@dvmkit/dvmctl 0.3.3-rc.1 → 0.3.5-rc.1

package/skills/build-dvm/references/running-deployment.md

@@ -1,231 +0,0 @@
-## Running
-
-### dvmctl dev (development)
-
-```bash
-dvmctl dev handler.ts              # http://localhost:3000, hot reload, /_dev test page
-dvmctl dev handler.ts --port 4000  # custom port
-```
-
-Port resolution: `--port` > `.env PORT` > `process.env.PORT` > `3000`.
-
-Handler resolution: default export > `dvm` named export > first `DVMDescriptor` export.
-
-With no configured rail, dev mode skips payment verification and says so in its banner. Configure
-Cashu, x402, or Tempo and the same server performs real rail verification with disposable in-process
-storage; its banner names every rail, verification state, and whether the SDK can prove the funds are
-test funds. The paid-completion observer prints each settled job and a deduplicated session total.
-`/_dev` can satisfy an interactive ask with the synthetic `dev_auto` flag, which no non-dev server
-admits; that shortcut applies only to the test page, never to caller CLI payments. Follow the
-rail-specific paid-test references for bounded calls. Drive a no-rail server from another terminal:
-
-```bash
-dvm request --endpoint http://localhost:3000 -i "input" --human
-```
-
-`--endpoint` and `-d <identifier>` are mutually exclusive — pass one or the other, not both.
-Against a raw endpoint the capability auto-resolves from `/v1/info`, so a single-cap DVM needs
-nothing more. A multi-cap DVM has no capability to auto-resolve and errors `ambiguous_capability`
-with the available tags listed — pin one via the slash form (`-d <identifier>/<tag>`), where
-`<identifier>` is an owner-qualified `<handle>--<slug>` or a saved favorite.
-
-### serve(dvm) — production one-liner
-
-```typescript
-import { serve } from "@dvmkit/sdk/server";
-import dvm from "./handler";
-
-await serve(dvm);
-// or with overrides:
-await serve(dvm, { port: 8080, mints: ["https://mint.example.com"] });
-```
-
-`serve(dvm, opts?)` is a thin wrapper over `createDVMHost(opts).mount(dvm).serve()` and returns
-`{ url, close }`. All wiring (port, `DATABASE_URL`, `DVMKIT_CASHU_MINTS`, Tempo/x402 rails, FX,
-platform reporter) is resolved from env by default — `opts` only overrides.
-
-### createDVMHost(opts) — advanced
-
-Use directly when you need to register `host.app` routes, mount several DVMs, or graceful-shutdown
-alongside DVM-owned resources:
-
-```typescript
-import { createDVMHost } from "@dvmkit/sdk/server";
-import { createCastDVM, buildCastRuntime } from "./handler";
-
-const { runtime } = await buildCastRuntime(process.env);
-
-const host = createDVMHost({
-  fx: runtime.fxFetcher,
-  // database / mints / port etc default from env
-});
-
-host.mount(createCastDVM(runtime));
-
-const { url } = await host.serve();
-console.log(`cast running at ${url}`);
-```
-
----
-
-## createDVMHost / serve options
-
-`DVMHostOpts` (passed to either function):
-
-| Option             | Type                     | Default                       | Description                                                 |
-| ------------------ | ------------------------ | ----------------------------- | ----------------------------------------------------------- |
-| `port`             | `number`                 | `PORT` env or `8080`          | HTTP listen port                                            |
-| `database`         | `string`                 | `DATABASE_URL` env            | Postgres URL — auto-creates job + KV stores (`pg` peer dep) |
-| `jobStore`         | `JobStore`               | derived from `database`       | Explicit job store; precedence over `database`              |
-| `store`            | `KVStore`                | in-memory                     | KV store for `ctx.store`                                    |
-| `env`              | `Record<string, string>` | `process.env`                 | Injected as `ctx.env`                                       |
-| `mints`            | `string[]`               | `DVMKIT_CASHU_MINTS` env      | Cashu mints accepted                                        |
-| `mpp`              | `MppxServer`             | from `DVMKIT_TEMPO_*` env       | Tempo rail handle (mppx server)                             |
-| `x402`             | `X402Config`             | from `DVMKIT_X402_*` env      | x402 stablecoin rail config                                 |
-| `paymentMethods`   | `PaymentMethod[]`        | derived from configured rails | Restrict accepted rails                                     |
-| `fx`               | `FxFetcher`              | env-derived                   | FX rate fetcher (override for tests or alt sources)         |
-| `builder`          | `BuilderIdentity`        | env-derived                   | `{ id?, name?, url? }` for `/v1/info`                       |
-| `healthHandler`    | `(c) => Response`        | default `/health`             | Custom `/health` handler                                    |
-| `platformReporter` | `PlatformReporterOpts`   | `DVMKIT_PLATFORM_*` env       | `{ token?, url? }` for revenue reporting                    |
-| `devMode`          | `boolean`                | `false`                       | Skips DB requirement; auto-credits only when mint-less      |
-
-`DVMHost` returned by `createDVMHost`:
-
-| Property / method             | Description                                                     |
-| ----------------------------- | --------------------------------------------------------------- |
-| `host.app`                    | Underlying Hono app — register host-level routes here           |
-| `host.pool`                   | Postgres pool, set after `host.serve()` resolves                |
-| `host.mount(dvm, { prefix })` | Mount a DVM; optional prefix nests its routes under `/<prefix>` |
-| `host.serve({ port })`        | Start listening; returns `{ url, close }`                       |
-| `host.shutdown()`             | Graceful shutdown                                               |
-
----
-
-## Persistence
-
-Pass `database` (or set `DATABASE_URL`) to persist jobs, state, step caches, and KV data to
-Postgres:
-
-```typescript
-await serve(dvm, { database: process.env.DATABASE_URL });
-```
-
-From the handler author's perspective:
-
-- `ctx.state` is typed from your `state: { ... }` defaults and is **auto-persisted transactionally
-  on every yield** (prompt, requestPayment) and at terminal states (complete, fail). After a
-  process restart, the SDK reloads state from Postgres and resumes.
-- `ctx.step("id", fn)` results are persisted alongside state. On replay, cached steps return their
-  stored value without re-executing, and replay the step's `ctx.cost()` declarations exactly once.
-- `ctx.requestPayment(amount, reason, opts?)` resolves on **counter-based auto-credit**: if the
-  upfront payment already covers `amount - alreadyCreditedToThisHandler`, the call returns
-  synchronously without round-tripping to the client. Only when the upfront pool is exhausted does
-  the handler suspend waiting for a new payment.
-
-Auto-creates `PostgresJobStore` + `PostgresKVStore`; tables are created on first run. `jobStore`
-and `store` opts take precedence over `database` for advanced use. `pg` is an optional peer dep —
-the scaffold already lists it.
-
----
-
-## Deployment
-
-The scaffold ships a Dockerfile and wires `npm run deploy` → `dvmctl deploy`. The cloud path:
-
-```bash
-dvmctl validate          # load handler + validate capability/schema/example/price/tags and package metadata
-dvmctl deploy            # build container, push, deploy to the dvmkit platform
-dvmctl deploy --dry-run  # full validation incl. a real `docker build` (slow, cold) — no provisioning
-```
-
-Use `dvmctl validate` for fast iteration; it emits `{"status":"ok", ...}` with agent-facing display and hint fields.
-`dvmctl deploy --dry-run` adds a real container build on top, so it's slower and needs Docker.
-
-On dvmkit Cloud, the active org owns each deployed DVM. Its treasury holds payout configuration — Tempo recipient, Base/x402 address, Cashu mints, and lock pubkey — rather than the DVM descriptor or builder profile. The lock pubkey propagates from org to DVM to SDK; see the three-level lock pubkey model.
-
-Provide the deployed DVM's API keys and payment credentials through its host's runtime environment
-facility; keep them out of source control. That is separate from the platform org treasury's payout
-configuration. System dependencies (ffmpeg, python, …) go in the scaffolded `Dockerfile`'s runtime
-stage. VM resources go in `package.json`'s `dvmkit` field (`{ "dvmkit": { "memory_mb": 1024 } }`).
-
-### Environment variables
-
-The SDK reads only `DVMKIT_*`-prefixed variables. Old unprefixed names (`MINTS`,
-`MPP_TEMPO_RECIPIENT`, `X402_PAY_TO`, etc.) and the legacy `DVMKIT_FIRST_PARTY` /
-`DVMKIT_ACCESS_TOKENS` / `DVMKIT_SKIP_PAYMENT` are gone — don't use them.
-
-**Standard (unprefixed):**
-
-| Var            | Description                                      |
-| -------------- | ------------------------------------------------ |
-| `PORT`         | HTTP port (default: 8080)                        |
-| `DATABASE_URL` | Postgres connection string (enables persistence) |
-
-**Cashu rail:**
-
-| Var                        | Description                                                                                                                                                                                                                                  |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DVMKIT_CASHU_MINTS`       | Comma-separated Cashu mint URLs                                                                                                                                                                                                              |
-| `DVMKIT_CASHU_LOCK_PUBKEY` | P2PK lock pubkey for the accumulator                                                                                                                                                                                                         |
-| `DVMKIT_DVM_ID`            | DVM identifier (replay key + scheduler lock)                                                                                                                                                                                                 |
-| `DVMKIT_CANONICAL_DVM_ID`  | Override `DVMKIT_DVM_ID` for cross-instance canonical ID                                                                                                                                                                                     |
-| `DVMKIT_ALLOW_TEST_MINTS`  | `true` to allow a test mint (`localhost:3338`, `testnut.cashu.space`) on a platform-hosted boot (`DVMKIT_PLATFORM_URL` set). Otherwise such a boot refuses to start — a test mint settles no real money. Local dev never trips it. |
-
-**Tempo rail:**
-
-| Var                          | Description                                     |
-| ---------------------------- | ----------------------------------------------- |
-| `DVMKIT_TEMPO_RECIPIENT` | 0x-prefixed 40-char hex Tempo recipient address |
-| `DVMKIT_TEMPO_SECRET_KEY`      | HMAC key for Tempo challenges                   |
-| `DVMKIT_TEMPO_METHODS`         | Comma-separated allowlist of Tempo methods      |
-
-**x402 rail:**
-
-| Var                       | Description                              |
-| ------------------------- | ---------------------------------------- |
-| `DVMKIT_X402_PAY_TO`      | EVM address receiving stablecoin         |
-| `DVMKIT_X402_NETWORK`     | Validated CAIP-2 id or known slug (default `eip155:8453`) |
-| `DVMKIT_X402_ASSET`       | Asset symbol                             |
-| `DVMKIT_X402_FACILITATOR` | Facilitator URL; use `https://api.cdp.coinbase.com/platform/v2/x402` for CDP |
-| `DVMKIT_X402_FACILITATOR_KEY_ID` | CDP API key ID; requires the secret below |
-| `DVMKIT_X402_FACILITATOR_KEY_SECRET` | CDP SEC1 ES256 PEM (`BEGIN EC PRIVATE KEY`) or base64 Ed25519 secret; provide it through the deployment environment |
-| `DVMKIT_X402_DUAL_SERVE`  | `"false"` disables dual-serve            |
-| `DVMKIT_X402_DESCRIPTION` | Prose description                        |
-| `DVMKIT_X402_BATCH_SETTLEMENT` | `true` enables reusable channels: Base Sepolia uses hosted facilitator support; Base mainnet also requires the self-relay key below and keeps batch credit funding independent from hosted exact health |
-| `DVMKIT_X402_RECEIVER_AUTHORIZER_KEY` | Receiver-authorizer private key when the facilitator supplies none; mainnet self-relay requires this separate signing-only key |
-| `DVMKIT_X402_SELF_RELAY_KEY` | Dedicated funded EOA key for one DVM's Base-mainnet relay; never reuse it as the authorizer or across DVMs |
-| `DVMKIT_X402_SELF_RELAY_MIN_BALANCE_WEI` | Optional positive Base ETH paging floor; defaults to 0.001 ETH |
-| `DVMKIT_X402_RPC_URL` | Required explicit Base RPC for self-relay transaction submission and settlement evidence |
-| `DVMKIT_X402_WITHDRAW_DELAY_SECONDS` | Channel withdrawal grace; minimum/default 86400 |
-
-**Lightning receive (credit funding only —:**
-
-| Var                                      | Description                                                                                                                                                                                          |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DVMKIT_NWC_RECEIVE_URI`                 | **Receive-only** NWC connection the DVM issues credit-funding bolt11s over. Adds `lightning` to the credit funding menu; never to `payment_methods` — there is no per-call Lightning rail. |
-| `DVMKIT_NWC_RECEIVE_INVOICE_TTL_SECONDS` | Invoice lifetime (default `900`, floor `600`)                                                                                                                                                        |
-| `DVMKIT_LIGHTNING_FUNDING_MIN_SATS`      | The deployment's receive floor in sats (default `2000`,. Advertised on the menu as `lightning_min_micro` (×1.15 fx margin); a sub-floor fund is refused `below_rail_minimum` before any invoice exists — a bolt11 under the channel's `htlc_minimum_msat` can never route. |
-
-The connection must permit `get_info`, `get_balance`, `make_invoice`, `lookup_invoice` and **not** `pay_invoice` — the SDK probes it at boot and refuses to start on a spend-capable connection, or on a wallet that won't state what its connection permits. A DVM machine never holds a spending credential; the drain sender is a deliberately separate, budget-capped connection.
-
-Crediting is **pull-based**. The caller sends `op: "fund"` with `fund: { amount_micro, fund_id, method: "lightning" }` and no `commitment` (there is no artifact to hash — the invoice is minted for the credit and amount in their signed body, which is the binding), gets a 402 carrying the bolt11, and their _next_ request — a re-poll, a `balance` read, or a job submit naming the credit — asks the wallet and credits the ledger in one transaction. No background watcher, so a suspend-to-zero fleet works unchanged. A re-poll always returns the same bolt11; a second invoice per `fund_id` would be two payable invoices against one creditable funding. If the wallet is unreachable, `lightning` drops off the menu and the other rails carry the sale.
-
-**Platform / ops:**
-
-| Var                     | Description                                                                                      |
-| ----------------------- | ------------------------------------------------------------------------------------------------ |
-| `DVMKIT_FAIL_FAST`      | `"1"` or `"true"` → escalate warning-level SDK boot checks to fatal (strict mode)                |
-| `DVMKIT_FX_SOURCE`      | FX rate source override                                                                          |
-| `DVMKIT_PLATFORM_TOKEN` | Bearer token for platform revenue reporter                                                       |
-| `DVMKIT_PLATFORM_URL`   | Platform internal URL — setting it marks the boot platform-hosted                                |
-| `DVMKIT_RECEIPT_KEY`    | Receipt-signing secret. Provisioned by `dvmctl deploy` — see [Signed receipts](patterns-auth.md#signed-receipts) |
-
-Setting `DVMKIT_PLATFORM_URL` makes `DVMKIT_PLATFORM_TOKEN`, `DVMKIT_DVM_ID`, and `DATABASE_URL`
-mandatory: partial revenue-reporter wiring is fatal at boot whether or not `DVMKIT_FAIL_FAST` is set
-. `devMode` boots — `dvmctl dev`, `dvm serve`, the e2e/smoke harnesses — are exempt, so a
-`DVMKIT_PLATFORM_URL` exported in your shell won't stop a dev server booting.
-
-`DVMKIT_FAIL_FAST` is the general strict-mode flag for the SDK's other boot checks (e.g.
-`secp256k1Auth`'s in-memory replay store outside `devMode`); set it in production.
-
----

package/skills/build-dvm/references/sdk-reference.md

@@ -1,47 +0,0 @@
-# SDK reference
-
-Use this after the first-build brief is approved. Keep the first version flat and single-capability unless the product requires distinct inputs, prices, or handlers.
-
-```ts
-import { configureDVM, z } from "@dvmkit/sdk";
-
-export default configureDVM({
-  name: "Uppercase",
-  description: "Convert text to uppercase.",
-  capability: "uppercase",
-  tags: ["text"],
-  input: z.object({ text: z.string().min(1) }),
-  price: "$0.01",
-  async onJob(ctx) {
-    ctx.complete(ctx.input.text.toUpperCase());
-  },
-});
-```
-
-Import `serve` or `createDVMHost` from `@dvmkit/sdk/server`, and `createTestContext` from `@dvmkit/sdk/testing`. `serve(dvm)` is sufficient for a normal DVM. Use `createDVMHost` only for custom HTTP routes, mounting several DVMs, or explicit lifecycle control.
-
-## Descriptor choices
-
-- `input: z.object(...)` validates requests before `onJob` and types `ctx.input`. Omit it only for deliberately raw-string input.
-- `price: "$0.01"` is a static USD price. Omit it for free work. Use `onQuote` for dynamic pricing; never calculate a static price in sats.
-- `capabilities: { ... }` replaces the flat capability fields for a multi-capability DVM. Keep name, tags, auth, routes, and lifecycle hooks at the parent level.
-- `state` provides typed per-job defaults. Use a persistent store only when jobs must survive process restarts.
-- `paymentMethods` is normally derived from configured server rails. Do not advertise a rail that the server cannot settle.
-
-## Job handler rules
-
-`ctx.text()` sends progress, `ctx.artifact()` sends named data, `ctx.working()` yields with an estimate, `ctx.prompt()` waits for a caller response, and `ctx.complete()` finishes. Call `ctx.cost({ amount, currency })` immediately after a paid provider call. Check `ctx.signal.aborted` around long work and pass the signal to fetches where supported. A cancellation is terminal; never attempt to complete it afterward.
-
-Use `ctx.fail(message, { refund: true })` for a provider or network failure that should return a Cashu payment. Configuration errors and invalid user input should fail without a refund.
-
-## Tests and secrets
-
-Write deterministic unit tests with `createTestContext`; assert messages, completion, failure, and artifacts. Mock an upstream boundary in unit tests and keep live-provider tests separate. Load credentials from environment variables. Never place a key, mnemonic, private key, or test wallet state in a repository.
-
-## Advanced routing
-
-Use descriptor `auth: secp256k1Auth(...)` only when the product needs authenticated callers. The verified identity is `ctx.auth`; do not accept an identity asserted in input. Use `routes(app)` for non-protocol endpoints and keep `/v1/*` protocol endpoints under SDK control. See the installed package's TypeScript declarations for exact option types; they match the installed SDK version.
-
-## Deploy preparation
-
-Before deployment, run the generated tests and validate the descriptor. A production deployment needs its own account, identity, database, environment secrets, and payment configuration. Do not reuse a local FakeWallet mint or its test key in production.

package/skills/build-dvm/references/testing.md

@@ -1,181 +0,0 @@
-## Input validation
-
-Pass an `input:` Zod schema and `ctx.input` is parsed and typed. Zod ships with the SDK —
-`import { z } from "@dvmkit/sdk"`, no extra install. Skip the schema and `ctx.input` stays a raw
-string you parse yourself.
-
-```typescript
-import { configureDVM, z } from "@dvmkit/sdk";
-
-export default configureDVM({
-  name: "Image Gen",
-  capability: "generate",
-  tags: ["image-generation"],
-  input: z.object({
-    prompt: z.string(),
-    width: z.number().default(1024),
-    height: z.number().default(1024),
-  }),
-
-  async onJob(ctx) {
-    // ctx.input is typed: { prompt: string; width: number; height: number }
-    ctx.text(`Generating: ${ctx.input.prompt}`);
-  },
-});
-```
-
-**Document fields with `.describe()`, not JSDoc.** `/v1/info` renders each field via
-`toJSONSchema(input, { io: "input" })`, which carries **only** Zod `.describe()` metadata — a
-`/** … */` JSDoc comment on a schema field is silently dropped and never reaches the cold-calling
-agent. Put field docs on `.describe("…")`; reserve JSDoc for internal notes. When a cross-field
-rule lives in a `.refine()` (e.g. "exactly one of `audio_url` / `audio_upload_handle`"), name it in
-the fields' `.describe()` and also ship an `example` so the CLI renders a runnable `--data` payload
-instead of a schema skeleton. The `dvmkit/no-jsdoc-on-zod-schema` ESLint rule (scoped to
-the DVM source tree) flags JSDoc on Zod-object properties.
-
-```typescript
-// ❌ dropped from /v1/info          ✅ reaches the wire
-z.object({                           z.object({
-  /** Omit to auto-detect. */          language: z.string().describe("Omit to auto-detect.").optional(),
-  language: z.string().optional(),   });
-});
-```
-
----
-
-## Testing
-
-### createTestContext()
-
-```typescript
-import { createTestContext } from "@dvmkit/sdk/testing";
-
-const ctx = createTestContext({
-  input: "test input", // string or parsed type
-  tags: ["web"],
-  params: { key: "value" },
-  env: { API_KEY: "test" }, // ctx.env
-  state: { step: 0 }, // ctx.state (typed, structured-cloned)
-  paidMsats: 10000,
-  responses: {
-    // pre-programmed prompt answers
-    q1: { text: "answer", prompt_id: "q1" },
-  },
-  payment: { cashu_token: "..." }, // pre-programmed requestPayment answer
-  jobId: "test-job-1",
-  requesterId: "test-requester",
-});
-```
-
-`createTestContext` bypasses `JobStore` entirely: `step()` runs `fn()` directly with no caching,
-state is a structured clone of `opts.state`, and there is no Postgres dependency. `ctx.auth` is
-always `undefined` in tests (there's no `auth` option) — exercise signed-request auth through
-`createSignedRequestVerifier` round-trips instead.
-
-### Inspection properties
-
-| Property          | Type                  | Description                               |
-| ----------------- | --------------------- | ----------------------------------------- |
-| `messages`        | `RecordedMessage[]`   | All outbound messages `[{type, content}]` |
-| `completed`       | `boolean`             | Whether `complete()` was called           |
-| `failed`          | `boolean`             | Whether `fail()` was called               |
-| `refundRequested` | `boolean`             | Whether `fail()` was called with refund   |
-| `summary`         | `string \| undefined` | The string passed to `complete()`         |
-| `failError`       | `string \| undefined` | The string passed to `fail()`             |
-
-`ctx.cancel(reason?)` aborts `ctx.signal` exactly as a real cancel would and puts the context into the
-same post-terminal shape as the runtime: every emitter (`text` / `artifact` / `sendMessage` /
-`working` / `progress` / `complete` / `fail`) is a no-op, and `prompt` / `requestPayment` reject with
-`JobCancelledError`. Use it to assert your handler stops work:
-
-```typescript
-const ctx = createTestContext({ input: "long job" });
-const running = dvm.capabilities.transcribe.onJob(ctx);
-ctx.cancel("caller changed their mind");
-await running;
-expect(ctx.completed).toBe(false);
-```
-
-### Calling the handler
-
-The descriptor exposes `dvm.capabilities[<name>].onJob` in both shapes (flat single-capability or
-multi-capability):
-
-```typescript
-import { describe, expect, it } from "vitest";
-
-import { createTestContext } from "@dvmkit/sdk/testing";
-
-import { createTranslatorDVM } from "./handler";
-
-describe("Translator", () => {
-  const dvm = createTranslatorDVM();
-
-  it("translates with language prompt", async () => {
-    const ctx = createTestContext({
-      input: "Hello",
-      tags: ["translation"],
-      state: { detectedLanguage: "", targetLanguage: "" },
-      responses: { "target-lang": { text: "Spanish", prompt_id: "target-lang" } },
-    });
-
-    await dvm.capabilities.translate.onJob(ctx);
-
-    expect(ctx.completed).toBe(true);
-    expect(ctx.summary).toContain("Spanish");
-    expect(ctx.messages).toContainEqual(expect.objectContaining({ type: "artifact" }));
-  });
-});
-```
-
-### Live provider contracts
-
-**Invariant: a capability that charges _and_ whose handler calls a paid third-party API must ship a
-live provider-contract test.** Both halves of the conjunction are required, and the rule is
-deliberately narrow. A free capability, or one that only talks to your database, your own endpoints,
-or a local FakeWallet mint, falls outside it. Give those paths appropriate integration checks in
-your project.
-
-Why: `createTestContext` and a stubbed `globalThis.fetch` pin your request shape against your own
-expectation. They do not prove the provider accepts it. A provider can reject a request after the
-job has taken payment. No debit lands either way — the draw releases (see
-[Refund-on-failure policy](patterns-auth.md#refund-on-failure-policy)) — but reaching that released
-value needs a verified caller. Add `auth` when the product needs callers to use released credit again;
-a rail-level reversal is a separate payment-design choice.
-
-The pattern has three parts:
-
-1. **Name the file `<provider>.live.test.ts`.** Configure your project's default test command to
-   exclude `**/*.live.test.ts`, so ordinary checks never spend vendor money.
-2. **Gate the suite on `describe.skipIf(!process.env.<PROVIDER_KEY>)`.** This is what makes the test
-   **merge inert**: a keyless checkout and a keyless CI run both skip cleanly rather than reddening.
-   The rule does **not** mean CI needs your API key.
-3. **Add an opt-in `test:providers:live` script** that includes only `**/*.live.test.ts`. Nothing
-   else runs it.
-
-```typescript
-const API_KEY = process.env.ELEVENLABS_API_KEY;
-
-describe.skipIf(!API_KEY)("ElevenLabs live provider contract (real EL spend)", () => {
-  it("accepts the expressive multi-chunk shape we emit", async () => {
-    // Real call. Assert the provider ACCEPTS what we send…
-    expect(call.status).toBe(200);
-    expect(call.body.model_id).toBe(ELEVENLABS_V3_MODEL_ID);
-    // …and returns what we actually parse.
-    expectMp3(audio);
-  });
-});
-```
-
-**Assert the provider accepts every request shape the handler actually emits, and returns something
-the parser actually parses.** A live 2xx alone is not the contract — if the handler branches (model
-× chunking, streaming vs. batch, each option a caller can select), each branch is a distinct wire
-shape and needs a cell. This is a _contract_ test, not a quality test: "the provider accepts what we
-send", never "the output is good".
-
-It spends **real vendor money** (never caller funds, never production). Keep request and response
-evidence small: record URL, body shape, and status; never print headers or keys. A provider 429/5xx
-may retry once, then skip with a clear reason rather than reporting a false product regression.
-Shipping this test with the capability keeps a new paid boundary from depending only on mocks.
-
----