@dvmkit/dvmctl 0.2.1-rc.2 → 0.3.1-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dvmkit/dvmctl",
-  "version": "0.2.1-rc.2",
+  "version": "0.3.1-rc.1",
   "description": "Builder CLI for creating, testing, and deploying Digital Vending Machines",
   "license": "Apache-2.0",
   "repository": {

package/skills/build-dvm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build-dvm
-description: Build a first DVM with dvmkit. Use when asked to turn an idea into a paid HTTPS capability, scaffold or hand-write a DVM, implement a `configureDVM` handler, run it locally, test it with Cashu FakeWallet funds, or prepare it for deployment. Do not use for changing the dvmkit platform, SDK internals, or a caller wallet unrelated to testing a DVM.
-compatibility: Node.js 22+, npm, the invited `@dvmkit/dvmctl` release, and Docker for the local paid Cashu test. The optional paid test also uses `@dvmkit/dvm-cli@0.2.0` with isolated builder and caller state.
+description: Build a first DVM with dvmkit. Use when asked to turn an idea into a paid HTTPS capability, scaffold or hand-write a DVM, implement a `configureDVM` handler, run it locally, verify Cashu, x402, or Tempo test payments, or prepare it for deployment. Do not use for changing the dvmkit platform, SDK internals, or a caller wallet unrelated to testing a DVM.
+compatibility: Node.js 22+, npm, the invited `@dvmkit/dvmctl` release, `@dvmkit/sdk@0.1.5-rc.9`, and `@dvmkit/dvm-cli@0.3.0`. Docker is needed only when this skill starts its local Cashu FakeWallet mint or performs a container build.
 allowed-tools: Bash Read Write Edit Glob Grep
 ---
 
@@ -39,11 +39,11 @@ For another harness, copy the same complete directory to that harness's project-
 
 Give the builder this canonical prompt after installation:
 
-> Help me build a DVM with dvmkit. Read the installed `build-dvm` skill. Interview me about one capability, its input, output, example, fiat price, and name. Write a short brief and wait for my approval. Then build and test it locally, including the optional Cashu FakeWallet paid-call path with isolated caller state. Do not deploy or use real funds without my approval.
+> Help me build a DVM with dvmkit. Read the installed `build-dvm` skill. Establish one capability, its name, typed input, output, example, fiat price, and a separate test-payment cap. Reuse any decisions and approval I already supplied; ask only for material choices that are still missing. Then implement it, run `dvmctl validate` and `dvmctl doctor`, and test it locally. Use only the approved test rail and cap, with isolated caller state. Do not deploy, connect a production wallet, or use real funds without my separate approval.
 
 ## 2. Shape one capability
 
-Ask only for the decisions that change the first version: input, result, one example, name, and a fiat price. Prefer one capability and one typed object input. Write this brief and get approval before editing:
+Ask only for missing decisions that change the first version: input, result, one example, name, and a fiat price. Prefer one capability and one typed object input. If the builder already supplied and approved a complete brief, reuse it instead of asking them to approve it again. Otherwise write this brief and get approval before editing:
 
 ```text
 Name:
@@ -61,26 +61,38 @@ The approved DVM price and the approved paid-test cap are different decisions. A
 
 Scaffold when it helps; a hand-written Node 22 project with `@dvmkit/sdk` is equally supported.
 
+For a hand-written project, pin the admitted SDK exactly:
+
+```bash
+npm install --save-exact @dvmkit/sdk@0.1.5-rc.9
+```
+
 ```bash
 dvmctl create my-dvm
 cd my-dvm
 npm install
 npm test
+dvmctl validate
+dvmctl doctor
 dvmctl dev handler.ts
 ```
 
 Keep `handler.ts` small: use `configureDVM`, a Zod `input` schema, a USD `price` string when paid, and `ctx.complete()` with a useful summary. Put provider keys in `.env`, never source code. Add a unit test using `createTestContext` before calling external services. Use the `/_dev` URL printed by `dvmctl dev` to show the builder the free result.
 
-Read [the SDK reference](references/sdk-reference.md) for descriptor shapes, job-context methods, streaming, dynamic quotes, auth, persistence, custom routes, and deployment. Read [the Cashu test reference](references/local-cashu-test.md) before a paid test.
+Read [the SDK reference](references/sdk-reference.md) for descriptor shapes, job-context methods, streaming, dynamic quotes, auth, persistence, custom routes, and deployment. `dvmctl validate` loads the real handler and checks its capability, schema, example, price, and tags. The `dev` banner states whether payments are skipped or really verified and prints the first caller command.
 
 ## 4. Exercise a paid local call with test money
 
-This is the only first-build paid path. It uses a local Cashu FakeWallet mint, which auto-settles test invoices and has no real value. Before starting, confirm a separate per-test dollar cap; approving the DVM's price alone is not payment approval. Then follow the complete [Local Cashu paid test](references/local-cashu-test.md). It isolates `DVMKIT_CONFIG_DIR`, `DVMCTL_CONFIG_DIR`, and `DVM_CONFIG_DIR`; uses self-hosted `dvmctl serve --dvm` with Postgres; and proves Cashu advertisement, an unpaid 402, the paid result, receipt, and balance decrease.
+Use the rail and cap in the approved brief. If either is missing, ask before moving value. Testnet and FakeWallet funds still need the separate cap; production funds always need separate approval. Follow the complete recipe for [Cashu](references/local-cashu-test.md), [x402 on Base Sepolia](references/local-x402-test.md), or [Tempo Moderato](references/local-tempo-test.md). Every recipe isolates `DVM_CONFIG_DIR`, runs `dvmctl dev` without Postgres, proves the advertised test rail and unpaid 402, makes one capped paid call with closed stdin, and verifies the stored receipt. Never label a mainnet rail as test money because the server is in dev mode.
 
 ## 5. Decide before deployment
 
 After the local result and paid test work, show the approved brief, test result, and the exact files changed. Ask whether to prepare deployment. Only then follow the invitation's account and deployment instructions. Production rails, payout configuration, wallet connections, and real funds are separate decisions.
 
+Run `dvmctl deploy --dry-run` before a real deploy; Docker is required for a container dry-run. A first real deploy needs a builder signing identity. In a noninteractive run, use `dvmctl deploy --create-identity`; in a terminal, `dvmctl deploy` offers to create the missing identity. Neither route prints the signing secret.
+
+Cashu accumulator operation also needs the separate recovery mnemonic created by `dvmctl lock create --human`. That command prints 12 recovery words only in human mode. Pause while the builder writes them down and require their explicit confirmation before continuing. Never infer that the backup happened, capture the words in a log, or replace an existing mnemonic without the builder's explicit instruction.
+
 ## Reference routing
 
 - [Configure and job context](references/configure-context.md): descriptor shapes, context methods, artifacts, cancellation, and costs.
@@ -89,5 +101,7 @@ After the local result and paid test work, show the approved brief, test result,
 - [Testing](references/testing.md): schemas, unit contexts, and live-provider boundaries.
 - [Running and deployment](references/running-deployment.md): dev server, host options, persistence, environment, and deployment.
 - [Operating and feedback](references/operating-feedback.md): deployed-DVM operations, revenue, and caller feedback.
-- [Local Cashu paid test](references/local-cashu-test.md): prerequisites, expected behavior, and failures.
-- [Rail limits](references/payment-rails.md): what can and cannot be tested locally today.
+- [Local Cashu paid test](references/local-cashu-test.md): FakeWallet or approved hosted-mint recipe.
+- [Local x402 paid test](references/local-x402-test.md): Base Sepolia USDC recipe.
+- [Local Tempo paid test](references/local-tempo-test.md): Moderato pathUSD recipe.
+- [Payment rails](references/payment-rails.md): test boundaries and production separation.

package/skills/build-dvm/references/local-cashu-test.md

@@ -1,28 +1,20 @@
 # Local Cashu paid test
 
-Use this only after the builder has approved both the DVM price and a separate dollar cap for this one test. A $0.01 DVM commonly needs a $0.02 cap because Cashu payments settle in whole satoshis. Do not infer approval or raise the cap after a refusal. This one shell session owns its temporary state, server process, Postgres container, and (unless `CASHU_MINT_URL` is supplied) FakeWallet container. It never stops an externally supplied mint.
+Use this after the builder approves the DVM price and a separate cap for one test payment. A `$0.01` price is fixed in dollars; the Cashu sats vary with the server's live quote. Derive the debit from the 402 and signed receipt. Never assume the server reads the caller's BTC-rate cache.
 
-The handler must have the approved static USD price and produce a useful completion summary or `ctx.artifact`. Replace the variables with the approved brief. For a named artifact, specify its name and MIME type; for JSON, also specify expected keys from the approved example. Leave the name and MIME values empty only when the completion summary is the whole result. Use `--data` for an object input; a deliberately primitive string input uses `-i` in the final request instead.
+The Docker-free default is the canonical hosted FakeWallet mint at `https://dvmkit-testmint.fly.dev`; override it only with another approved `CASHU_MINT_URL`. Set `CASHU_LOCAL_MINT=1` to opt into the owned Nutshell container fallback. Docker is needed only for that explicit fallback; `dvmctl dev` itself is Docker-free and needs no Postgres.
+
+Set the values from the approved brief. Object inputs use `--data`; keep stdin closed so the caller cannot wait on the terminal.
 
 ```bash
 set -euo pipefail
-
-DVM_HANDLE="my-dvm"
 DVM_CAPABILITY="uppercase"
 DVM_INPUT='{"text":"your approved example"}'
-DVM_PAYMENT_CAP='$0.02' # explicit approval for this test, separate from the $0.01 DVM price
-DVM_ARTIFACT_NAME="" # e.g. result.json; required when the handler emits an artifact
-DVM_ARTIFACT_MIME="" # e.g. application/json
-DVM_ARTIFACT_JSON_KEYS="" # comma-separated required keys, e.g. answer,language
+DVM_PAYMENT_CAP='$0.02'
 
 test_root="$(mktemp -d "${TMPDIR:-/tmp}/dvmkit-cashu-paid.XXXXXX")"
-export DVMKIT_CONFIG_DIR="$test_root/builder"
-export DVMCTL_CONFIG_DIR="$test_root/dvmctl"
 export DVM_CONFIG_DIR="$test_root/caller"
-mkdir -p "$DVMKIT_CONFIG_DIR" "$DVMCTL_CONFIG_DIR" "$DVM_CONFIG_DIR"
-
-postgres_name="dvmkit-cashu-postgres-$$"
-postgres_id=""
+mkdir -p "$DVM_CONFIG_DIR"
 mint_id=""
 dvm_pid=""
 cleanup() {
@@ -30,24 +22,13 @@ cleanup() {
   trap - EXIT INT TERM
   [ -z "$dvm_pid" ] || kill "$dvm_pid" 2>/dev/null || true
   [ -z "$mint_id" ] || docker rm -f "$mint_id" >/dev/null 2>&1 || true
-  [ -z "$postgres_id" ] || docker rm -f "$postgres_id" >/dev/null 2>&1 || true
   rm -rf "$test_root"
   exit "$status"
 }
 trap cleanup EXIT
 trap 'exit 130' INT TERM
 
-docker run --rm -d --name "$postgres_name" -e POSTGRES_PASSWORD=paid-test \
-  -p 127.0.0.1::5432 postgres:17-alpine >/dev/null
-postgres_id="$(docker container inspect --format '{{.Id}}' "$postgres_name")"
-for _ in $(seq 1 30); do docker exec "$postgres_id" pg_isready -U postgres -d postgres >/dev/null 2>&1 && break; sleep 1; done
-docker exec "$postgres_id" pg_isready -U postgres -d postgres >/dev/null
-postgres_port="$(docker port "$postgres_id" 5432/tcp | sed -E 's/.*:([0-9]+)$/\1/')"
-export DATABASE_URL="postgresql://postgres:paid-test@127.0.0.1:${postgres_port}/postgres"
-
-if [ -n "${CASHU_MINT_URL:-}" ]; then
-  cashu_mint_url="$CASHU_MINT_URL"
-else
+if [ "${CASHU_LOCAL_MINT:-0}" = "1" ]; then
   mint_name="dvmkit-cashu-mint-$$"
   docker run --rm -d --name "$mint_name" -p 127.0.0.1::3338 \
     -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 \
@@ -56,86 +37,67 @@ else
     cashubtc/nutshell:0.19.2 poetry run mint >/dev/null
   mint_id="$(docker container inspect --format '{{.Id}}' "$mint_name")"
   cashu_mint_url="http://127.0.0.1:$(docker port "$mint_id" 3338/tcp | sed -E 's/.*:([0-9]+)$/\1/')"
+else
+  cashu_mint_url="${CASHU_MINT_URL:-https://dvmkit-testmint.fly.dev}"
 fi
-for _ in $(seq 1 30); do curl -fsS "$cashu_mint_url/v1/info" >"$test_root/mint-info.json" && break; sleep 1; done
-test -s "$test_root/mint-info.json"
+for _ in $(seq 1 30); do
+  node -e 'fetch(process.argv[1]+"/v1/info",{signal:AbortSignal.timeout(2000)}).then(r=>{if(!r.ok)throw Error(`HTTP ${r.status}`)}).catch(()=>process.exit(1))' "${cashu_mint_url%/}" && break
+  sleep 1
+done
+node -e 'fetch(process.argv[1]+"/v1/info",{signal:AbortSignal.timeout(2000)}).then(r=>{if(!r.ok)throw Error(`HTTP ${r.status}`)}).catch(e=>{console.error(e.message);process.exit(1)})' "${cashu_mint_url%/}"
 
-dvmctl lock create
-dvmctl identity create
-dvmctl init "$DVM_HANDLE" --self-hosted
-dvm_port="$(node -e 'require("node:net").createServer().listen(0, "127.0.0.1", function () { console.log(this.address().port); this.close(); })')"
-DVMKIT_CASHU_MINTS="$cashu_mint_url" dvmctl serve handler.ts --dvm "$DVM_HANDLE" --port "$dvm_port" >"$test_root/dvm.log" 2>&1 &
+dvmctl validate
+dvmctl doctor
+dvm_port="$(node -e 'require("node:net").createServer().listen(0,"127.0.0.1",function(){console.log(this.address().port);this.close()})')"
+DVMKIT_CASHU_MINTS="$cashu_mint_url" dvmctl dev handler.ts --port "$dvm_port" >"$test_root/dvm.log" 2>&1 &
 dvm_pid=$!
 dvm_endpoint="http://127.0.0.1:$dvm_port"
-for _ in $(seq 1 30); do curl -fsS "$dvm_endpoint/v1/info" >"$test_root/info.json" && break; sleep 1; done
-test -s "$test_root/info.json"
-node -e 'const i=require(process.argv[1]); if (!i.payment?.methods?.includes("cashu")) throw new Error("/v1/info does not advertise cashu")' "$test_root/info.json"
+for _ in $(seq 1 30); do
+  node -e 'fetch(process.argv[1]+"/v1/info",{signal:AbortSignal.timeout(2000)}).then(async r=>{if(!r.ok)throw Error(`HTTP ${r.status}`);require("node:fs").writeFileSync(process.argv[2],await r.text())}).catch(()=>process.exit(1))' "$dvm_endpoint" "$test_root/info.json" && break
+  sleep 1
+done
+node -e 'const i=require(process.argv[1]);if(!i.payment?.methods?.includes("cashu"))throw Error("cashu is not advertised")' "$test_root/info.json"
 
-node -e 'process.stdout.write(JSON.stringify({capability:process.argv[1],data:JSON.parse(process.argv[2])}))' "$DVM_CAPABILITY" "$DVM_INPUT" >"$test_root/unpaid-request.json"
-unpaid_status="$(curl -sS -o "$test_root/unpaid.json" -w '%{http_code}' -H 'content-type: application/json' --data-binary @"$test_root/unpaid-request.json" "$dvm_endpoint/v1/job")"
-test "$unpaid_status" = 402
+node --input-type=module - "$dvm_endpoint" "$DVM_CAPABILITY" "$DVM_INPUT" "$test_root/unpaid.json" <<'NODE'
+import { writeFileSync } from "node:fs";
+const [endpoint, capability, input, output] = process.argv.slice(2);
+const response = await fetch(`${endpoint}/v1/job`, {
+  method: "POST", headers: { "content-type": "application/json" },
+  body: JSON.stringify({ capability, data: JSON.parse(input) }),
+  signal: AbortSignal.timeout(5000),
+});
+const body = await response.json();
+if (response.status !== 402 || body.error !== "payment_required" || !Number.isSafeInteger(body.required_msats) || body.required_msats <= 0 || body.required_msats % 1000 !== 0) {
+  throw new Error(`expected a valid Cashu 402, got ${response.status} ${JSON.stringify(body)}`);
+}
+writeFileSync(output, JSON.stringify(body));
+NODE
 
-npm install -g @dvmkit/dvm-cli@0.2.0
+npm install -g @dvmkit/dvm-cli@0.3.0
 dvm init
 dvm wallet init
 dvm wallet mint-add "$cashu_mint_url"
 dvm wallet fund '$1' --mint "$cashu_mint_url" --test-skip-lightning
-dvm wallet show >"$test_root/balance-before.json"
+dvm wallet show >"$test_root/before.json"
 dvm request --endpoint "$dvm_endpoint" --data "$DVM_INPUT" --rail cashu --mint "$cashu_mint_url" \
   --budget "$DVM_PAYMENT_CAP" --auto-pay-below "$DVM_PAYMENT_CAP" \
   --max-increment "$DVM_PAYMENT_CAP" --max-payments 1 </dev/null >"$test_root/paid.json"
-dvm wallet show >"$test_root/balance-after.json"
-node -e '
-const before=require(process.argv[1]).total_sats;
-const after=require(process.argv[2]).total_sats;
-const paid=require(process.argv[3]);
-if (!(typeof before === "number" && typeof after === "number" && after < before)) throw new Error("Cashu balance did not decrease");
-if (!paid.jobId || paid.next_action !== null || paid.receipt_verified !== "verified") throw new Error("paid receipt is not verified");
-if (paid.receipt?.outcome !== "completed" || paid.receipt?.paid?.rail !== "cashu" || !(paid.receipt.paid.msats > 0)) throw new Error("receipt does not prove a positive Cashu payment for a completed job");
-if (!(paid.summary || paid.has_artifacts)) throw new Error("paid result has no completion output");
-' "$test_root/balance-before.json" "$test_root/balance-after.json" "$test_root/paid.json"
-if [ -n "$DVM_ARTIFACT_NAME" ]; then
-  node -e 'if (!require(process.argv[1]).has_artifacts) throw new Error("expected artifact is missing")' "$test_root/paid.json"
-  test -n "$DVM_ARTIFACT_NAME" && test -n "$DVM_ARTIFACT_MIME"
-  case "$DVM_ARTIFACT_MIME" in application/json*) test -n "$DVM_ARTIFACT_JSON_KEYS" ;; esac
-  job_id="$(node -p 'require(process.argv[1]).jobId' "$test_root/paid.json")"
-  dvm messages "$job_id" --no-stream >"$test_root/artifacts.json"
-  cat "$test_root/artifacts.json"
-  node -e '
-const m=require(process.argv[1]).messages.filter((m) => m.type === "artifact");
-if (!m.length) throw new Error("artifact content is missing");
-const [name, mime, keys]=process.argv.slice(2);
-Promise.all(m.map(async ({content}) => {
-  let bytes;
-  if (typeof content?.data === "string" && content.data.length > 0) {
-    bytes=Buffer.from(content.data, content.encoding === "base64" ? "base64" : "utf8");
-  } else if (typeof content?.url === "string") {
-    const response=await fetch(content.url);
-    bytes=Buffer.from(await response.arrayBuffer());
-    if (!response.ok || bytes.byteLength === 0) throw new Error("artifact URL did not return content");
-  } else {
-    throw new Error("artifact content is missing");
-  }
-  const name=typeof content.name === "string" ? content.name :
-    content.name?._source === "provider" && typeof content.name.text === "string" ? content.name.text : undefined;
-  return {name, mime_type: content.mime_type, bytes_base64: bytes.toString("base64"), text: bytes.toString("utf8")};
-})).then((artifacts) => {
-  const artifact=artifacts.find((a) => a.name === name && a.mime_type === mime);
-  if (!artifact) throw new Error("expected artifact name or MIME type is missing");
-  if (keys) { const value=JSON.parse(artifact.text); for (const key of keys.split(",")) if (!(key in value)) throw new Error(`artifact JSON is missing ${key}`); }
-  console.log(JSON.stringify({artifact}));
-});' "$test_root/artifacts.json" "$DVM_ARTIFACT_NAME" "$DVM_ARTIFACT_MIME" "$DVM_ARTIFACT_JSON_KEYS" >"$test_root/artifact-content.json"
-  cat "$test_root/artifact-content.json"
-fi
+dvm wallet show >"$test_root/after.json"
+job_id="$(node -p 'require(process.argv[1]).jobId' "$test_root/paid.json")"
+dvm receipts verify "$job_id" >"$test_root/verified.json"
+node - "$test_root/unpaid.json" "$test_root/before.json" "$test_root/after.json" "$test_root/paid.json" "$test_root/verified.json" <<'NODE'
+const [challengePath, beforePath, afterPath, paidPath, verifiedPath] = process.argv.slice(2);
+const challenge=require(challengePath), before=require(beforePath), after=require(afterPath), paid=require(paidPath), verified=require(verifiedPath);
+const validReceiptStatuses = new Set(["verified", "verified_unattested"]);
+const expectedSats=challenge.required_msats/1000;
+if (before.total_sats-after.total_sats !== expectedSats) throw Error(`Cashu debit was ${before.total_sats-after.total_sats}, quote was ${expectedSats} sats`);
+if (!paid.jobId || paid.next_action !== null || !validReceiptStatuses.has(paid.receipt_verified)) throw Error("paid result is not terminal with a valid receipt signature");
+if (paid.receipt?.outcome !== "completed" || paid.receipt?.paid?.rail !== "cashu" || paid.receipt.paid.msats !== challenge.required_msats) throw Error("receipt is not bound to the 402 quote");
+if (verified.job_id !== paid.jobId || !validReceiptStatuses.has(verified.receipt_verified)) throw Error("stored receipt signature did not verify");
+NODE
 cat "$test_root/paid.json"
 ```
 
-The final JSON is the evidence artifact: it must show a terminal paid job and verified Cashu receipt, while the assertions prove Cashu was advertised, the same unauthenticated request returned 402, and the isolated balance fell. When the approved result is a named artifact, the recipe fetches URL content or decodes inline data, then checks its name, MIME type, and expected JSON keys. Add a stricter assertion for any deeper approved schema before counting the test as passed; the generic recipe cannot infer it. The trap deletes only the state and processes this session created. The FakeWallet key and funds are test-only; do not point this recipe at a production mint.
-
-## Failure routing
+The observed hosted-mint acceptance for a `$0.01` call quoted `12000` msats and debited `12` test sats. That is evidence from that rate snapshot, not a constant for future runs.
 
-- `/v1/info` lacks `cashu`: do not retry with `dvmctl dev`. Confirm the three disposable configuration directories are exported, then rerun `lock create`, `identity create`, `init --self-hosted`, and `serve --dvm` in this session.
-- The unpaid request is not 402: confirm the handler's approved price and capability/input values before spending test money.
-- `fx_rate_unavailable` or `rate_unavailable`: the public BTC/USD rate provider could not answer. Wait for recovery before retrying, keeping the same approved dollar cap. A DVM-side test rate source does not configure the caller’s rate provider.
-- The paid request exceeds the cap: stop and ask for a new explicit dollar cap. Do not increase any flag automatically.
-- The mint cannot be reached: start the owned FakeWallet or correct `CASHU_MINT_URL`; an externally supplied mint remains outside this session's cleanup.
+Stop on any cap refusal and ask for a new explicit cap. Do not raise flags automatically. A failed mint probe names the exact mint that must recover or be corrected.

package/skills/build-dvm/references/local-tempo-test.md

@@ -0,0 +1,72 @@
+# Local Tempo paid test on Moderato
+
+Use this only after the builder approves a test-payment cap. Moderato is Tempo's public testnet (chain 42431); `dvm wallet fund --rail tempo` uses its official programmatic faucet. These tokens have no real value. Never substitute Tempo mainnet.
+
+```bash
+set -euo pipefail
+DVM_CAPABILITY="uppercase"
+DVM_INPUT='{"text":"your approved example"}'
+DVM_PAYMENT_CAP='$0.02'
+
+test_root="$(mktemp -d "${TMPDIR:-/tmp}/dvmkit-tempo-paid.XXXXXX")"
+export DVM_CONFIG_DIR="$test_root/caller"
+mkdir -p "$DVM_CONFIG_DIR"
+dvm_pid=""
+cleanup() { status=$?; trap - EXIT INT TERM; [ -z "$dvm_pid" ] || kill "$dvm_pid" 2>/dev/null || true; rm -rf "$test_root"; exit "$status"; }
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+node --input-type=module <<'NODE'
+const response=await fetch("https://rpc.moderato.tempo.xyz",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({jsonrpc:"2.0",id:1,method:"eth_chainId",params:[]}),signal:AbortSignal.timeout(5000)});
+const body=await response.json();
+if(!response.ok || body.result!=="0xa5bf") throw Error(`Moderato RPC mismatch: ${response.status} ${JSON.stringify(body)}`);
+NODE
+
+recipient="0x$(node -e 'process.stdout.write(require("node:crypto").randomBytes(20).toString("hex"))')"
+tempo_secret="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
+dvmctl validate
+dvmctl doctor
+dvm_port="$(node -e 'require("node:net").createServer().listen(0,"127.0.0.1",function(){console.log(this.address().port);this.close()})')"
+env DVMKIT_TEMPO_RECIPIENT="$recipient" DVMKIT_TEMPO_SECRET_KEY="$tempo_secret" \
+  DVMKIT_TEMPO_TESTNET=true DVMKIT_TEMPO_RPC_URL="https://rpc.moderato.tempo.xyz" \
+  dvmctl dev handler.ts --port "$dvm_port" >"$test_root/dvm.log" 2>&1 &
+dvm_pid=$!
+dvm_endpoint="http://127.0.0.1:$dvm_port"
+for _ in $(seq 1 30); do
+  node -e 'fetch(process.argv[1]+"/v1/info",{signal:AbortSignal.timeout(2000)}).then(async r=>{if(!r.ok)throw Error(`HTTP ${r.status}`);require("node:fs").writeFileSync(process.argv[2],await r.text())}).catch(()=>process.exit(1))' "$dvm_endpoint" "$test_root/info.json" && break
+  sleep 1
+done
+node -e 'const i=require(process.argv[1]);if(i.tempo?.chain_id!==42431)throw Error("Moderato is not advertised")' "$test_root/info.json"
+
+node --input-type=module - "$dvm_endpoint" "$DVM_CAPABILITY" "$DVM_INPUT" "$test_root/unpaid.json" <<'NODE'
+import { writeFileSync } from "node:fs";
+const [endpoint, capability, input, output] = process.argv.slice(2);
+const response=await fetch(`${endpoint}/v1/job`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({capability,data:JSON.parse(input)}),signal:AbortSignal.timeout(5000)});
+const body=await response.json();
+if(response.status!==402 || body.error!=="payment_required" || !Number.isSafeInteger(body.required_msats) || body.required_msats<=0) throw Error(`expected valid 402, got ${response.status} ${JSON.stringify(body)}`);
+writeFileSync(output,JSON.stringify(body));
+NODE
+
+npm install -g @dvmkit/dvm-cli@0.3.0
+dvm init
+dvm wallet tempo-connect --network moderato
+dvm wallet fund '$1' --rail tempo
+dvm wallet balance >"$test_root/balance.json"
+dvm request --endpoint "$dvm_endpoint" --data "$DVM_INPUT" --rail tempo \
+  --budget "$DVM_PAYMENT_CAP" --auto-pay-below "$DVM_PAYMENT_CAP" \
+  --max-increment "$DVM_PAYMENT_CAP" --max-payments 1 </dev/null >"$test_root/paid.json"
+job_id="$(node -p 'require(process.argv[1]).jobId' "$test_root/paid.json")"
+dvm receipts verify "$job_id" >"$test_root/verified.json"
+node - "$test_root/unpaid.json" "$test_root/paid.json" "$test_root/verified.json" <<'NODE'
+const [challengePath,paidPath,verifiedPath]=process.argv.slice(2);const challenge=require(challengePath),paid=require(paidPath),verified=require(verifiedPath);
+const validReceiptStatuses=new Set(["verified","verified_unattested"]);
+if(!paid.jobId || paid.next_action!==null || !validReceiptStatuses.has(paid.receipt_verified)) throw Error("paid result is not terminal with a valid receipt signature");
+const receipt=paid.receipt;
+if(receipt?.outcome!=="completed" || receipt?.paid?.rail!=="tempo" || receipt.paid.msats!==challenge.required_msats) throw Error("receipt is not quote-bound Tempo");
+if(receipt.paid.native_amount!==10000 || receipt.paid.native_asset!=="usdc") throw Error("$0.01 must settle as exactly 10000 pathUSD micro-units");
+if(verified.job_id!==paid.jobId || !validReceiptStatuses.has(verified.receipt_verified)) throw Error("stored receipt signature did not verify");
+NODE
+cat "$test_root/paid.json"
+```
+
+Stop if the Moderato chain check, faucet, balance, or cap fails. Do not switch to mainnet or fund a production wallet as a workaround.

package/skills/build-dvm/references/local-x402-test.md

@@ -0,0 +1,74 @@
+# Local x402 paid test on Base Sepolia
+
+Use this only after the builder approves a test-payment cap and supplies a Base Sepolia wallet containing at least the approved amount in test USDC. Base Sepolia has no unattended public faucet. Never substitute Base mainnet or a production key.
+
+```bash
+set -euo pipefail
+DVM_CAPABILITY="uppercase"
+DVM_INPUT='{"text":"your approved example"}'
+DVM_PAYMENT_CAP='$0.02'
+X402_TESTNET_KEY_FILE="/absolute/path/to/base-sepolia-test-key"
+
+test_root="$(mktemp -d "${TMPDIR:-/tmp}/dvmkit-x402-paid.XXXXXX")"
+export DVM_CONFIG_DIR="$test_root/caller"
+mkdir -p "$DVM_CONFIG_DIR"
+dvm_pid=""
+cleanup() { status=$?; trap - EXIT INT TERM; [ -z "$dvm_pid" ] || kill "$dvm_pid" 2>/dev/null || true; rm -rf "$test_root"; exit "$status"; }
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+test -f "$X402_TESTNET_KEY_FILE"
+node --input-type=module <<'NODE'
+const rpc = await fetch("https://sepolia.base.org", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({jsonrpc:"2.0",id:1,method:"eth_chainId",params:[]}), signal: AbortSignal.timeout(5000) });
+const body = await rpc.json();
+if (!rpc.ok || body.result !== "0x14a34") throw new Error(`Base Sepolia RPC mismatch: ${rpc.status} ${JSON.stringify(body)}`);
+const facilitator = await fetch("https://x402.org/facilitator/supported", { signal: AbortSignal.timeout(5000) });
+if (!facilitator.ok) throw new Error(`x402 facilitator HTTP ${facilitator.status}`);
+NODE
+
+recipient="0x$(node -e 'process.stdout.write(require("node:crypto").randomBytes(20).toString("hex"))')"
+dvmctl validate
+dvmctl doctor
+dvm_port="$(node -e 'require("node:net").createServer().listen(0,"127.0.0.1",function(){console.log(this.address().port);this.close()})')"
+env DVMKIT_X402_PAY_TO="$recipient" DVMKIT_X402_NETWORK="eip155:84532" \
+  DVMKIT_X402_FACILITATOR="https://x402.org/facilitator" \
+  dvmctl dev handler.ts --port "$dvm_port" >"$test_root/dvm.log" 2>&1 &
+dvm_pid=$!
+dvm_endpoint="http://127.0.0.1:$dvm_port"
+for _ in $(seq 1 30); do
+  node -e 'fetch(process.argv[1]+"/v1/info",{signal:AbortSignal.timeout(2000)}).then(async r=>{if(!r.ok)throw Error(`HTTP ${r.status}`);require("node:fs").writeFileSync(process.argv[2],await r.text())}).catch(()=>process.exit(1))' "$dvm_endpoint" "$test_root/info.json" && break
+  sleep 1
+done
+node -e 'const i=require(process.argv[1]);if(i.x402?.network!=="eip155:84532")throw Error("Base Sepolia is not advertised")' "$test_root/info.json"
+
+node --input-type=module - "$dvm_endpoint" "$DVM_CAPABILITY" "$DVM_INPUT" "$test_root/unpaid.json" <<'NODE'
+import { writeFileSync } from "node:fs";
+const [endpoint, capability, input, output] = process.argv.slice(2);
+const response = await fetch(`${endpoint}/v1/job`, { method:"POST", headers:{"content-type":"application/json"}, body:JSON.stringify({capability,data:JSON.parse(input)}), signal:AbortSignal.timeout(5000) });
+const body=await response.json();
+if(response.status!==402 || body.error!=="payment_required" || !Number.isSafeInteger(body.required_msats) || body.required_msats<=0) throw Error(`expected valid 402, got ${response.status} ${JSON.stringify(body)}`);
+writeFileSync(output,JSON.stringify(body));
+NODE
+
+npm install -g @dvmkit/dvm-cli@0.3.0
+dvm init
+dvm wallet x402-connect --key-file "$X402_TESTNET_KEY_FILE" --network "eip155:84532"
+dvm wallet balance >"$test_root/balance.json"
+dvm request --endpoint "$dvm_endpoint" --data "$DVM_INPUT" --rail x402 \
+  --budget "$DVM_PAYMENT_CAP" --auto-pay-below "$DVM_PAYMENT_CAP" \
+  --max-increment "$DVM_PAYMENT_CAP" --max-payments 1 </dev/null >"$test_root/paid.json"
+job_id="$(node -p 'require(process.argv[1]).jobId' "$test_root/paid.json")"
+dvm receipts verify "$job_id" >"$test_root/verified.json"
+node - "$test_root/unpaid.json" "$test_root/paid.json" "$test_root/verified.json" <<'NODE'
+const [challengePath,paidPath,verifiedPath]=process.argv.slice(2);const challenge=require(challengePath),paid=require(paidPath),verified=require(verifiedPath);
+const validReceiptStatuses=new Set(["verified","verified_unattested"]);
+if(!paid.jobId || paid.next_action!==null || !validReceiptStatuses.has(paid.receipt_verified)) throw Error("paid result is not terminal with a valid receipt signature");
+const receipt=paid.receipt;
+if(receipt?.outcome!=="completed" || receipt?.paid?.rail!=="x402" || receipt.paid.msats!==challenge.required_msats) throw Error("receipt is not quote-bound x402");
+if(receipt.paid.native_amount!==10000 || receipt.paid.native_asset!=="usdc") throw Error("$0.01 must settle as exactly 10000 micro-USDC");
+if(verified.job_id!==paid.jobId || !validReceiptStatuses.has(verified.receipt_verified)) throw Error("stored receipt signature did not verify");
+NODE
+cat "$test_root/paid.json"
+```
+
+Stop on a missing balance, RPC/facilitator failure, or cap refusal. Do not replace the network, key, or cap without new approval.

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

@@ -1,11 +1,11 @@
-# Payment rail limits for first builds
+# Payment rails 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.
+`dvmctl dev` skips payment verification only when no rail is configured. When a rail is configured, the SDK verifies and settles its real credential, uses disposable in-process job/payment state, and reports completed paid jobs in the terminal. A dev server does not turn mainnet funds into test funds.
 
-| Rail | First-build local proof | Current limit |
+| Rail | First-build proof | Test boundary |
 | --- | --- | --- |
-| 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. |
+| Cashu | [Cashu recipe](local-cashu-test.md) with a local FakeWallet or explicitly approved hosted test mint. | The receipt's quoted msats and exact wallet debit are authoritative. |
+| x402 | [x402 recipe](local-x402-test.md) on Base Sepolia (`eip155:84532`). | Requires a separately funded testnet key and an approved micro-USDC cap. Never substitute Base mainnet. |
+| Tempo | [Tempo recipe](local-tempo-test.md) on Moderato (chain 42431). | `dvm wallet fund --rail tempo` uses the official testnet faucet. Never substitute Tempo mainnet. |
 
-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.
+A successful test proves only the selected local rail and test network. Production recipients, mints, facilitator credentials, payout settings, wallet connections, and funds are deployment decisions with separate approval.

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

@@ -11,13 +11,13 @@ Port resolution: `--port` > `.env PORT` > `process.env.PORT` > `3000`.
 
 Handler resolution: default export > `dvm` named export > first `DVMDescriptor` export.
 
-The dev server auto-credits payments — upfront and mid-job alike — **only while no mints are
-configured**, so a priced handler runs with no wallet in sight. A mint alone starts Cashu accumulator
-mode but does not supply its lock pubkey, durable DVM ID, or Postgres store, so it does not advertise
-Cashu. Use the complete [Local Cashu paid test](local-cashu-test.md) for the self-hosted `dvmctl serve
---dvm` path. `dvmctl dev` itself serves a test page at `/_dev` for
-interactive testing, whose auto-approve button satisfies a mid-job ask with a proofless `dev_auto`
-flag no non-dev server admits. Drive it from another terminal with the `dvm` CLI:
+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
@@ -133,12 +133,12 @@ the scaffold already lists it.
 The scaffold ships a Dockerfile and wires `npm run deploy` → `dvmctl deploy`. The cloud path:
 
 ```bash
-dvmctl validate          # fast local check: slug, package.json, vmConfig — JSON out, no Docker
+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's instant and emits `{"status":"ok", ...}`.
+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.