@extrovert.dev/sdk 0.1.0-pre.5 → 0.1.0-pre.7

package/README.md

@@ -4,19 +4,19 @@
 
 **A real inbox for your agent, in one call.**
 
-The TypeScript SDK for [Extrovert](https://extrovert.dev) — Message Science's agent-email
+The TypeScript SDK for [Extrovert](https://extrovert.dev): Message Science's agent-email
 platform. Extrovert gives an AI agent a real, persistent inbox on a domain we own: created in one
 call, sends and receives, behind a scoped key that expires and revokes on its own.
 
-- **One call to a live inbox.** `agent7@smtp.extrovert.dev`, sending and receiving, on a
-  pre-verified `smtp.extrovert.dev` subdomain — no DNS, no waiting.
+- **One call to a live inbox.** Paid accounts use `agent7@extrovertmail.com`; free
+  signups use `agent7@free.extrovertmail.com`. No DNS setup is required.
 - **`waitForEmail`, the killer primitive.** Block until the next matching message lands and get the
   OTP code / verification link extracted as a structured field. No polling loop.
 - **Typed everything.** Request and response models matching the Extrovert `/v1` contract, a typed
   `ApiError` hierarchy, full `.d.ts` declarations.
 - **Runs where your agent runs.** Pure `fetch`. Node 18+, Cloudflare Workers, Vercel Edge, Deno,
   the browser. Zero runtime dependencies.
-- **Don't hand an MCP host your master key.** Redeem a scoped enrollment key; mint an agent key that
+- **Don't hand an MCP host your master key.** Redeem a scoped enrollment key; issue an agent key that
   expires and revokes on its own.
 
 ---
@@ -30,7 +30,7 @@ for a stable release:
 npm install @extrovert.dev/sdk@next
 ```
 
-Pin `@extrovert.dev/sdk@0.1.0-pre.5` when a dogfood test needs a reproducible contract snapshot.
+Pin `@extrovert.dev/sdk@0.1.0-pre.7` when a dogfood test needs a reproducible contract snapshot.
 Requires Node 18+ for global `fetch` and Web Crypto.
 
 ## Build and use from source
@@ -48,7 +48,11 @@ REST API and served OpenAPI document remain the underlying contract.
 
 ---
 
-## Quickstart — inbox in one call
+## Quickstart: inbox in one call
+
+Use the scoped key issued for this agent on your existing account. Do not sign up for another
+account to connect a new agent. Confirm the connection with `extrovert.whoami()` before creating
+resources; its capability summary explains what the connection can do.
 
 ```ts
 import { Extrovert, isQueuedForReview } from "@extrovert.dev/sdk";
@@ -57,10 +61,10 @@ const extrovert = new Extrovert({ apiKey: process.env.EXTROVERT_API_KEY! });
 
 // One call. A real, send-and-receive-capable inbox.
 const inbox = await extrovert.inboxes.create({ display_name: "Support Bot" });
-console.log(inbox.address); // agent7@smtp.extrovert.dev
+console.log(inbox.address); // agent7@extrovertmail.com
 
 // Queue a message for a human. `intent.summary` is what the reviewer reads
-// first, and it is REQUIRED — under the default `require_review` policy a send
+// first, and it is REQUIRED: under the default `require_review` policy a send
 // without one is refused 422 `intent_required` (nothing sent, nothing queued).
 const outcome = await inbox.send({
   to: "ops@acme.test",
@@ -77,17 +81,56 @@ if (isQueuedForReview(outcome)) {
 
 **Your agent queues mail; it does not send it.** A message parks as a review request, a human
 approves / edits / rejects it, and your agent watches for that outcome and redrafts as needed.
-`allow_direct` inboxes and graduated categories are the exceptions, not the default — read
+`allow_direct` inboxes and graduated categories are the exceptions, not the default: read
 `inbox.record?.effective_review_policy` once rather than learning the policy by being refused. The
 other half of the loop is the [agent contract](https://docs.extrovert.dev/review-loop/agent-contract/).
 
-`inboxes.create()` returns an `InboxHandle` — an ergonomic handle bound to one address, so the rest
+`inboxes.create()` returns an `InboxHandle`: an ergonomic handle bound to one address, so the rest
 of your agent code reads naturally: `inbox.send(...)`, `inbox.messages()`, `inbox.waitForEmail(...)`,
 `inbox.delete()`. This is the curl-style sugar that resolves to your key's default project.
 
 ---
 
-## The canonical chain — `projects.inboxes.*`
+## Check whether your domain is ready
+
+```ts
+const domain = await extrovert.domains.get("mail.example.com");
+const readiness = domain.readiness;
+if (!readiness) throw new Error("This server did not return domain readiness.");
+console.log(readiness.label, readiness.summary);
+console.log(readiness.inboxes); // counts visible to this connection, not a global total
+
+if (readiness.ready_for_inboxes && readiness.next_action === "create_inbox") {
+  console.log("Ready to create an inbox when you want one.");
+} else if (readiness.action_required_by === "extrovert") {
+  console.log("Extrovert is handling the next steps. No DNS changes are needed.");
+}
+
+// A deliberate recheck verifies the DNS entries now; ordinary reads do not.
+// Use after publishing/fixing the entries, not in a tight polling loop.
+await extrovert.domains.verify("mail.example.com");
+
+// Wait at most 45 seconds. A timeout does not stop background setup.
+const waiting = await extrovert.domains.wait("mail.example.com", { timeout_seconds: 45 });
+if (waiting.outcome === "timed_out") {
+  console.log(`Resume checking in ${waiting.resume_after_seconds} seconds.`);
+}
+
+// Persist next_cursor privately and pass it as after on the next check.
+const updates = await extrovert.domains.events("mail.example.com", { after: "0", limit: 50 });
+for (const event of updates.items) console.log(event.summary);
+```
+
+`waiting_for_dns` means your DNS entries are not confirmed yet; `setting_up` means Extrovert is
+finishing setup. `ready` means mail setup is complete. `action_required` identifies a customer DNS
+repair; `needs_attention` identifies work for Extrovert. Temporary `checking` results are inconclusive,
+not a request to change DNS. Use the returned summary and next action when answering a person.
+
+Do not infer readiness from legacy verification or signing fields. Ready inboxes still follow their
+permissions, account limits, and review rules. Setup continues while your agent is disconnected, but
+the agent must stay connected or resume its event/status checks to receive updates.
+
+## The canonical chain: `projects.inboxes.*`
 
 Scope lives in your **key**, not in headers. A broad (org-tier) key narrows to one **project** by
 path; a project/inbox key is already pinned. The canonical, contract-aligned surface is the
@@ -98,13 +141,13 @@ within-project alias):
 const x = new Extrovert({ apiKey: process.env.EXTROVERT_API_KEY! });
 const { project_id } = await x.whoami();          // the key's fixed project
 
-// Create / send / list in a project — keyed by the opaque inbox_id.
+// Create / send / list in a project: keyed by the opaque inbox_id.
 const inbox = await x.projects.inboxes.create(project_id!, { username: "ada" });
 await x.projects.inboxes.send(project_id!, inbox.id, { to: "ops@acme.test", subject: "hi", text: "…",
   intent: { summary: "…one sentence for the human reviewer…" } });   // queues for review
 
 // One list envelope: { object: "list", data, has_more, next_cursor }. The ListPage
-// auto-paginates over OPAQUE cursors — never thread a cursor by hand.
+// auto-paginates over OPAQUE cursors: never thread a cursor by hand.
 const page = await x.projects.inboxes.list(project_id!, { limit: 50 });
 for await (const ib of page) console.log(ib.id);   // walks every page
 const all = await (await x.projects.inboxes.list(project_id!)).collect();  // eager
@@ -125,7 +168,7 @@ to opt into the server's transform shim.
 
 ---
 
-## The OTP flow — `waitForEmail`
+## The OTP flow: `waitForEmail`
 
 Agents sign up for things. The high-value, time-boxed task is "wait for the verification email and
 read the code." Extrovert holds the request open, polls the mailbox server-side, and hands you the extracted code.
@@ -165,7 +208,7 @@ of real warmup mail for years. Need it standalone? Import `extractOtp` / `extrac
 
 ## Try it offline (no API key, no network)
 
-Run the whole SDK against built-in, deterministic fixtures — no key, no network. Every method
+Run the whole SDK against built-in, deterministic fixtures: no key, no network. Every method
 works, including a synthesized `waitForEmail` OTP, and the mock models the real review policy,
 so a send without an `intent` is refused offline exactly as it would be live:
 
@@ -173,21 +216,25 @@ so a send without an `intent` is refused offline exactly as it would be live:
 const extrovert = new Extrovert({ transport: "mock" });
 const inbox = await extrovert.inboxes.create();
 const { extracted } = await inbox.waitForEmail();
-console.log(extracted.otp); // a fixture OTP — no network touched
+console.log(extracted.otp); // a fixture OTP: no network touched
 ```
 
 Set `EXTROVERT_API_BASE_URL=mock` to flip every client into offline mode from the environment.
 
+Offline domain setup remains `waiting_for_dns`: it does not query DNS, run background setup, or
+produce lifecycle events. Recheck does not fabricate a ready result. Use a test HTTP response for
+readiness transitions and resumable event scenarios; only the live service confirms actual setup.
+
 ---
 
-## Scoped keys — redeem an enrollment key
+## Scoped keys: redeem an enrollment key
 
-The identity model: a human (or org-admin call) **mints** a scoped `pk_enroll_...` enrollment key
+The identity model: a human (or org-admin call) **issues** a scoped `pk_enroll_...` enrollment key
 that can create up to *N* inboxes and nothing else. An agent **redeems** it for a short-lived,
 individually-revocable `pk_agent_...` key.
 
 ```ts
-// The agent is handed only the enrollment key — never an org-wide key.
+// The agent is handed only the enrollment key: never an org-wide key.
 const bootstrap = new Extrovert({ apiKey: process.env.EXTROVERT_ENROLLMENT_KEY! });
 
 const { client, enrollment } = await bootstrap.enrolled({
@@ -200,21 +247,21 @@ const { client, enrollment } = await bootstrap.enrolled({
 console.log(enrollment.agent_id, enrollment.scopes);
 console.log(enrollment.org_id, enrollment.project_id); // the key's fixed org + project
 
-// `client` is already authenticated with the minted agent key.
+// `client` is already authenticated with the issued agent key.
 const inbox = await client.inboxes.create();
 
-// The minted key is bound to a fixed org + project — visible via whoami, never selectable.
+// The issued key is bound to a fixed org + project: visible via whoami, never selectable.
 const me = await client.whoami();
 console.log(me.org_id, me.project_id, me.scopes);
 ```
 
 ---
 
-## Inbox metadata — attach your own key-value data
+## Inbox metadata: attach your own key-value data
 
 Every inbox carries an arbitrary `metadata` object (string / number / boolean values; ≤256 keys,
 ≤256 chars per key and per string value). Set it at create time, read it on every inbox shape, and
-patch it in place with shallow-merge / null-delete semantics — no delete+recreate.
+patch it in place with shallow-merge / null-delete semantics: no delete+recreate.
 
 ```ts
 // Set metadata at create time. It is echoed back on the inbox record.
@@ -235,30 +282,57 @@ const updated = await extrovert.inboxes.update(inbox.address, {
 console.log(updated.metadata); // { tier: 3, vip: true }
 ```
 
-Metadata is **project-scoped** — a key only reads/mutates inboxes in its bound project. Where the
+Metadata is **project-scoped**: a key only reads/mutates inboxes in its bound project. Where the
 API accepts a `project_id`, it is an **assertion** that must match the key's bound project (a
 mismatch is a 403), never a selector: the project is always derived from the key. See `whoami` for
 the fixed `org_id` / `project_id` the key is bound to.
 
 ---
 
-## Receiving mail — read, thread, reply
+## Receiving mail: read, thread, reply
 
 ```ts
-// List messages and threads in an inbox.
-const { data: messages } = await inbox.messages({ direction: "inbound" });
-const { data: threads } = await inbox.threads();
-
-// Reply in-thread (In-Reply-To / References handled server-side from IMAP).
-const first = messages[0];
-if (first) {
-  await extrovert.messages.reply(first.id, { text: "On it — thanks." });
+// Find a conversation. Pass next_cursor back unchanged to continue.
+const firstPage = await extrovert.threads.search(inbox.address, {
+  q: "deployment",
+  limit: 25,
+});
+const nextPage = firstPage.next_cursor
+  ? await extrovert.threads.search(inbox.address, {
+      q: "deployment",
+      limit: 25,
+      cursor: firstPage.next_cursor,
+    })
+  : undefined;
+
+// Read the complete oldest-first conversation before acting.
+const summary = firstPage.items[0];
+if (summary) {
+  const thread = await extrovert.threads.get(inbox.address, summary.id);
+  const authoredText = thread.messages.map((message) =>
+    message.extracted_text ?? message.text
+  );
+
+  // Recipients, subject, In-Reply-To, and References are derived server-side.
+  await extrovert.threads.reply(inbox.address, {
+    thread_id: thread.id,
+    expected_last_message_id: thread.last_message_id,
+    text: "On it — thanks.",
+    intent: { summary: "Acknowledge the deployment request." },
+    idempotency_key: "deployment-ack-v1",
+  });
 }
 ```
 
+If the thread advances first, `expected_last_message_id` returns a 409: fetch the thread again and
+reconsider the draft. It is an optimistic check at submission, not an atomic lock through delivery.
+
+For an inbox-bound style, use `inbox.threads(...)`, `inbox.searchThreads(...)`,
+`inbox.thread(...)`, `inbox.reply(...)`, and `inbox.deleteThread(...)`.
+
 ---
 
-## Webhooks — verified inbound, anywhere
+## Webhooks: verified inbound, anywhere
 
 Register an HMAC-signed, timestamped webhook, then verify deliveries with Web Crypto (works in Node
 and at the edge, no dependency):
@@ -272,11 +346,11 @@ const webhook = await extrovert.webhooks.register({
   url: "https://my-agent.example.com/inbound",
   events: ["message.received"],
 });
-// Store webhook.secret now — it is shown once.
+// Store webhook.secret now: it is shown once.
 
 // In your handler (Workers / Vercel Edge / Node):
 export async function POST(req: Request) {
-  const payload = await req.text(); // raw body — do not re-serialize
+  const payload = await req.text(); // raw body: do not re-serialize
   const ok = await verifyWebhookSignature({
     payload,
     signature: req.headers.get("x-extrovert-signature")!,
@@ -308,12 +382,12 @@ new Extrovert({
 
 | Option       | Env                     | Default                              |
 | ------------ | ----------------------- | ------------------------------------ |
-| `apiKey`     | `EXTROVERT_API_KEY`       | — (required for `http` transport)    |
+| `apiKey`     | `EXTROVERT_API_KEY`       |: (required for `http` transport)    |
 | `baseUrl`    | `EXTROVERT_API_BASE_URL`  | `https://api.extrovert.dev`      |
 | `transport`  | (`baseUrl=mock`)        | `http`                               |
-| `timeoutMs`  | —                       | `30000`                              |
+| `timeoutMs`  |:                       | `30000`                              |
 
-Idempotency: pass `client_id` to `inboxes.create()` and `idempotency_key` to `send` / `reply` —
+Idempotency: pass `client_id` to `inboxes.create()` and `idempotency_key` to `send` / `reply` :
 retries won't duplicate. Cursor pagination: list responses carry `next_cursor`; pass it back as
 `cursor`.
 
@@ -326,15 +400,15 @@ Every non-2xx response throws a typed error extending `ApiError`. Branch on the
 ```ts
 import {
   ApiError,
-  AuthenticationError,  // 401 — key missing / expired / revoked
-  PermissionError,      // 403 — scope denied
-  ForbiddenScopeError,  // 403 forbidden_scope — out of the key's ceiling / non-org key on the wildcard
-  BreadthRequiredError, // 400 breadth_required — org key on a bare list must pick a project / "-"
-  NotFoundError,        // 404 — incl. an out-of-ceiling id (never an existence oracle)
-  ConflictError,        // 409 — incl. idempotency_conflict (same key, different body)
-  ValidationError,      // 422 — see err.body.error.details
-  PaymentRequiredError, // 402 — x402 test-mode challenge in err.paymentRequired
-  RateLimitError,       // 429 — err.retryAfter (seconds)
+  AuthenticationError,  // 401: key missing / expired / revoked
+  PermissionError,      // 403: scope denied
+  ForbiddenScopeError,  // 403 forbidden_scope: out of the key's ceiling / non-org key on the wildcard
+  BreadthRequiredError, // 400 breadth_required: org key on a bare list must pick a project / "-"
+  NotFoundError,        // 404: incl. an out-of-ceiling id (never an existence oracle)
+  ConflictError,        // 409: incl. idempotency_conflict (same key, different body)
+  ValidationError,      // 422: see err.body.error.details
+  PaymentRequiredError, // 402: x402 test-mode challenge in err.paymentRequired
+  RateLimitError,       // 429: err.retryAfter (seconds)
   ConnectionError,      // network failure before a response
   TimeoutError,         // request timed out / aborted
 } from "@extrovert.dev/sdk";
@@ -387,13 +461,24 @@ Maps 1:1 to the Extrovert `/v1` REST contract.
 | `inbox.send()`                        | `POST /v1/inboxes/{addr}/send`        |
 | `inbox.messages()`                    | `GET /v1/inboxes/{addr}/messages`     |
 | `inbox.threads()`                     | `GET /v1/inboxes/{addr}/threads`      |
+| `inbox.searchThreads()`               | `GET /v1/inboxes/{addr}/threads/search` |
+| `inbox.thread(thread_id)`             | `GET /v1/inboxes/{addr}/threads/{thread_id}` |
+| `inbox.reply({ thread_id, ... })`      | `POST /v1/inboxes/{addr}/reply`       |
+| `inbox.deleteThread(thread_id)`        | `DELETE /v1/inboxes/{addr}/threads/{thread_id}` |
 | `inbox.waitForEmail()`                | `POST /v1/inboxes/{addr}/wait`        |
 | `extrovert.inboxes.update(addr, ...)`   | `PATCH /v1/inboxes/{addr}`            |
 | `extrovert.messages.get(id)`            | `GET /v1/messages/{id}`               |
-| `extrovert.messages.reply(id, ...)`     | `POST /v1/messages/{id}/reply`        |
-| `extrovert.threads.get(id)`             | `GET /v1/threads/{id}`                |
+| `extrovert.threads.list(inbox, ...)`     | `GET /v1/inboxes/{inbox}/threads`     |
+| `extrovert.threads.search(inbox, ...)`   | `GET /v1/inboxes/{inbox}/threads/search` |
+| `extrovert.threads.get(inbox, id)`       | `GET /v1/inboxes/{inbox}/threads/{id}` |
+| `extrovert.threads.reply(inbox, ...)`    | `POST /v1/inboxes/{inbox}/reply`      |
+| `extrovert.threads.delete(inbox, id)`    | `DELETE /v1/inboxes/{inbox}/threads/{id}` |
 | `extrovert.webhooks.register()`         | `POST /v1/webhooks`                   |
 | `extrovert.domains.onboard(...)`        | `POST /v1/domains`                    |
+| `extrovert.commerce.quoteDomain(...)`   | `POST /v1/commerce/domain-quotes`     |
+| `extrovert.commerce.requestDomainPurchase(...)` | `POST /v1/commerce/requests/domain-purchases` |
+| `extrovert.commerce.requestPlanChange(...)` | `POST /v1/commerce/requests/plan-changes` |
+| `extrovert.commerce.get(...)`           | `GET /v1/commerce/requests/{id}`      |
 | `extrovert.whoami()`                    | `GET /v1/auth/me`                     |
 
 Helpers: `verifyWebhookSignature`, `parseWebhook`, `extractOtp`, `extractLink`,
@@ -419,30 +504,32 @@ A key carries a subset of these capability scopes (`whoami().scopes`):
 | ----------------- | ---------------------------------------------------------------------- |
 | `mailbox:create`  | Create inboxes.                                                        |
 | `mailbox:read`    | Read inboxes, messages, threads.                                       |
+| `mailbox:credentials` | Export raw IMAP/SMTP credentials on paid plans; never implied by read. |
 | `mailbox:send`    | Send / reply / forward.                                                |
 | `mailbox:quota`   | Change an inbox's effective daily recipient cap (opt-in).              |
 | `mailbox:delete`  | Delete inboxes.                                                        |
 | `webhook:write`   | Register / manage webhooks.                                            |
-| `domain:manage`   | The agent-facing domains plane (onboard / verify / offboard).          |
-| `domain:purchase` | Additionally required (and **opt-in, default-off**) to onboard with `mode: "purchased"` (registrar spend, plan-capped). |
+| `domain:manage`   | Onboard / verify / offboard shared or customer-controlled domains. It never buys a domain. |
+| `domain:read`     | Read accessible domains, readiness, and domain updates without permission to change setup. |
+| `commerce:request` | Quote and request a domain purchase or plan change, then poll status. It never approves or spends directly. |
 | `review:act`      | The BYO reviewer decision plane.                                       |
 
 > The `mailbox:*` scope strings are the live wire contract (the public product term is **inbox**;
-> the scope strings are kept verbatim so already-minted keys stay valid).
+> the scope strings are kept verbatim so already-issued keys stay valid).
 
 ---
 
-## Review Loop — the open contract
+## Review Loop: the open contract
 
 The **Review Loop** (HITL) adds supervised autonomy: an agent submits a draft `mode:"review"`,
 a human approves / edits / rejects it, and the loop learns. The stable agent-facing JSON shapes
-are published here as a documented, **versioned open contract** — an SDK + skill contract, **not**
+are published here as a documented, **versioned open contract**: an SDK + skill contract, **not**
 a wire protocol (there is no `/v1/contract` endpoint).
 
 ```ts
 import { CONTRACT_VERSION, CONTRACT_MANIFEST } from "@extrovert.dev/sdk";
 
-CONTRACT_VERSION;            // "0.1.0-pre.5" — provisional, pre-1.0; pin it
+CONTRACT_VERSION;            // "0.1.0-pre.7": provisional, pre-1.0; pin it
 CONTRACT_MANIFEST.stability; // "provisional"
 CONTRACT_MANIFEST.core_shapes; // ["ReviewIntent","ReviewFeedback","DiffJson","Rule","ReviewEvent"]
 ```
@@ -451,8 +538,8 @@ CONTRACT_MANIFEST.core_shapes; // ["ReviewIntent","ReviewFeedback","DiffJson","R
 `org_id` / `project_id`. `org` rules are house-style inherited by every project in the org;
 `project` rules are layered on top and outrank broader org rules in the ordered `get_rules`
 precedence ladder. An agent-plane `rules.save(...)` is **always project-layer** (bound to the key's
-project); an agent **cannot author `rule_layer: "org"` rules in v1** — that is a console/admin
-action. (`scope: "general"` still means a house-style rule *within* the project layer — `scope` is
+project); an agent **cannot author `rule_layer: "org"` rules in v1**: that is a console/admin
+action. (`scope: "general"` still means a house-style rule *within* the project layer: `scope` is
 the category axis, `rule_layer` is the ownership axis.)
 
 Full reference: the [agent contract](https://docs.extrovert.dev/review-loop/agent-contract/) docs
@@ -460,21 +547,21 @@ page and the agent skills (`extrovert-send-email`, `extrovert-writing-rules`).
 
 ### Contract & versioning
 
-The Review-Loop shapes are an **open, documented contract — versioned *with* this SDK** (not a wire
+The Review-Loop shapes are an **open, documented contract: versioned *with* this SDK** (not a wire
 protocol; there is no `/v1/contract` endpoint). Three guarantees:
 
-- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.5`**, reconciled across the SDK package
+- **One version, everywhere.** `CONTRACT_VERSION` is **`0.1.0-pre.7`**, reconciled across the SDK package
   version, the MCP server, and the OpenAPI `info.version`. Pin it; pin `CONTRACT_MANIFEST` for the
   exact shape set you built against.
-- **Named, documented types.** The five canonical shapes — `ReviewIntent`, `ReviewFeedback`,
-  `DiffJson` (+`DiffHunk`), `Rule`, `ReviewEvent` — plus the full M1–M8 surface (submit/states,
+- **Named, documented types.** The five canonical shapes: `ReviewIntent`, `ReviewFeedback`,
+  `DiffJson` (+`DiffHunk`), `Rule`, `ReviewEvent`: plus the full M1–M8 surface (submit/states,
   chat, categories, graduation + risk dial, reconciliation + pacing, rules + audit, the BYO reviewer
   decision plane) are exported as named TypeScript types from the `contract` module.
   `CONTRACT_MANIFEST.shapes` enumerates them all by name.
 - **Drift-proof.** A conformance/drift test validates the canonical example JSON against **both** the
   OpenAPI component schemas (Go) and these SDK types, and asserts the version is reconciled across
   every surface (plus a negative test so the guard isn't a tautology). Rename a field anywhere and
-  the build breaks — the published types can't silently diverge from the wire.
+  the build breaks: the published types can't silently diverge from the wire.
 
 > **Provisional 0.x.** The contract is open and documented but MAY still evolve additively before
 > 1.0 (no external users yet). Pin `CONTRACT_VERSION` and `CONTRACT_MANIFEST`.
@@ -483,7 +570,7 @@ protocol; there is no `/v1/contract` endpoint). Three guarantees:
 
 ## Examples
 
-Runnable with [`tsx`](https://github.com/privatenumber/tsx) — work offline out of the box:
+Runnable with [`tsx`](https://github.com/privatenumber/tsx): work offline out of the box:
 
 ```bash
 EXTROVERT_API_BASE_URL=mock npx tsx examples/mailbox-in-one-call.ts
@@ -494,7 +581,7 @@ EXTROVERT_API_BASE_URL=mock npx tsx examples/wait-for-otp.ts
 
 ## Status
 
-> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.5` — a
+> **Note.** This source SDK tracks the `/v1` contract at `CONTRACT_VERSION` `0.1.0-pre.7`: a
 > deliberate **prerelease**, pre-1.0, expect additive change. The offline `mock` transport models the
 > live server closely enough to reproduce a 422 `intent_required` and a queued review, so build and
 > test against it before you have a key. Install from the `next` tag until a stable release is cut.