A USD send says it needs a quote_id but not how to get one #39

What happened

The agent paid from a USD wallet:

voltage payments send --account me --org ORG --env ENV --wallet USD_WALLET \
  --currency usd --invoice INVOICE

It exited with code 2: USD payment flows require an explicit quote_id. To recover, the
agent had to:

1. grep README.md to learn that quotes come from quotes create on a USD line of
   credit,
2. run credit-lines list to find the line of credit ID,
3. run price and work out the conversion by hand.

Why it was confusing

• The message uses the API field name quote_id. The flag is --quote.
• The message names no next command. It does not say that the quote must come from the
  wallet's USD line of credit, or that its amount must equal the invoice amount (see
  2026-10-14-sub-cent-invoice-from-usd-wallet).
• Cheapest fix: "pass --quote QUOTE_ID; create one with voltage quotes create --credit-line CREDIT_LINE_ID --network NETWORK --amount AMOUNT --unit usd --to btc --execute (find the line with voltage credit-lines list)". A better fix is for
  payments send --currency usd --invoice to create the matching quote itself, after
  the user confirms.

Provenance

• Found 2026-10-14 during a Claude Code session ("pay this invoice").
• Branch feat/cli-human-output, commit a060712, voltage 0.1.0 (a060712).
• Deployment: staging, a USD wallet on mutinynet.

Status on other branches

• feat/cli-help-examples (and the branches stacked on it) adds a quotes create
  example to help. That helps, but only after you know to look there.
• On feat/cli-error-hints, the message in src/input.rs is still the same.

Reproduction

repro.sh runs offline with --dry-run, placeholder IDs, and a placeholder invoice. The
check is local and runs before the invoice is parsed.

# docs/issues/2026-10-14-usd-send-quote-error-no-next-step/repro.sh
#!/usr/bin/env bash
PIN=a060712
source "$(git rev-parse --show-toplevel)/docs/issues/lib.sh"
build
Z=00000000-0000-4000-8000-000000000000
try payments send --dry-run --org $Z --env $Z --wallet $Z --currency usd \
  --invoice INVOICE  # the check runs before the invoice is parsed
# expected: a hint naming --quote and quotes create. actual: "explicit quote_id", exit 2

#!/usr/bin/env bash
# Shared setup for issue reproductions. Source it from a repro.sh after setting PIN.
set -euo pipefail
root=$(git rev-parse --show-toplevel)
cd "$root"
head=$(git rev-parse --short HEAD)
if [ "${PIN:-}" != "" ] && [ "$head" != "$PIN" ]; then
  echo "note: HEAD is $head; the issue was found at $PIN (git switch --detach $PIN to match)" >&2
fi
voltage() { "$root/scripts/voltage-staging" "$@"; }
need() { for v in "$@"; do [ -n "${!v:-}" ] || { echo "set $v first" >&2; exit 64; }; done; }
build() { "$root/scripts/voltage-staging" --build >/dev/null 2>&1; }
# Run a command, print its exit code, and never stop the script.
try() { echo "\$ voltage $*" >&2; set +e; voltage "$@"; echo "exit=$?" >&2; set -e; }

Run with nix develop --command ./docs/issues/2026-10-14-usd-send-quote-error-no-next-step/repro.sh (see the agent friction log in AGENTS.md, #33).

Progress on master (b25c05d, 2026-10-20)

Done:

• When the API rejects a payment with quote_required, the hint names voltage quotes create, voltage quotes get QUOTE_ID, and --quote QUOTE_ID. feat(cli): name the next command in scope, credential, and login errors #24
• --help for quotes create shows a USD quote example. feat(cli): show examples and a guide link in every command's help #27
• docs/guides/troubleshooting.md has a quote_required entry, and docs/guides/payments.md shows the quote-then-pay flow. docs: add troubleshooting, getting started, a changelog, its CI check, and a PR template #29, docs: add wallet and webhook guides and dry-run every documented change #26

Left:

• The local check is unchanged: payments send --currency usd without --quote fails with USD payment flows require an explicit quote_id (src/input.rs), with no hint. It should name --quote and the quotes create command, and credit-lines list to find the line.
• Optional: payments send --currency usd --invoice creates the matching quote itself, after the user confirms.