unfazed 0.6.0 → 0.8.0

package/README.md

@@ -20,8 +20,11 @@ SDK:  one script. Three requests. You read the four lines you cared about.
 - Zero runtime dependencies. Installing `unfazed` installs exactly one package.
   (The optional [`unfazed/workflow`](#durable-workflows-unfazedworkflow) subpath
   uses Workflow SDK packages your app installs; the root entry never loads them.)
-- `npx workflow inspect runs --backend unfazed`: Workflow SDK's CLI and web UI
-  read your app's runs through the platform ([details](#inspect-runs-from-your-terminal)).
+- `npx unfazed login` signs you in from a terminal in the browser; the SDK then
+  acts as you, with no token to copy ([details](#sign-in-from-a-terminal-npx-unfazed)).
+- `npx unfazed workflow inspect runs --app <alias>`: Workflow SDK's CLI and web
+  UI read your app's runs through the platform, from any directory
+  ([details](#inspect-runs-from-your-terminal)).
 - Strict TypeScript, generated from the platform's own GraphQL schema.
 - Bun-first, runs unchanged on Node >= 20 and Deno.
 
@@ -33,27 +36,79 @@ bun add unfazed     # or: npm i unfazed
 
 ## Auth
 
-Get a token from <https://unfazed.dev/auth.md> (or `POST
-https://unfazed.dev/agents/register`). The SDK reads `UNFZ_API_TOKEN`:
+**A person** signs in once from a terminal, in the browser
+([`npx unfazed login`](#sign-in-from-a-terminal-npx-unfazed)); the SDK then acts
+as them, with their apps, teams and claimed agents:
+
+```sh
+npx unfazed login
+```
+
+**An agent or a CI job** uses a bearer token instead: an agent registers itself
+at <https://unfazed.dev/auth.md> (`POST https://unfazed.dev/agents/register`).
+The SDK reads `UNFZ_API_TOKEN`, which wins over a stored login:
 
 ```sh
 export UNFZ_API_TOKEN="..."
 ```
 
 ```ts
-const unfazed = new Unfazed();                       // reads UNFZ_API_TOKEN
-const unfazed = new Unfazed({ token });              // or pass it explicitly
+const unfazed = new Unfazed();          // UNFZ_API_TOKEN, else your `npx unfazed login`
+const unfazed = new Unfazed({ token }); // or pass a token explicitly
 ```
 
 Both endpoint and token are configurable. `UNFZ_API_URL` overrides the endpoint
-(default `https://unfazed.dev/query`); `baseUrl` is a convenience for
-self-hosted control planes where only the host differs.
+(default `https://unfazed.dev/query`, or the stored login's); `baseUrl` is a
+convenience for self-hosted control planes where only the host differs.
 
 ```ts
 new Unfazed({ token, baseUrl: "https://staging.example.com" });   // → /query
 new Unfazed({ token, endpoint: "https://example.com/graphql" });  // exact
 ```
 
+## Sign in from a terminal: `npx unfazed`
+
+The package's `unfazed` bin signs a person in, the way `vercel login` does. It
+runs from any directory (`npx` fetches the package when the directory has no
+`unfazed`), on Node >= 20.16 or Bun, with no dependencies.
+
+```sh
+npx unfazed login      # opens the browser; you sign in and allow access
+npx unfazed whoami     # who the SDK acts as here
+npx unfazed logout     # revokes the login where the server offers it, and deletes it
+```
+
+```
+$ npx unfazed login
+Opening your browser to sign in to https://unfazed.dev.
+…
+Signed in to https://unfazed.dev as ada (user).
+The login is stored in /home/ada/.config/unfazed/credentials.json.
+```
+
+- **How:** OAuth 2.1 with PKCE against the platform's own authorization server,
+  the one MCP clients sign in through. The CLI registers itself once as a
+  public client (cached in `oauth-clients.json` beside the login), listens on
+  `http://127.0.0.1:<random port>/callback` for the answer, and asks for
+  `unfz:read unfz:deploy` (`--scope` narrows it).
+- **The login** is `${XDG_CONFIG_HOME:-~/.config}/unfazed/credentials.json`,
+  mode 0600: the access token (an hour long), the refresh token (30 days, rotated
+  on every refresh), the expiry, the endpoint and who signed in. The SDK uses it
+  whenever no token is passed and `UNFZ_API_TOKEN` is unset, refreshes the access
+  token before it expires (and once when the platform refuses it), and writes
+  the rotated pair back for the next process. It is only ever sent to the
+  endpoint it was issued by; another `UNFZ_API_URL` needs its own
+  `UNFZ_API_URL=… npx unfazed login`. `new UnfazedClient({ login: false })`
+  ignores it.
+- **A browser on another machine** (an SSH session, a box): the URL is printed
+  instead of opened. Sign in there, then paste the address the browser ends up
+  on (`http://127.0.0.1:…/callback?code=…`, which does not load there) into the
+  terminal. `--no-browser` prints the URL on your own machine too.
+- **Another control plane:** `--endpoint https://staging.example.com` (or
+  `UNFZ_API_URL`).
+- `whoami --json` prints the same as JSON; nothing the CLI prints ever carries
+  a token.
+
 ## Code mode: deploy, wait, tail logs, in one script
 
 ```ts
@@ -64,8 +119,8 @@ const unfazed = new Unfazed();
 
 const ws = await unfazed.createWorkspace("greeter");
 
-// One request, not three — batched as aliased mutations.
-await unfazed.writeFiles(ws.id, {
+// One request, not three — and ONE commit on an app with platform git.
+const written = await unfazed.writeFiles(ws.id, {
   "server.ts": `
     export default {
       fetch(req: Request) {
@@ -76,7 +131,8 @@ await unfazed.writeFiles(ws.id, {
   `,
   "unfazed.json": JSON.stringify({ entry: "server.ts" }),
   "README.md": "# greeter",
-});
+}, { commitMessage: "First version" });
+console.log(written.commit?.sha ?? "no platform git");
 
 try {
   // Blocks until the build, VM boot and health probe all pass.
@@ -86,6 +142,8 @@ try {
     wait: true,
   });
   console.log(`live: ${app.url}`);
+  // What the platform measured, and what this script waited.
+  console.log(app.timings?.platform?.totalMs, app.timings?.client.totalMs);
 
   // Verify it for real before trusting the alias.
   const res = await fetch(`${app.url}?name=agent`);
@@ -109,6 +167,17 @@ try {
 }
 ```
 
+## Every signature, from a script: `help()`
+
+`help()` returns [REFERENCE.md](REFERENCE.md): every method with its
+signature, result and an example, in one page. `help("writeFiles")` is one
+entry, `help("Events")` one section. A Code Mode script (MCP `run_script`) can
+`export default () => help("restoreVersion")` to read it without leaving the
+tool. The platform serves the reference of the version it vendors at
+https://unfazed.dev/sdk.md; a run_script result's `sdk_version` (or
+`VERSION` in the script) names the version a script actually ran, which lags
+for a while after a release (it ships with the platform's worker releases).
+
 ## Two layers
 
 ### 1. Typed GraphQL core — `UnfazedClient`
@@ -133,7 +202,8 @@ const data = await client.query<{ workspaces: { id: string }[] }, never>(
 Errors are typed and specific: `UnfazedAuthError`, `UnfazedHTTPError` (carries
 `status`/`body`), `UnfazedGraphQLError` (carries `errors` **and any partial
 `data`**), `UnfazedTimeoutError`, `UnfazedDeployError`, `UnfazedConflictError`,
-`UnfazedNotFoundError`. All extend `UnfazedError`.
+`UnfazedNotFoundError`, `UnfazedWriteError` (carries the write's `result` and
+the `failed` paths). All extend `UnfazedError`.
 
 ### 2. Workflow layer — `Unfazed`
 
@@ -151,14 +221,17 @@ The chains an agent actually performs. Reach `client` from it any time:
 | `createWorkspace(name)` | names are unique per owner, case-insensitively |
 | `ensureWorkspace(name)` | get-or-create; **use this in re-runnable scripts** |
 | `listWorkspaces()` | |
-| `deleteWorkspace(id, opts?)` | cascades to deployments by default; also destroys a BOX's data disk |
+| `liveApps(id)` | the apps the workspace serves now: what a cascading delete takes offline |
+| `deleteApp({ workspaceId, alias }, opts?)` | deletes ONE app; the workspace and its other apps keep serving |
+| `deleteWorkspace(id, opts?)` | with deployments only via `{ withDeployments: true, confirmAliases }` naming every live app; also deletes a BOX's data disk |
 
 **Files**
 | Method | Notes |
 | --- | --- |
-| `writeFiles(wsId, files, opts?)` | **batched** — many files per request |
-| `writeFile(wsId, path, text)` | |
-| `writeBinaryFile(wsId, path, bytes)` | base64 under the hood |
+| `writeFiles(wsId, files, opts?)` | **one request, one commit** (MCP `write_workspace_files`); `commitMessage`; answers the `commit` |
+| `writeFile(wsId, path, text, opts?)` | a one-file `writeFiles`; answers the file and its `commit` |
+| `writeBinaryFile(wsId, path, bytes, opts?)` | base64 under the hood |
+| `waitForCommit(wsId)` | resolves once no write waits for its commit (see "Saved, committed, deployed") |
 | `listFiles(wsId, page?)` | |
 | `readFile(wsId, path, range?)` | |
 | `deleteFile(wsId, path)` | |
@@ -166,11 +239,11 @@ The chains an agent actually performs. Reach `client` from it any time:
 **Deploy**
 | Method | Notes |
 | --- | --- |
-| `deployService(opts)` | `wait: true` polls to READY |
+| `deployService(opts)` | `wait: true` waits server-side to READY; the result carries `timings` |
 | `deployStatic(opts)` | `spaMode` for single-page apps |
 | `deployBox(opts)` | persistent Linux VM; result carries `sshCommand` |
 | `deploy(input, opts?)` | raw `CreateDeploymentInput` escape hatch |
-| `waitForDeployment(id, opts?)` | standalone poller |
+| `waitForDeployment(id, opts?)` | the server-side wait (MCP `wait_for_deployment`); polls on older platforms |
 | `getDeployment(id)` / `getDeploymentByAlias(alias)` | |
 | `listDeployments(filter?)` | |
 
@@ -179,7 +252,8 @@ The chains an agent actually performs. Reach `client` from it any time:
 | --- | --- |
 | `getLogs(id, { tailBytes })` | stdout + stderr tail |
 | `getStatus(id)` | health, in-flight, restarts, `memSizeMiB` |
-| `getEvents(id, limit?)` | build/boot/probe/cron lifecycle events |
+| `getEvents(id, limit?)` | lifecycle events; `type` is the dotted name MCP shows (`deployment.build_finished`), `typeEnum` the GraphQL enum |
+| `getDeploymentTimings(id)` | the platform's measured phases, as numbers |
 | `restartService(id)` / `stopService(id)` | |
 | `deleteDeployment(id, opts?)` | `ignoreNotFound` for idempotent cleanup |
 
@@ -198,6 +272,27 @@ The chains an agent actually performs. Reach `client` from it any time:
 | `listReleases(alias)` | newest first; one entry has `aliasHeld: true` |
 | `rollback({ alias, to?, expectedCurrentId?, retries? })` | **whole compare-and-swap in one call** |
 
+**History (platform git)**
+| Method | Notes |
+| --- | --- |
+| `listCommits(wsId, { limit?, before? })` | newest first; `deployed` says what each alias runs (MCP `list_commits`) |
+| `getCommit(wsId, sha)` | the changed paths and a unified diff (MCP `get_commit`) |
+| `restoreVersion({ workspaceId, sha, wait? })` | one new commit with that commit's files; `wait: true` follows its deploy to READY (MCP `restore_version`) |
+
+**App errors**
+| Method | Notes |
+| --- | --- |
+| `listErrors({ workspaceId, alias, status? })` | a service app's error groups (MCP `list_errors`) |
+| `getErrorGroup({ workspaceId, alias, groupId })` | the latest occurrence whole, and where it was seen |
+| `resolveErrorGroup` / `muteErrorGroup` / `reopenErrorGroup` | same ref; only on your human's say-so |
+
+**Events**
+| Method | Notes |
+| --- | --- |
+| `listEventTypes()` | every type with its filters and payload |
+| `pollEvents({ names?, arguments?, cursor? })` | MCP `poll_events`; the same cursors |
+| `waitForEvents({ …, timeoutMs? })` | blocks server-side until an event arrives (MCP `wait_for_events`) |
+
 **Agent runs**
 | Method | Notes |
 | --- | --- |
@@ -214,25 +309,53 @@ The chains an agent actually performs. Reach `client` from it any time:
 
 ## The two things worth knowing
 
-### `writeFiles` batches, because the API is one-file-per-mutation
+### `writeFiles` is one request and one commit
 
-Writing a 12-file app the obvious way costs 12 round trips. `writeFiles` puts
-one **aliased** mutation per file into a single GraphQL document:
+`writeFiles` sends every file in one `writeWorkspaceFiles` mutation, the one
+MCP's `write_workspace_files` uses. Text and binary mix freely. On an app with
+platform git the whole call is ONE commit, made before any file is written,
+with your `commitMessage`; the answer carries it:
 
-```graphql
-mutation SdkWriteFilesBatch($workspaceID: ID!, $p0: String!, $c0: String!, ...) {
-  f0: writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $p0, text: $c0 }) { file { ... } }
-  f1: writeWorkspaceBase64File(input: { workspaceID: $workspaceID, path: $p1, contentBase64: $c1 }) { file { ... } }
-}
+```ts
+const out = await unfazed.writeFiles(ws.id, { "server.ts": code, "package.json": pkg }, { commitMessage: "Add the API" });
+out.commit;  // { sha, branch, message, committed, waiting, waitingCount, deploys, conflicts, writeSHA, paused }
 ```
 
-Text and binary mix freely in one batch. It splits automatically at 20 files or
-4 MiB per request (`batchSize`, `maxBatchBytes`).
-
-Batches are **not atomic** — GraphQL resolves each field independently. If one
-path fails, the others still commit; the thrown `UnfazedGraphQLError` carries
-`data` with the aliases that succeeded and `errors[].path` naming the ones that
-didn't.
+A call is **not transactional**, exactly as MCP's: files are written in order,
+each atomically, and one failing does not undo the others. Then `writeFiles`
+throws `UnfazedWriteError`, whose `result` lists what landed and `failed` what
+did not — retry only those, or pass `allowPartial: true` to get the result
+instead. A request carries up to 100 files and 32 MiB (the platform's limits);
+a bigger map is split, one commit per request (`commits`). On a platform older
+than the batch mutation the SDK falls back to one aliased mutation per file in
+one request (one commit each, `commit: null`).
+
+### Saved, committed, deployed
+
+- **Saved** — `writeFiles` returned: the app's files have it; the next deploy
+  uses it.
+- **Committed** — `commit.committed && !commit.waiting`: it is in the app's
+  history (`listCommits`). When the git server is slow the commit comes back
+  `waiting` (`sha: null`): saved, landing in order, nothing to retry.
+  `writeFiles(…, { waitForCommit: true })` or `waitForCommit(wsId)` resolves
+  once it has landed, with the branch head.
+- **Deployed** — a deploy of those files went READY: `deployService({ wait:
+  true })`. A write deploys by itself only when `commit.deploys` is true (the
+  branch head is imported like a push).
+
+### Waiting is server-side, and you get both clocks
+
+`deployService({ wait: true })` and `waitForDeployment` wait on the platform
+(MCP `wait_for_deployment`): each request blocks until the deployment leaves
+BUILDING — woken by the deploy pipeline — or 45 s pass, and answers with the
+full deployment. READY reaches the script one round trip after it happens.
+Before 0.8.0 the SDK polled at 1 s × 1.5 backoff and re-read the deployment in
+full: a deploy READY after 6.8 s was seen at about 8.1 s and returned at 9.0 s.
+
+The result carries `timings`: `platform` is what the platform measured
+(`totalMs` from creation to READY, `buildMs`, `promoteMs`, and every phase in
+`phases`), `client` what the script waited (`createMs`, `waitMs`, `totalMs`,
+`waitRequests`, `waitMode`). `timings: false` skips the one extra read.
 
 ### `rollback` does the compare-and-swap for you
 
@@ -306,26 +429,79 @@ what the first one did:
 | `deployBox({ workspaceId })` | `deployBox({ workspaceId, alias })` | no alias ⇒ a brand-new box each time |
 | `rollback({ alias })` | `rollback({ alias, to })` or `expectedCurrentId` | bare rollback is a toggle |
 | `deleteWorkspace(id)` throwing | `deleteWorkspace(id, { ignoreNotFound: true })` | already-deleted is not a failure |
+| `deleteApp({ workspaceId, alias })` throwing | `deleteApp({ workspaceId, alias }, { ignoreNotFound: true })` | same; resolves `null` |
 | `deleteDeployment(id)` throwing | `deleteDeployment(id, { ignoreNotFound: true })` | same |
 
-`ignoreNotFound` matches the server's two exact sentinels — `workspace was not
-found` and `deployment was not found` — and nothing else. A message that merely
-*contains* "not found" still throws, so a real failure can't be mistaken for a
-successful teardown. (Both sentinels also cover "belongs to another tenant": the
-server reports the two identically so ids can't be probed.)
-
-### Deleting a workspace cascades by default
-
-`deleteWorkspace` sends `withDeployments: true` unless you say otherwise. It has
-to: the server **refuses** to delete a workspace with any deployment history at
-all — including FAILED-only history — without that flag, so the strict form
-fails on nearly every workspace that was ever deployed.
+`ignoreNotFound` matches the server's exact refusals — `workspace was not
+found`, `deployment was not found`, and for `deleteApp` `app "<alias>" was not
+found in workspace "…"` naming that alias — and nothing else. A message that
+merely *contains* "not found" still throws, so a real failure can't be mistaken
+for a successful teardown. (The two sentinels also cover "belongs to another
+tenant": the server reports the two identically so ids can't be probed.)
+
+### Deleting names what goes
+
+A workspace is a source, and one source can serve several apps: each
+`unfazed.json` `apps[]` entry, or several aliases deployed into it. A delete is
+never wider than what you name:
+
+- **`deleteApp({ workspaceId, alias })` deletes one app**: every deployment of
+  the alias in that workspace (its VM stops, its URL and custom domains stop
+  serving), its App State, its app-scoped env and secrets, and its integration
+  bindings. The workspace, its files and defaults, its other apps and a box's
+  data disk stay. The result says what went (`deployments`, `domains`,
+  `envEntries`) and what still serves (`otherApps`). In a git-linked workspace
+  pushes and syncs skip the alias while `unfazed.json` `apps[]` still declares
+  it (`skippedOnSync: true`); remove it from `apps[]`, or bring it back with
+  the GraphQL `syncRepo` mutation's `restoreApps`. A delete that stops
+  part-way throws saying so; deleting again finishes it.
+- **`deleteWorkspace(id, { withDeployments: true, confirmAliases })` deletes the
+  workspace with every app it serves**, so `confirmAliases` must name exactly
+  those apps, in any order. A missing or extra alias, or an app that went live
+  after the check, makes the server delete nothing and refuse with
+  `UnfazedUnconfirmedAppsError` (still an `UnfazedGraphQLError`), whose message
+  is the server's: it lists every live app with its custom domains. A
+  workspace whose deploys all failed serves no app: `confirmAliases: []`.
+- **`deleteWorkspace(id)`** deletes only a workspace with no deployment records
+  left; otherwise the server refuses with `still has deployments; delete them
+  first`.
+
+The SDK never fills `confirmAliases` in for you. `liveApps(id)` is there to look
+the list up deliberately — read it, then name what you mean to take down:
 
 ```ts
-await unfazed.deleteWorkspace(ws.id);                             // cascade (default)
-await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
+await unfazed.liveApps(ws.id);
+// [{ alias: "api", deploymentID: "…", domains: ["api.example.com"] },
+//  { alias: "web", deploymentID: "…", domains: [] }]
+
+// Either one app — "web" keeps serving:
+await unfazed.deleteApp({ workspaceId: ws.id, alias: "api" });
+
+// or the workspace with every app it serves, each named:
+await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: ["api", "web"] });
+
+// Naming fewer (or more) deletes nothing and throws:
+await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: ["web"] });
+// UnfazedUnconfirmedAppsError: unfazed: nothing was deleted: workspace "shop" (…) serves 2 apps:
+// api (api.example.com); web. Deleting it takes every one of them offline. To delete one app,
+// use deleteApp (MCP delete_app). To delete the workspace with all of them, name exactly these
+// aliases in confirmAliases.
 ```
 
+**Deleted is kept for 30 days.** A delete takes effect at once: the app,
+release or workspace disappears from your views, its name and alias are free
+for anyone, and it stops serving. The platform keeps what you deleted — its
+files, releases with their env and secrets, App State, box disk, integration
+resources and custom domains — for 30 days. Within that time support (the
+platform operator) can restore it exactly as it was; you cannot restore it
+yourself, so ask support. After 30 days it is erased for good. This holds for
+`deleteApp`, `deleteWorkspace` and `deleteDeployment` alike.
+
+**Upgrading from 0.6.** `deleteWorkspace(id)` used to send `withDeployments:
+true` with no apps named; the server now refuses that whenever the workspace
+serves an app. From 0.7 the bare call is the strict delete, and a cascade takes
+`{ withDeployments: true, confirmAliases }`. To remove one app, use `deleteApp`.
+
 ## Env & secrets: three states, not two
 
 A name in a given scope is exactly one of **plain**, **secret**, or **masked**,
@@ -446,25 +622,38 @@ to the app as well.
 
 ### With Nitro (the recipe)
 
+The app deploys in Nitro's own layout, as the platform's "Deploying a Nitro
+app" describes, with no re-export file:
+
+```ts
+// server.ts — the app itself; Nitro takes a root server.ts as its server entry
+import { Hono } from "hono";
+
+const app = new Hono();
+// … routes that start() workflows
+export default app;
+```
+
 ```ts
 // nitro.config.ts
 import { defineConfig } from "nitro";
 
 export default defineConfig({
   modules: ["workflow/nitro", "unfazed/workflow/nitro"],
-  routes: { "/**": "./src/app.ts" },   // a Hono app; not named server.ts (Nitro claims that name)
 });
 ```
 
 ```json
-// unfazed.json — package.json has "build": "nitro build"
-{ "kind": "SERVICE", "runtime": "BUN", "install": "bun install", "build": "bun run build", "entry": "unfazed-entry.ts" }
+// unfazed.json — no "entry"
+{ "kind": "SERVICE", "build": "nitro build" }
 ```
 
-```ts
-// unfazed-entry.ts
-export { default } from "./.output/server/index.mjs";
-```
+With no `entry` in unfazed.json and a `standard` Nitro build, unfazed serves
+`.output/server/index.mjs`; the build log says `using Nitro output
+.output/server/index.mjs as the service entry`. Do not set `entry` or add an
+`unfazed-entry.ts` re-export: an explicit entry replaces the Nitro output.
+Install and build commands find the app's `node_modules/.bin` CLIs on PATH, so
+`"build": "bun run build"` over a package.json script works as well.
 
 Then bind a Postgres or Neon integration to the app and deploy. In a
 production build the module:
@@ -481,14 +670,16 @@ production build the module:
 - mounts the **inspection route** the unfazed dashboard and MCP read runs
   through (below), with the build's workflow list and Workflow SDK version;
 - sets `noExternals: true` and builds Nitro's `standard` output (`export
-  default { fetch }`), which is what unfazed serves, whenever no preset was
+  default { fetch }`, recorded as `"preset": "standard"` in
+  `.output/nitro.json`), which is what unfazed serves, whenever no preset was
   chosen, whatever Nitro detected on the build machine: `bun` under Bun (as on
   the unfazed build VM), `node-server` under Node, `deno-server` under Deno.
   Their own outputs start a server of their own (under Bun with a 10 s idle
   timeout that cuts every quiet workflow stream). A preset chosen explicitly
   (`preset` in nitro.config.ts or .nitrorc, `NITRO_PRESET`, `SERVER_PRESET`)
   other than `standard` **fails the build** with a message saying so; leave it
-  out, or set `preset: "standard"`.
+  out, or set `preset: "standard"`. A Nitro app without this module sets both
+  itself: `defineConfig({ preset: "standard", noExternals: true })`.
 - serves public assets only when `serveStatic: "inline"` embeds them in the
   bundle (a service VM has nothing next to it to read from disk). That is how
   one service ships an API and its UI (`publicAssets: [{ dir: "dist" }]`
@@ -499,8 +690,12 @@ production build the module:
 A complete app — steps, a retried step, `sleep`, a webhook (plain
 `createWebhook()` and `webhook.url`), a progress stream — is in
 [`examples/workflow-nitro`](./examples/workflow-nitro). Once it is deployed,
-`UNFZ_APP=<alias> npx workflow inspect runs --backend unfazed` lists its runs
+`npx unfazed workflow inspect runs --app <alias>` lists its runs
 ([Inspect runs from your terminal](#inspect-runs-from-your-terminal)).
+[`examples/birthday-card-generator`](./examples/birthday-card-generator) is
+Vercel's Workflow launch demo on unfazed: a React UI built by Vite and served
+from the same bundle, AI steps, webhooks resumed from emails, `sleep` until a
+date, and a stream the UI reconnects to; it runs without any provider keys.
 
 ### Without Nitro
 
@@ -569,12 +764,11 @@ database connection afterwards; `wake` and `cancel` are Workflow SDK's own
 ### Inspect runs from your terminal
 
 Workflow SDK's own CLI reads an app's runs through the platform, the way
-`--backend vercel` reads a Vercel project. From the app's project (where
-`unfazed` is installed; the CLI loads `createWorld()` from it):
+`--backend vercel` reads a Vercel project. From any directory:
 
 ```sh
-export UNFZ_API_TOKEN=...          # a token from https://unfazed.dev/auth.md
-UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
+npx unfazed login                                       # once
+npx unfazed workflow inspect runs --app birthday-card
 ```
 
 ```
@@ -586,25 +780,38 @@ wrun_01KPBDAY00000000000000RN03  generateBirthdayCard  failed     2026-10-15 09:
 ```
 
 ```sh
-npx workflow inspect run <run-id> --backend unfazed               # input, output, error
-npx workflow inspect steps --runId <run-id> --backend unfazed     # also: events, hooks, sleeps, streams
-npx workflow inspect step <step-id> --runId <run-id> --backend unfazed
-npx workflow inspect stream <stream-id> --runId <run-id> --backend unfazed   # follows it while the run writes
-npx workflow cancel <run-id> --backend unfazed
-npx workflow web --backend unfazed                                # the local web UI: trace, events, streams,
-                                                                  # Wake Up Sleep and Cancel
+npx unfazed workflow inspect run <run-id> --app birthday-card            # input, output, error
+npx unfazed workflow inspect steps --runId <run-id> --app birthday-card  # also: events, hooks, sleeps, streams
+npx unfazed workflow inspect step <step-id> --runId <run-id> --app birthday-card
+npx unfazed workflow inspect stream <stream-id> --runId <run-id> --app birthday-card   # follows it while the run writes
+npx unfazed workflow cancel <run-id> --app birthday-card
+npx unfazed workflow web --app birthday-card     # the local web UI: trace, events, streams,
+                                                 # Wake Up Sleep and Cancel
+```
+
+`npx unfazed workflow …` is Workflow SDK's CLI with this package as its
+backend: everything after `workflow` but `--app` is passed to it, and its
+output and exit code come back unchanged. It runs the project's own
+`workflow` (major 5) when the directory has one, else `npx -y workflow@5`.
+
+**Inside a project** that has `unfazed` installed, the CLI's native form works
+too, since the CLI resolves `--backend unfazed` from the project:
+
+```sh
+UNFZ_APP=birthday-card npx workflow inspect runs --backend unfazed
 ```
 
-The usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
+`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend` there. The
+usual options work (`--json`, `--limit`, `--cursor`, `--all`, `--status`,
 `--workflowName`, `--interactive`); the exceptions are below.
-`export WORKFLOW_TARGET_WORLD=unfazed` saves typing `--backend`.
-
-- **Which app:** `UNFZ_APP` (its alias, the `<alias>` of
-  `https://<alias>.unfz.to`); without it, the `alias` in `./unfazed.json`, or
-  its only `apps[]` entry. `UNFZ_API_URL` points at another control plane.
-- **The token** needs `unfz:read`; cancel and Wake Up Sleep need `unfz:deploy`
-  too, and the caller must be allowed to restart the app (owner, team member,
-  operator).
+
+- **Which app:** `--app` (`npx unfazed workflow` only), else `UNFZ_APP` (its
+  alias, the `<alias>` of `https://<alias>.unfz.to`), else the `alias` in
+  `./unfazed.json`, or its only `apps[]` entry. `UNFZ_API_URL` points at
+  another control plane.
+- **The token** is your `npx unfazed login`, or `UNFZ_API_TOKEN` when set. It
+  needs `unfz:read`; cancel and Wake Up Sleep need `unfz:deploy` too, and the
+  caller must be allowed to restart the app (owner, team member, operator).
 - **Every command is one platform call relayed to the app**, through the same
   inspection route the dashboard reads; an `on_demand` app cold-starts for it,
   as for a visitor.
@@ -726,6 +933,7 @@ WORKFLOW_POSTGRES_URL=$UNFAZED_TEST_DATABASE_URL bun run test:conformance
                                                    # delivery cold-started in a fresh process
 bun run test:example                               # the example, bundled as unfazed builds it,
                                                    # one fresh process per delivery and request
+bun run test:birthday                              # the same for examples/birthday-card-generator
 bun run test:cli                                   # Workflow SDK's CLI with --backend unfazed (and --web)
                                                    # against a fake of the platform's inspection API
 ```
@@ -745,6 +953,11 @@ After bumping the `@workflow/world-postgres` devDependency, run
 `bun run embed-migrations`: `bun run check` fails while
 `src/workflow/migrations.generated.ts` is stale.
 
+`REFERENCE.md` is what `help()` returns: after editing it run
+`bun run embed-reference` (`bun run check` fails while
+`src/reference.generated.ts` is stale). `test/reference.test.ts` fails when a
+public method of `Unfazed` is missing from it.
+
 ### Regenerating from the schema
 
 `schema/schema.graphqls` is a **vendored copy** of `graph/schema.graphqls` from
@@ -783,6 +996,14 @@ bun run check          # typecheck + tests + build + dist smoke
 npm publish            # or: bun publish --access public
 ```
 
+Then bring the release to Code Mode: MCP `run_script` runs a copy of the SDK
+vendored in the unfazed repo, not npm's. There, `hack/update-script-sdk.sh
+<version>` vendors the published tarball (checked against npm's integrity),
+and a worker release ships it, since scripts run on workers (unfazed
+`docs/code-mode.md`, "Shipping a new SDK"). Its `script-sdk` check turns red
+within a day of a publish that was not vendored. A release that needs new
+platform fields goes out after the platform change that adds them.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).