@dvmkit/dvmctl 0.1.0-rc.2 → 0.2.0-rc.2

package/skills/build-dvm/references/operating-feedback.md

@@ -0,0 +1,153 @@
+## Operating a deployed DVM
+
+Once a DVM is live, `dvmctl` is the full operational surface — you never need `flyctl`.
+Every command emits JSON by default and takes `--human`; `<slug>` is the DVM's deployed name.
+Exceptions noted inline (`logs` and `revenue csv` emit raw output, not JSON).
+
+Every DVM-specific command resolves its bare `<slug>` only inside the active `dvmctl switch` context. Pass `--org <handle>` for a one-shot override without changing that context. The CLI resolves that scoped slug to an immutable DVM ID before it reads, changes, or opens a machine resource, so a matching slug in another org is never selected accidentally.
+
+### Fleet introspection
+
+| Command                 | Purpose                                                      | Key flags                   |
+| ----------------------- | ------------------------------------------------------------ | --------------------------- |
+| `dvmctl list`           | List your deployed DVMs                                      |                             |
+| `dvmctl info <slug>`    | Deployed-DVM details                                         | `--org`                     |
+| `dvmctl status <slug>`  | Live Fly runtime state (machines, region, image, health)     | `--org`                     |
+| `dvmctl metrics <slug>` | Request metrics                                              | `--hours` (default 24), `--org` |
+| `dvmctl events <slug>`  | Recent events (deploys, restarts, scale, env, machine state) | `--since` (e.g. `2h`, `7d`), `--org` |
+
+### Runtime ops
+
+| Command                     | Purpose                                                         | Key flags                          |
+| --------------------------- | --------------------------------------------------------------- | ---------------------------------- |
+| `dvmctl logs <slug>`        | View or stream logs (**raw output**, not JSON)                  | `--tail`, `--since`, `--lines`, `--org` |
+| `dvmctl ssh <slug>`         | Interactive shell, or one-shot command, on the Fly machine      | `--command`, `--machine`, `--org`  |
+| `dvmctl restart <slug>`     | Restart machines without a redeploy                             | `--machine` (default: all), `--org` |
+| `dvmctl rollback <slug>`    | Revert to a previous successful deploy's image                  | `--to <deploy-id>` (default: prev), `--org` |
+| `dvmctl scale <slug>`       | Change machine count and/or VM size without a redeploy          | `--count` (1–8), `--size`, `--org` |
+| `dvmctl destroy <slug>`     | Destroy the DVM and its paired Postgres cluster                 | `--confirm`, `--keep-db`, `--org`  |
+| `dvmctl deploy-status <id>` | Status of a deploy by ID — recovery handle for a stuck `deploy` |                                    |
+
+### Config, data & tracing
+
+| Command                             | Purpose                                                                       | Key flags                      |
+| ----------------------------------- | ----------------------------------------------------------------------------- | ------------------------------ |
+| `dvmctl env <slug>`                 | View or update environment variables                                          | `--set KEY=val`, `--unset KEY`, `--org` |
+| `dvmctl secrets list <slug>`        | List secret names + last-applied times (never values)                         | `--org`                       |
+| `dvmctl db connect <slug>`          | Interactive `psql` against the DVM's database (needs local `psql`)            | `--machine`, `--org`          |
+| `dvmctl db proxy <slug>`            | Bind a local port to the DVM's database (`pg_dump`, drizzle-kit, GUI clients) | `--port`, `--machine`, `--org` |
+| `dvmctl trace get <traceId>`        | Fetch a trace by ID (isolate-dataset spans)                                   | `--no-color`                   |
+
+### Custom domains
+
+| Command                                 | Purpose                                         |
+| --------------------------------------- | ----------------------------------------------- |
+| `dvmctl domains add <slug> <domain>`    | Attach a custom domain (e.g. `api.example.com`); `--org` selects its org |
+| `dvmctl domains list <slug>`            | List attached domains; `--org` selects its org                              |
+| `dvmctl domains verify <slug> <domain>` | Verify DNS/TLS provisioning; `--org` selects its org                        |
+| `dvmctl domains remove <slug> <domain>` | Remove a custom domain; `--org` selects its org                             |
+
+### Revenue & payout
+
+Reporting, the path to collect your earnings off the Cashu accumulator, and the operator queues for refunds
+and settlements no automatic loop will ever clear.
+
+| Command                                | Purpose                                                              | Key flags                                                    |
+| -------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `dvmctl revenue summary`               | Totals + per-rail breakdown                                          | `--from`, `--to` (required), `--currency`                    |
+| `dvmctl revenue events`                | Individual revenue events                                            | `--from`, `--to`, `--rail`, `--limit`                        |
+| `dvmctl revenue csv`                   | Export revenue as CSV (**raw CSV output**)                           | `--from`, `--to` (required), `--currency`, `--rail`, `--out` |
+| `dvmctl set-payout <handle> <ln-addr>` | Persist the default Lightning payout address for `melt-pending`      | `--skip-preflight`, `--self-hosted`, `--org`                  |
+| `dvmctl melt-pending <handle>`         | Drain pending Cashu accumulator batches to the Lightning payout addr | `--payout`, `--endpoint`, `--watch`, `--interval`, `--org`   |
+| `dvmctl rotate <handle>`               | Rotate the per-DVM Cashu lock pubkey (publishes next BIP-32 child)   | `--endpoint`, `--org`                                        |
+| `dvmctl credit blocked <handle>`       | Lightning top-ups the ledger could never credit — the operator queue | `--include-resolved`, `--limit`, `--after`, `--endpoint`, `--org` |
+| `dvmctl credit reconcile <handle> <payment-hash>` | Credit a blocked payment onto a credit the caller holds    | `--credit-id` (required), `--endpoint`, `--org`              |
+| `dvmctl credit write-off <handle> <payment-hash>` | Reviewed, not crediting — moves no money, reversible       | `--note`, `--endpoint`, `--org`                               |
+| `dvmctl credit drains-owed <handle>`     | One-payment stablecoin refunds you owe (channel-backed ones settle themselves) | `--endpoint`, `--org`                              |
+| `dvmctl credit drain-settle <handle> <credit-id> <drain-id>` | Record a refund you sent on chain — idempotent   | `--tx` (required), `--note`, `--endpoint`, `--org`           |
+| `dvmctl credit x402-wedged <handle>`     | x402 refunds that settled on chain but never booked — the repair queue | `--include-resolved`, `--limit`, `--after`, `--min-age-ms`, `--no-evidence`, `--endpoint`, `--org` |
+| `dvmctl credit x402-reconcile <handle> <settlement-id>` | Finish one at the chain's own figure — never one you supply | `--endpoint`, `--org`                        |
+| `dvmctl credit x402-write-off <handle> <settlement-id>` | Reviewed, not booking — moves no money, reversible | `--note`, `--endpoint`, `--org`                    |
+| `dvmctl credit tempo-wedged <handle>`    | Tempo closes that landed on chain but never booked the drain | `--include-resolved`, `--limit`, `--after`, `--min-age-ms`, `--no-evidence`, `--endpoint`, `--org` |
+| `dvmctl credit tempo-reconcile <handle> <credit-id> <drain-id>` | Book one against the close receipt's own refund figure | `--endpoint`, `--org`                  |
+| `dvmctl credit tempo-write-off <handle> <credit-id> <drain-id>` | Reviewed, not booking — moves no money, reversible | `--note`, `--endpoint`, `--org`            |
+
+### Account, org & auth
+
+| Command                        | Purpose                                                  | Key flags                        |
+| ------------------------------ | -------------------------------------------------------- | -------------------------------- |
+| `dvmctl auth`                  | Authenticate with the platform                           | `--status`, `--logout`           |
+| `dvmctl switch [handle]`       | Set the active org context for deploys (omit = show)     | `--personal` (clear)             |
+| `dvmctl transfer <slug> <to>`  | Transfer a DVM to an org (by handle) or back to personal | `--create-org`, `--display-name`, `--org` |
+| `dvmctl api-keys list`         | List builder API keys                                    |                                  |
+| `dvmctl api-keys create`       | Create a builder API key                                 | `--label`                        |
+| `dvmctl api-keys revoke <id>`  | Revoke a builder API key                                 |                                  |
+| `dvmctl handle set <handle>`   | Claim a builder handle for `*.dvmkit.ai` subdomains      |                                  |
+| `dvmctl handle check <handle>` | Check handle availability                                |                                  |
+| `dvmctl identity create`       | Generate a per-workstation secp256k1 builder identity    | `--force`                        |
+| `dvmctl identity show`         | Print the builder identity pubkey                        |                                  |
+
+## Caller feedback
+
+Callers can send signed-envelope feedback about a DVM via `dvm feedback --dvm <slug> "..."` (or
+`--job <jobId>` to attach a trace_id). The platform persists every submission per-slug; as the
+builder, you read and toggle collection through `dvmctl feedback`.
+
+```bash
+dvmctl feedback list <slug>              # newest-first, JSON
+dvmctl feedback list <slug> --since 24h  # relative duration ("24h", "7d") or ISO 8601
+dvmctl feedback list <slug> --limit 100 --cursor <c> --org acme
+```
+
+`list` is cursor-paginated, capped at 100 per page (default 50). Walk older pages by passing the
+response's `next_cursor` back via `--cursor`. JSON shape:
+
+```json
+{
+  "slug": "...",
+  "feedback": [
+    { "id": "...", "slug": "...", "created_at": "...", "caller_pubkey": "...",
+      "body": "...", "trace_id": "..." | null, "job_id": "..." | null }
+  ],
+  "next_cursor": "..." | undefined
+}
+```
+
+Toggle collection per-DVM:
+
+```bash
+dvmctl feedback enable <slug>    # flips dvms.feedback_enabled = true
+dvmctl feedback disable <slug>   # flips dvms.feedback_enabled = false
+```
+
+When disabled, subsequent caller submissions to that slug fail with `409 feedback_disabled` and a
+`display` field the calling agent can relay to its user. `list` keeps returning previously-stored
+rows either way — the toggle gates collection, not retrieval.
+
+All three commands require `dvmctl auth` (org-scoped); `list` only returns feedback for DVMs owned
+by the authenticated org.
+
+---
+
+## Verification
+
+After writing or modifying DVM code, run the generated project's test command. Add project-owned
+`lint` and `typecheck` scripts before relying on them, then run all three from the project directory:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+**If the capability charges and calls a paid third-party API, there is a fourth rung** — the
+[live provider contract](testing.md#live-provider-contracts):
+
+```bash
+<PROVIDER_KEY>=… npm run test:providers:live
+```
+
+This is a project-owned opt-in script: add it as described in the
+[live provider contract](testing.md#live-provider-contracts). It is key-gated and spends real vendor
+money, so it skips cleanly without the key. If you don't have one, **say so** and hand the operator
+a green static pass — don't report the provider contract as verified when the suite skipped.

package/skills/build-dvm/references/patterns-auth.md

@@ -0,0 +1,390 @@
+## Patterns
+
+### Single-turn (simplest)
+
+```typescript
+import { configureDVM } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "Uppercase",
+  capability: "uppercase",
+  tags: ["text"],
+
+  onJob(ctx) {
+    ctx.complete(ctx.input.toUpperCase());
+  },
+});
+```
+
+### Multi-turn linear
+
+```typescript
+import { configureDVM } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "Translator",
+  capability: "translate",
+  tags: ["translation"],
+  price: "$0.02",
+  state: { detectedLanguage: "", targetLanguage: "" },
+
+  async onJob(ctx) {
+    const detected = await ctx.step("detect", async () => detectLanguage(ctx.input));
+    ctx.state.detectedLanguage = detected;
+    ctx.text(`Detected: ${detected}`);
+
+    const lang = await ctx.prompt("target-lang", `Translate to?`, {
+      options: ["Spanish", "French", "German"],
+    });
+    ctx.state.targetLanguage = lang.text;
+
+    ctx.text(`Translating to ${lang.text}...`);
+    const result = await ctx.step("translate", async () => translate(ctx.input, lang.text));
+
+    ctx.artifact({ data: result, mime_type: "text/plain" });
+    ctx.complete(`Translated to ${lang.text}`);
+  },
+});
+```
+
+### Event-driven (complex routing)
+
+```typescript
+import { configureDVM } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "Translator",
+  capability: "translate",
+  tags: ["translation"],
+  state: { original: "" },
+
+  onJob(ctx) {
+    ctx.state.original = ctx.input;
+    ctx.prompt("lang", "What language?", {
+      options: ["Spanish", "French", "German"],
+    });
+  },
+
+  async onResponse(ctx, content) {
+    const result = await translate(ctx.state.original, content.text);
+    ctx.complete(result);
+  },
+});
+```
+
+### Multi-capability DVM (cast's pattern)
+
+When several related operations share resources (a Postgres pool, an auth verifier, an S3
+bucket), declare them as capabilities on one DVM instead of mounting separate DVMs. This is what
+cast does — a podcast-feed DVM with one descriptor-level auth scheme covering four capabilities:
+
+```typescript
+import { configureDVM } from "@dvmkit/sdk";
+import { secp256k1Auth } from "@dvmkit/sdk/server";
+
+import { addEpisodeSchema, deleteEpisodeSchema, updateFeedSchema } from "./types";
+
+export function createCastDVM(runtime: CastRuntime) {
+  return configureDVM({
+    name: "cast",
+    description: "Host RSS feeds and episodes for podcast distribution",
+    tags: ["podcast", "rss", "feed", "audio"],
+    idleTimeout: 1800,
+
+    // Descriptor-level auth: one scheme gates every capability (see below).
+    auth: secp256k1Auth({ replayStore: runtime.replays, driftSeconds: 300 }),
+
+    onBoot(env) {
+      // validate env; runtime is already built by the time we reach here
+    },
+
+    capabilities: {
+      "add-episode": {
+        description: "Add an episode to a private RSS feed by audio URL",
+        input: addEpisodeSchema,
+        onQuote: {
+          schema: addEpisodeSchema,
+          handler: async (ctx) => quoteAddEpisode(ctx, runtime),
+        },
+        async onJob(ctx) {
+          await runAddEpisodeJob(ctx, runtime);
+        },
+      },
+
+      "update-feed": {
+        description: "Update per-feed metadata",
+        input: updateFeedSchema,
+        async onJob(ctx) {
+          await runUpdateFeedJob(ctx, runtime);
+        },
+      },
+
+      "delete-episode": {
+        description: "Delete a single episode",
+        input: deleteEpisodeSchema,
+        async onJob(ctx) {
+          await runDeleteEpisodeJob(ctx, runtime);
+        },
+      },
+    },
+
+    routes(app, { authAudience }) {
+      // see "Custom HTTP routes" below
+    },
+  });
+}
+```
+
+Callers target a capability by passing `capability: "add-episode"` on the job submission; the
+wire (`POST /v1/job`) always carries the capability name. Each capability has its own input
+schema, pricing, and quote handler; the DVM-level `auth`, `paymentMethods`, and `routes` are
+shared.
+
+### Stateful DVM — signed-request auth
+
+When a DVM owns persistent state (feeds, accounts, subscriptions) and must verify the caller owns
+the resource being acted on, require **signed requests**. Signatures are **secp256k1 with BIP-340
+Schnorr** over a versioned statement containing the exact input plus the attested DVM audience, HTTP method, concrete path, and capability, with timestamp-drift and replay protection. A proof for one DVM or operation cannot be replayed against another. This is a protocol invariant — caller auth and builder identity are always
+secp256k1+Schnorr via `@noble/curves`, never Ed25519 or another curve. Don't introduce other
+curves into auth/identity paths.
+
+The schema must include the envelope fields `pubkey`, `signature`, `timestamp`, `nonce` alongside the operation's payload fields. `auth_statement` is protocol-owned and the SDK removes it before builder schema parsing:
+
+```typescript
+import { z } from "@dvmkit/sdk";
+
+const addEpisodeSchema = z.object({
+  // payload
+  feed_id: z.string(),
+  audio_url: z.string().url(),
+  // envelope (the SDK verifies these)
+  pubkey: z.string(),
+  signature: z.string(),
+  timestamp: z.number().int(),
+  nonce: z.string(),
+});
+```
+
+**What gets verified is the raw wire body**, on `/v1/quote`, on the `/v1/job` submit and on the
+cross-machine reactivation re-verify alike (`signedRequestInput`, — never the
+Zod-parsed input. So your schema is free to fill defaults at any depth, coerce, or transform: the
+parse shapes what the handler receives, not what the signature covers. The one thing that must
+match is the wire body itself, which is why a client signs the payload it is about to send rather
+than a normalised copy of it.
+
+#### Canonical pattern — `auth: secp256k1Auth({...})` at descriptor level
+
+For most stateful DVMs, declare auth on the descriptor (shown in the cast example above). The SDK
+then publishes `secp256k1-schnorr-v2` plus its attested `auth_audience` on `/v1/info`, and rejects unsigned / stale / replayed or wrong-domain envelopes with HTTP 401 **before payment is taken or any
+handler runs**, and records the replay nonce only after upfront payment verifies,
+. Inside the handler, the verified caller identity is on `ctx.auth`:
+
+```typescript
+import { secp256k1Auth } from "@dvmkit/sdk/server";
+
+// auth: secp256k1Auth({
+//   replayStore: runtime.replays,   // omit for the bounded in-memory FIFO default
+//   driftSeconds: 300,              // ±5 min clock drift (default)
+// }),
+
+async onJob(ctx) {
+  // The envelope is already verified. ctx.auth.pubkey is the trusted caller key;
+  // ctx.auth.envelope holds the parsed payload, so no re-parsing is needed.
+  const pubkey = ctx.auth!.pubkey;
+  const { feed_id } = ctx.auth!.envelope as { feed_id: string };
+
+  if (!(await runtime.db.ownsFeed(pubkey, feed_id))) {
+    ctx.fail("auth_error: caller does not own this feed");
+    return;
+  }
+  // ...
+}
+```
+
+`replayStore` accepts a `PostgresReplayStore` (cross-instance, also from `@dvmkit/sdk/server`);
+omit it for a bounded in-memory FIFO default suitable for single-instance DVMs.
+
+#### Lower-level primitive — `createSignedRequestVerifier`
+
+When you need hands-on control on a custom route, use the verifier directly. The SDK passes the resolved audience to `routes(app, context)`; combine it with the live request method and URL so mount prefixes remain covered. The descriptor-level `secp256k1Auth` is built on the same primitive.
+
+```typescript
+import { createSignedRequestVerifier, SignedRequestError } from "@dvmkit/sdk/server";
+
+const verifier = createSignedRequestVerifier(addEpisodeSchema, {
+  driftSeconds: 300,          // ±5 min clock drift (default)
+  replayStore: replays,       // pass null to disable replay protection
+});
+
+routes(app, { authAudience }) {
+  if (!authAudience) throw new Error("signed route requires descriptor auth");
+  app.post("/private/feed", async (c) => {
+  try {
+    // Two-step: `checkAuth` is sync — schema → drift → signature.
+    // `recordReplay` is async — commits the nonce, throws on duplicate. Split
+    // so validation does not burn a nonce before the operation is accepted.
+    const signed = verifier.checkAuth(await c.req.json(), {
+      audience: authAudience,
+      method: c.req.method,
+      path: new URL(c.req.url).pathname,
+      capability: null,
+    });
+    await verifier.recordReplay(signed);
+    // signed.pubkey is now trusted — use it for ownership checks
+    if (!(await runtime.db.ownsFeed(signed.pubkey, signed.feed_id))) {
+      return c.json({ error: "auth_error" }, 401);
+    }
+    // ...
+  } catch (err) {
+    if (err instanceof SignedRequestError) {
+      return c.json({ error: "auth_error", sub_reason: err.sub_reason }, 401);
+    }
+    throw err;
+  }
+  });
+}
+```
+
+`verifier.checkAuth(input, domain)` returns the parsed input typed as `T & CanonicalEnvelope` on success
+and throws `SignedRequestError` (`sub_reason`: `schema_invalid` | `timestamp_drift` |
+`signature_invalid`). `verifier.recordReplay(envelope)` commits the nonce and throws
+`SignedRequestError` (`replay_detected`) on a duplicate. Pair them with your own error taxonomy
+for a domain-specific error code (cast wraps both as `auth_error`).
+
+In `onQuote` (and the 402-discovery hop), call `checkAuth` only — skip `recordReplay`. The caller creates a separate `/v1/job` proof because method/path/capability are signed; quote and submit never reuse a proof.
+
+`verifier.signRequest(privkey, body, opts?, domain)` is the matching client-side primitive — useful for
+round-trip tests that exercise the real crypto path:
+
+```typescript
+import { schnorr } from "@noble/curves/secp256k1.js";
+
+const { secretKey } = schnorr.keygen();
+const signed = verifier.signRequest(secretKey, {
+  feed_id: "morning-news",
+  audio_url: "https://example.com/episode-1.mp3",
+}, undefined, {
+  audience: authAudience,
+  method: "POST",
+  path: "/private/feed",
+  capability: null,
+});
+// signed.pubkey, signed.signature, signed.timestamp, signed.nonce are filled in.
+```
+
+### Refund-on-failure policy
+
+A failed job never debits — the draw is released, on every rail, with nothing to wire (see
+[Prepaid credit](pricing-credit.md#prepaid-credit)). `{ refund: true }` is a separate annotation recording that the failure
+was the caller's fault; the first-party DVMs all key it off an `OPERATOR_FAULT_CODES` set:
+
+```typescript
+const refund = !OPERATOR_FAULT_CODES.has(err.code) ? { refund: true } : undefined;
+ctx.fail(`[${err.code}] ${err.hint}`, refund);
+```
+
+Keep annotating — but don't rely on it moving money. Its one runtime branch (hand back a Cashu change token
+from proofs still held in-process) never fires under the P2PK-accumulator path, and no rail reverses a
+settled payment. What decides whether the caller can _reach_ the released value is your **`auth` slot**, not your
+`credit` block — the draw path never reads `credit`, it needs a verified pubkey. Without `auth` every caller is
+the pooled `anonymous` requester and an explicit draw is refused, so the money stays with you in practice. With
+`auth`, the release lands on a credit keyed to their pubkey and the failed job's receipt carries its `credit_id`,
+so the protocol lets them spend it down on the next job with nothing extra wired (the `dvm` CLI doesn't do that
+automatically yet. Offering credit is the further step
+that makes it _reclaimable as money_ — that's what `drain` and `POST /v1/credit` are gated on.
+
+### Signed receipts
+
+Every job that reaches a terminal status — `completed`, `failed`, `cancelled` — carries a signed
+`receipt` block on its response. **Nothing to wire:** `dvmctl deploy` derives the key
+from the builder identity only after the platform returns the immutable DVM ID, binds both into the
+attestation, and provisions it; the SDK signs at the terminal.
+
+```jsonc
+"receipt": {
+  "v": 1, "job_id": "job-a7571b-1", "dvm_id": "<immutable-id>", "dvm": "<slug>", "capability": "count",
+  "outcome": "completed",           // completed | failed | cancelled
+  "reason": null,                   // terminal reason on failed/cancelled
+  "seq": 4213,                      // per-DVM monotonic terminal counter
+  "issued_at": 1789300000,
+  "requester_pubkey": null,         // set when signed-request auth was used
+  "paid": { "msats": 19000, "rail": "cashu", "native_amount": null,
+            "native_asset": null, "tx_hash": null, "mint": "https://..." },
+  "result_hash": "<sha256 hex>",    // sha256(canonicalize({summary, artifact_hashes})); summary
+                                    // only on completed, null otherwise; null if nothing delivered
+  "receipt_pubkey": "<64-hex>",
+  "signature": "<128-hex>",         // BIP-340 over canonicaliseForSigning(receipt minus signature)
+  "credit": {                       // present when the payment funded/drew the credit ledger
+    "credit_id": "imp:cashu:…", "draw_id": "…", "amount": 10000,
+    "balance_after": 240000,        // settled draw: the recorded trajectory.
+                                    // released draw (failed/cancelled): restored available balance
+    "ledger_seq": 7                 // per-credit monotonic draw counter
+  }
+}
+```
+
+What a builder needs to know:
+
+- Same receipt on the synchronous 200, the poll, and every later re-read — signed once at the
+  terminal and persisted, not re-signed per response (JSON key order can differ; canonicalisation
+  is what the signature covers).
+- Free jobs get receipts too (`paid.msats: 0`); they consume a `seq` like any other job.
+- `/v1/info` advertises `receipts: true` only when a key is wired **and** the job store can issue
+  (`claimReceiptSeq` / `saveReceipt` — both built-in stores do), so absence is detectable. A custom
+  `jobStore` that can't warns `receipts_disabled_store_unsupported` at boot.
+- Signing failure never breaks a job: the SDK logs `receipt_issue_failed` and serves without one.
+- `dvmctl dev` / `devMode` boots mint an ephemeral key — receipts verify locally but nothing
+  attests them. Outside dev, no key means no receipts and no flag.
+- Isolate-runtime DVMs don't issue receipts yet.
+
+Verifying one (four links, all required): the signature verifies under `receipt_pubkey`; the receipt's
+immutable `dvm_id` equals `/v1/info#builder`'s `attestation.dvm_id`; `receipt_pubkey` equals that
+attestation's `receipt_pubkey`; and the attestation verifies under `builder.pubkey`. The slug stays
+signed display metadata, never the trust identity. Use the published caller command
+`dvm receipts verify <job-id>` to check a stored receipt rather than reimplementing its canonicalisation.
+
+### Custom HTTP routes
+
+Two seams:
+
+- `routes(app)` on the descriptor — routes that **belong to this DVM**. They register on the DVM's
+  Hono sub-app and inherit any mount prefix.
+- `host.app` on the host — routes that **belong to the host** (cross-DVM `/health`, cron-callable
+  maintenance, anything not tied to one DVM).
+
+DVM-scoped (cast feed XML):
+
+```typescript
+configureDVM({
+  name: "cast",
+  capabilities: {
+    /* ... */
+  },
+
+  routes(app) {
+    app.get("/feeds/:owner/:slug", async (c) => {
+      const xml = await renderFeed(c.req.param("owner"), c.req.param("slug"));
+      return c.body(xml, 200, { "Content-Type": "application/rss+xml" });
+    });
+  },
+});
+```
+
+Host-scoped (scrape's pool-aware `/health`, registered before `host.mount`):
+
+```typescript
+import { createDVMHost } from "@dvmkit/sdk/server";
+
+const host = createDVMHost();
+
+let shuttingDown = false;
+host.app.get("/health", (c) => {
+  if (shuttingDown) return c.json({ ok: false, draining: true }, 503);
+  return c.json({ ok: true, pool: runtime.pool.health() });
+});
+
+host.mount(createScrapeDVM(runtime));
+await host.serve();
+```
+
+---

package/skills/build-dvm/references/payment-rails.md

@@ -0,0 +1,11 @@
+# Payment rail limits for first builds
+
+Use Cashu FakeWallet for the local paid demonstration. It is the only supported builder-facing local payment path in the admitted SDK release.
+
+| Rail | First-build local proof | Current limit |
+| --- | --- | --- |
+| Cashu | Supported with a local Nutshell FakeWallet mint, disposable Postgres and builder/caller state. | Test value only; never deploy the test mint or key. Follow [Local Cashu paid test](local-cashu-test.md). |
+| x402 | No builder-facing x402-only local verification. | Do not configure a mainnet endpoint as a substitute for a test. |
+| Tempo | No supported builder-facing local test recipe. | The forthcoming Tempo testnet environment switches are not in the admitted SDK release. |
+
+Payment configuration for a deployed DVM belongs to the deployment decision. A successful Cashu test proves the local Cashu path only; it does not validate another rail, production credentials, payout, or real-money settlement.