@ixo/decision-oracle 0.2.31 → 0.2.33

package/README.md

@@ -43,9 +43,10 @@ publishing a protocol and its rubric, and for anyone who needs a claim judged th
 - **Be an OpenHands checker with one flag.** `init --openhands` wires the add-on: the OpenHands
   app's hire webhook makes your oracle authorize itself on each ask that picked it, register it and
   start judging, with a backstop that keeps every hired ask topped up.
-- **Drive all of it with the shipped Claude skills.** `init` copies eight skills into
+- **Drive all of it with the shipped Claude skills.** `init` copies ten skills into
   `.claude/skills/`: `create-oracle`, `write-facts`, `create-rubric`, `publish-protocol`,
-  `create-collection`, `decision-api-oracle`, `decision-api-client`, `add-openhands-support`.
+  `create-collection`, `decision-api-oracle`, `decision-api-client`, `add-openhands-support`,
+  `update-pricing`, `operate-oracle`.
 
 ## How it works
 
@@ -738,7 +739,7 @@ packages/eval-oracle/         THE package — @ixo/decision-oracle
   src/                        the Worker: routes, workflows, the facts lane, the CLI
   src/facts/  src/testing/    the two node-safe public subpaths
   migrations/                 the D1 migrations — shipped, never hand-written by a consumer
-  skills/                     the eight Claude skills `init` copies into a new project
+  skills/                     the ten Claude skills `init` copies into a new project
   templates/project/          exactly what `decision-oracle init` generates
   dev/                        engine-conformance harnesses (ours, not published)
   docs/                       api.md (the API reference) + guide.md (the walkthrough)
@@ -786,6 +787,6 @@ symlinks are not packed). CI diffs them — change one, copy it to the other.
 
 ## Status
 
-Published on npm: `@ixo/decision-oracle` 0.2.31 and `@ixo/decision-oracle-client` 0.1.3.
+Published on npm: `@ixo/decision-oracle` 0.2.33 and `@ixo/decision-oracle-client` 0.1.3.
 
 Apache License 2.0: `LICENSE` at the repo root and in each package.

package/docs/guide.md

@@ -71,7 +71,7 @@ bun run cf-typegen
 | `wrangler.jsonc` | **yours to fill** | Bindings, vars, the cron, the custom domains. Binding and var **names are the package's contract** — never rename one |
 | `.dev.vars` | **yours, never committed** | Local secrets. `.dev.vars.example` lists every one with what it does |
 | `tsconfig.json`, `biome.json`, `vitest.config.ts`, `package.json` | generated | Scripts: `dev`, `deploy`, `deploy:devnet`, `deploy:testnet`, `deploy:production`, `build`, `cf-typegen`, `db:migrate`, `db:migrate:remote`, `test`, `typecheck`, `lint`, `check` |
-| `.claude/skills/` | shipped | The six skills below. Refresh after an upgrade: `bunx decision-oracle skills sync` |
+| `.claude/skills/` | shipped | The ten skills in §14. Refresh after an upgrade: `bunx decision-oracle skills sync` |
 | `CLAUDE.md` | shipped | The two rules, and where the package docs live |
 
 Everything else — pulling claims, the engine handshake, the D1 ledgers, review folds, the chain
@@ -1652,7 +1652,7 @@ own retries, and a terminal failure clears it.
 
 ## 14. For AI agents working in a generated project
 
-Six skills ship with the package and are copied into `.claude/skills/` by `init` (refresh with
+Ten skills ship with the package and are copied into `.claude/skills/` by `init` (refresh with
 `bunx decision-oracle skills sync`). Invoke the one that matches the job rather than improvising:
 
 | Job | Skill |
@@ -1663,6 +1663,10 @@ Six skills ship with the package and are copied into `.claude/skills/` by `init`
 | Anchor a claim form and rubric as an on-chain protocol entity | `publish-protocol` |
 | Create a deed and a claim collection, fund it, grant the roles | `create-collection` |
 | Turn on, deploy and verify the Decision API lane (`API_LANE`) — engine registration (payable at once on the Standard plan), operator sources and keys, verifying it | `decision-api-oracle` |
+| Call a Decision API oracle as a customer — test credentials, the SDK and CLI, MCP, paying | `decision-api-client` |
+| Make the oracle hireable from the Openhands app (`init --openhands`) | `add-openhands-support` |
+| Change what the oracle charges, and refresh the card apps show | `update-pricing` |
+| Run a deployed oracle — upgrades, pauses, renewals, reviews, alerts, admin top-ups | `operate-oracle` |
 
 And the three rules that matter more than any of them:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "license": "Apache-2.0",
   "description": "Run an IXO evaluation oracle: pull claims, produce facts with your handlers, let the decision engine decide, sign on chain",
   "keywords": [

package/skills/README.md

@@ -11,11 +11,13 @@ installed package (leaving any skill of your own in that directory alone).
 | `create-rubric` | authoring a rubric for a claim form and validating it against the engine |
 | `publish-protocol` | anchoring a claim form and rubric on chain as a protocol entity |
 | `create-collection` | creating a claim collection an oracle can be hired against |
-| `decision-api-client` | testing a Decision API oracle from the customer side: devnet test credentials (source, keys, payment delegation), the SDK and CLI smoke, MCP from Claude Code, the docs agent test |
-| `decision-api-oracle` | turning on, deploying and verifying the Decision API lane — the shipment-delivery example (SwiftDrop Express) on devnet end to end: publish, identity, Cloudflare, deploy, engine registration (payable at once), operator, verify, emails |
+| `decision-api-client` | calling a Decision API oracle from the customer side: test credentials (source, keys, payment delegation), the SDK and CLI, MCP from Claude Code, paying by card |
+| `decision-api-oracle` | turning on, deploying and verifying the Decision API lane for your own oracle: protocol, identity, Cloudflare, deploy, engine registration (payable at once), operator, verify, emails, payments |
 | `add-openhands-support` | making an oracle hireable from the Openhands app (asks, the Yoma youth world): the OpenHands add-on (`init --openhands`), who pays for decisions, the account to register with, the logo and the picker's card |
+| `update-pricing` | changing what a running oracle charges: the check fee, per-protocol fees, the Decision API price, and refreshing the Agent Card apps show |
+| `operate-oracle` | looking after a deployed oracle: upgrades and migrations, pausing and resuming collections, renewals and key rotation, reviews and recovery, logs, status and alerts, topping up an admin account |
 
 `reference/engine-contract.md` (here, beside the skills) is the decision engine's contract —
-background for all eight, not an interface anyone codes against.
+background for all ten, not an interface anyone codes against.
 `reference/linked-docs.md` is the linked-document rules: where an entity's documents are uploaded,
 each proof's format, and how to read one.

package/skills/create-collection/SKILL.md

@@ -67,8 +67,9 @@ protocol.
    - the oracle address to grant Evaluate; the agent address(es) to grant Submit (comma-separated)
      — `--submit addr1,addr2` is also how to restrict who may claim, e.g. a payouts collection only
      two people may submit to
-   - quota and window in days if the defaults (100, 90) aren't right — state them explicitly rather
-     than silently applying them
+   - the collection's claim quota and window in days if the defaults (100, 90) aren't right —
+     state them explicitly rather than silently applying them. `--quota` is the COLLECTION's quota
+     only; the grants' own quota is fixed (step 5)
 
 2. **Log in once** if there is no session for this network yet:
    `bunx decision-oracle login --network devnet`.
@@ -96,9 +97,14 @@ protocol.
      [--max-custom-amount 0uixo] [--phase collection|fund|grants|all] [--yes]
    ```
 
-   `--eval-denom` must equal the oracle's `EVALUATION_DENOM` — on mainnet the USDC ibc denom or
-   `upay`, never `uixo`. `--eval-amount 0` writes an EMPTY evaluation leg (the chain refuses a zero
-   coin): that is what a collection for a per-review-billed or 0-minimum oracle registers with.
+   `--eval-denom` must equal the oracle's `EVALUATION_DENOM` (read `GET <oracle>/v1/info`
+   `pricing`). A third-party oracle charges IXO (`uixo`, any network) or, on mainnet, USDC.inj
+   (`ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6`). PAY (`upay`) is only
+   for oracles IXO runs: register refuses it on any other (`pay_requires_ixo_managed`).
+   `--eval-amount 0` writes an EMPTY evaluation leg (the chain refuses a zero coin): that is what a
+   collection for a per-review-billed or 0-minimum oracle registers with. `--fund` always sends
+   `uixo`: an admin that pays evaluations in USDC is topped up with
+   `bunx decision-oracle org fund --entity <deed did> --amount <whole USDC> --coin usdc --network mainnet`.
 
    `--max-custom-amount` is the evaluate grant's `MaxCustomAmount`, written explicitly (`0<eval
    denom>` by default). The chain holds EVERY non-empty evaluation amount to it (its denom must be
@@ -138,6 +144,20 @@ protocol.
    it is a bearer credential — and it expires on its own schedule (30 days by default), independent
    of the grants' 365-day expiry.
 
+   **The grants' limits.** Each grant expires after 365 days, and the evaluate grant's
+   `agentQuota` is hard-coded to 100 — `--quota` does not change it. Every `MsgEvaluateClaim` the
+   oracle signs uses one slot, and a claim that goes to a person uses TWO: the oracle signs it
+   FLAGGED while the person decides (it pays nothing), then signs the final verdict. So 100 slots
+   cover 100 decided claims, or 50 reviewed ones. When the grant runs out or expires, the engine
+   answers `NO_EVALUATE_GRANT` and the collection pauses `engine-no-grant`. Re-grant with the grants
+   phase alone (a new grant replaces the old one), then re-register to resume:
+
+   ```bash
+   bunx decision-oracle create-collection --entity <deed did> --protocol <protocol did> \
+     --phase grants --evaluate <oracle address> [--max-custom-amount <amount><denom>] [--network <n>] [--yes]
+   bunx decision-oracle register --collection <id>
+   ```
+
    The bot returns the claim's JSON re-ordered, so its bytes can't be CID-checked: a claim the oracle
    read only from the Matrix claim bot goes to the engine as `claimContent` with no `document`, and
    is decided like any other. For a payout protocol the oracle also looks past the bot to the IPFS
@@ -162,16 +182,18 @@ protocol.
      [--file <fileQuestion>=<path> …] [--yes]
    ```
 
-   (claim-bot media upload → save into the deed's room → `MsgExec(MsgSubmitClaim)`. The
-   passport-delivery example's `protocol/sample-claim.json` is a worked answers file.)
+   (claim-bot media upload → save into the deed's room → `MsgExec(MsgSubmitClaim)`.)
+   `answers.json` is a flat object of the claim form's answers keyed by question name, e.g.
+   `{ "orderId": "ORD-1", "deliveredAt": "2026-11-01T10:00:00Z" }`; each `--file` answers one file
+   question with a local file.
 
 7. **Report the run** — the output contract below.
 
 Payout ASKS (a deed or request with its organisation links and `#payoutTerms`) are posted only
-through OpenHands, not with these commands. A company paying people from its OWN collection runs
-its own self-hosted payouts facilitator instead: enable the collection there
-(`/v1/payouts/collections`) with a `fromDecision` rule on `$.<amount field>`, and name the same
-amount field and currency in the oracle's `payouts` config.
+through OpenHands, not with these commands. A company that pays people from its OWN collection
+names the amount field and currency per protocol in the oracle's `payouts` config; an approved
+claim's receipt then carries the payment to make. Optional — see
+`node_modules/@ixo/decision-oracle/docs/api.md` (`payouts`).
 
 ## Output contract
 
@@ -199,6 +221,8 @@ account, a phase that was dry-run but never confirmed, or a delegation nobody ha
 | Creating the collection before the deed links the protocol | run `create-deed --phase claims`; the picker reads `linkedClaim` → claims-config |
 | Granting Evaluate and expecting the oracle to pull claims | it also needs the claim-bot delegation (step 5) |
 | Leaving the admin account unfunded | every evaluation debits it, rejects included — pass `--fund` |
+| Expecting `--quota` to size the evaluate grant | the grant's `agentQuota` is always 100 (a reviewed claim uses 2); re-run `--phase grants` when it runs out |
+| `--eval-denom upay` for a third-party oracle | register refuses `pay_requires_ixo_managed` — use `uixo`, or USDC.inj on mainnet |
 | Guessing the evaluation amount | it must meet the oracle's `EVALUATION_MIN_AMOUNT` in its `EVALUATION_DENOM`, or register 402s |
 | `--eval-amount 0` expecting a zero coin | it writes an empty evaluation leg — right only for a per-review-billed or 0-minimum oracle |
 | Running with `--yes` first | dry-run, show the plan, then confirm |

package/skills/create-collection/reference/collection.md

@@ -58,7 +58,7 @@ explicitly — `0<--eval-denom>` unless the owner passes `--max-custom-amount <a
 chain checks EVERY non-empty evaluation amount against it (x/claims `IsCoinsInMaxConstraints`; the
 denom must be listed), and the act lane sends an ordinary claim's own coins by default, so claims
 that carry coins need a cap ≥ the largest claim amount in each denom — at `0` their approvals fail
-at MsgExec. It is also the owner's cap on any amount an evaluator sets (company authority D7); the
+at MsgExec. It is also the owner's cap on any amount an evaluator sets; the
 oracle side's own switch is the owner's `operatorAmounts` (`PATCH /v1/collections/:id/settings`),
 honoured only while the owner who set it still owns the collection. All grant messages for one run
 broadcast as ONE tx. No addresses given ⇒

package/skills/create-oracle/SKILL.md

@@ -24,7 +24,8 @@ Write the rules claims are judged by → `create-rubric`. Put a claim form and i
 `publish-protocol`. Open a place for claims to be submitted and hire an oracle on it →
 `create-collection`. Let apps and agents ask the oracle for decisions over HTTP →
 `decision-api-oracle`; test that from the customer's side → `decision-api-client`. Be hireable from
-the Openhands app → `add-openhands-support`.
+the Openhands app → `add-openhands-support`. Change what the oracle charges → `update-pricing`. Keep
+a deployed oracle running (upgrades, pauses, renewals, alerts) → `operate-oracle`.
 
 **Words used throughout:**
 
@@ -42,7 +43,7 @@ the Openhands app → `add-openhands-support`.
 - **did:web** — this oracle's web identity, a name tied to its domain; other services check its
   signatures by fetching `https://<host>/.well-known/did.json`.
 - **Delegation** — a signed permission one party gives another, such as the owner letting the engine
-  bill their subscription, or letting the oracle read their claims.
+  bill their engine credits, or letting the oracle read their claims.
 
 ## When to use
 
@@ -61,12 +62,23 @@ handlers themselves (`write-facts`, handed off to at step 3).
 bunx @ixo/decision-oracle init <dir> [--name <project-name>] [--openhands]
 cd <dir> && bun install
 bun run cf-typegen                       # after ANY wrangler.jsonc binding/var change, too
-wrangler d1 create <project-name>        # paste the id into wrangler.jsonc
-wrangler kv namespace create <project>-cache   # paste the id into wrangler.jsonc (KV names are per account)
 bun run db:migrate                       # the package's own migrations, applied to the local D1
 cp .dev.vars.example .dev.vars           # git-ignored; secrets only
 ```
 
+Local dev needs no Cloudflare resources: the placeholder ids at the top of `wrangler.jsonc` are fine
+for `bun run dev` and the tests. Each env you deploy (`devnet`, `testnet`, `production` in the
+template) needs its own D1 and KV, named exactly as `init` printed them, because that env's block
+already names the database `<project-name>-<env>`:
+
+```bash
+bunx wrangler d1 create <project-name>-<env>                 # → env.<env> d1_databases[0].database_id
+bunx wrangler kv namespace create <project-name>-cache-<env>  # → env.<env> kv_namespaces[0].id
+```
+
+Paste each printed id over its placeholder in that env's block only (KV names are per account, so
+two oracles in one account need two project names).
+
 AI checks run on the Cloudflare AI Gateway by default. `AI_GATEWAY_ID` (in `wrangler.jsonc`, every
 env) is the name of a gateway in the provider's own Cloudflare account: dashboard → AI → AI Gateway
 → create one and use its name. Third-party models through it need AI Gateway credits on that
@@ -154,6 +166,11 @@ signed-in AI app's own auto-approve limits (the hosted MCP's "Don't ask again")
 without a per-claim approval; `false` means every such submit waits for the user's approval of that
 claim. IXO's own oracles turn it on; anyone else decides it explicitly — ask.
 
+Signing uses the collection's evaluate grant. Each `MsgEvaluateClaim` the oracle signs costs gas
+(paid by `ORACLE_ADDRESS`, which `oracle init` keeps topped up) and one slot of the grant's quota. A
+claim that goes to a person costs two: it is first signed FLAGGED (status 5, pays nothing) while the
+person decides, then signed again with the final verdict after the review.
+
 ### 3. The handlers → the `write-facts` skill
 
 ```bash
@@ -187,13 +204,14 @@ table produced plus any validation issue (exit 1 if there are issues); `--previe
 engine's preview lane and prints the decision they would produce — nothing persisted, nothing billed,
 no grant needed. This is the first end-to-end proof.
 
-A flat answers file has no attachments, so any fact that reads one fails closed: in the passport
-example the AI check freezes as an `error` (its guard's path) rather than reaching the stock judge.
-Exercising that lane needs a claim file with an `attachments` entry pointing at a local photo.
+A flat answers file has no attachments, so any fact that reads one fails closed: an AI check over a
+photo freezes as an `error` (its guard's path) rather than reaching the stock judge. Exercising
+that lane needs the envelope, with each file as `{ question, name, mediaType, path }` (`path`
+relative to the claim file) — the `write-facts` skill shows one.
 
 ### 6. The owner's delegation (engine billing)
 
-The engine bills the oracle OWNER's credits, so the owner — whoever holds the IXO subscription —
+The engine bills the oracle OWNER's credits, so the owner — the account that buys those credits —
 mints a delegation to the engine before register will work. **Do this step, don't just quote it.**
 
 ```bash
@@ -214,13 +232,14 @@ printf 'OWNER_DELEGATION_CAR="%s"\n' "$(cat owner-delegation.car)" >> .dev.vars
   before it lapses.
 - Only the human can do the login. Run it in the background so the loopback callback lands, and tell
   them to finish in the browser.
-- **The owner must hold an IXO subscription before `engine register`**, or it answers 402
-  `NO_SUBSCRIPTION`. A subscription created by the subscriptions workflow (not the portal) also
-  needs a Stripe customer: the owner calls the subscriptions API's `POST /api/v1/payments/intent`
-  once (a SetupIntent — nothing is charged).
-- **A 402 at register is the owner's credits, not a bug**: `NO_SUBSCRIPTION` (none at all) or
-  `INSUFFICIENT_CREDITS` (below one decision's price, carrying `manageSubscriptionUrl`). Send the
-  owner to that portal URL to buy credits, then register again — nothing here can fake it.
+- **The owner needs IXO decision-engine credits before `engine register`.** The engine bills
+  every decision to them. The owner buys credits in the Decision Console (devnet:
+  `https://decision-console.devnet.ixo.earth`) › Billing › Credits, signed in as the same account
+  that minted the delegation; the first purchase opens their credits account.
+- **A 402 at register is the owner's credits, not a bug**: `NO_SUBSCRIPTION` (no credits account
+  yet) or `INSUFFICIENT_CREDITS` (below one decision's price; the engine adds a
+  `manageSubscriptionUrl`). `engine register` prints where to buy them (`<CONSOLE_URL>/billing/credits`
+  when `CONSOLE_URL` is set). Send the owner there, then register again — nothing here can fake it.
 
 ### 7. Run it locally — and leave it running
 
@@ -321,16 +340,45 @@ where a live token would have skipped (it mints a new Matrix device — not a ca
 
 ### 9. Deploy it
 
+First write that env's secrets file, `.dev.vars.<env>` (git-ignored like `.dev.vars`). It is what
+`--secrets-file` uploads and what `engine register --env-file` reads below. Never echo a value:
+
+```bash
+{
+  grep -E '^(SERVICE_ED25519_MNEMONIC|ORACLE_SECP_MNEMONIC|ORACLE_MATRIX_ACCESS_TOKEN)=' .dev.vars
+  printf 'OWNER_DELEGATION_CAR="%s"\n' "$(cat owner-delegation.car)"
+  printf 'UNIQUE_HMAC_KEY="%s"\n' "$(openssl rand -base64 32)"
+} > .dev.vars.<env> && chmod 600 .dev.vars.<env>
+```
+
+What a deployed env needs:
+
+| Secret | Needed |
+| --- | --- |
+| `SERVICE_ED25519_MNEMONIC` | always — the did:web key |
+| `ORACLE_SECP_MNEMONIC` | always — signs `MsgEvaluateClaim` and the engine registration |
+| `OWNER_DELEGATION_CAR` | always — register refuses without it. Mint it (step 6) with `--oracle did:web:<this env's host>`: a CAR minted for another host is refused `DELEGATION_NOT_FOR_ORACLE` |
+| `UNIQUE_HMAC_KEY` | when a rubric declares `unique`, and always with `API_LANE` on. One per deployment, for life |
+| `ORACLE_MATRIX_ACCESS_TOKEN` | for review cards. It belongs to one network's homeserver: copy it only into an env on the network step 8 ran on |
+| `OPENROUTER_API_KEY` | only with `AI_PROVIDER=openrouter` (the AI Gateway default needs no secret) |
+| `WEBHOOK_ENCRYPTION_KEY` | only with `API_LANE` on (`openssl rand -base64 32`, for life) |
+| `SENTRY_DSN`, `OPS_ALERT_WEBHOOK_URL` | optional (`operate-oracle`) |
+
+The env file must NOT carry a localhost `ORACLE_HOSTNAME` (that env's host comes from its
+`wrangler.jsonc` vars). **Keep a private backup of every secret outside the repo** (a password
+manager, or a 0600 file only the owner can read): Cloudflare never shows a secret again, and a lost
+mnemonic or `UNIQUE_HMAC_KEY` cannot be recovered — a new one is a new identity or a blind
+duplicate registry.
+
 ```bash
-bun run db:migrate:remote        # BEFORE the first deploy of the default env; for a named env:
-                                 #   bunx wrangler d1 migrations apply DB --remote --env <env>
-bun run deploy:devnet            # or deploy:testnet / deploy:production (`--env <env>`)
-wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN     # the value step 8 wrote into .dev.vars
+bunx wrangler d1 migrations apply DB --remote --env <env>         # BEFORE the first deploy
+bunx wrangler deploy --env <env> --secrets-file .dev.vars.<env>   # code + secrets in one version
+bunx wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN --env <env>   # later, one secret at a time (e.g. after --relogin)
 ```
 
-Before deploying: the D1/KV ids for that env are real, that env's `ORACLE_HOSTNAME` is the host
+Before deploying: the D1/KV ids for that env are real, and that env's `ORACLE_HOSTNAME` is the host
 it will be served from (its Custom Domain in `routes`, or, with no `routes`, its `workers.dev`
-host), and every secret is set with `wrangler secret put`. **Then run step 8 again with
+host). Later deploys are `bun run deploy:<env>` (secrets persist). **Then run step 8 again with
 `--kit-url https://<the deployed host>` and `--yes`**: the `service` step re-points `#eval` at the
 real host and `profile` anchors the `#pro` it had to skip. `fund` may act again too — it is a floor
 check, so a wallet the first run's own `iid`/`key` transactions left below 1 IXO is topped back
@@ -352,7 +400,7 @@ failed check — `identity` means `ORACLE_ENTITY_DID` is missing from that env's
 bunx decision-oracle engine register --env <env> --env-file .dev.vars.<env>
 ```
 
-The chain lane proves its address lazily, on its first `decide`; until then the engine — and the
+The `.dev.vars.<env>` file from the deploy step above supplies the keys. The chain lane proves its address lazily, on its first `decide`; until then the engine — and the
 Decision Console, which lists the engine's `GET /v1/oracles` — does not know this oracle exists.
 `billing: ok` is done; a 402 is the owner's credits (step 6).
 
@@ -394,7 +442,7 @@ the required fee (`pricing.byProtocol` for that collection's protocol, else the
 | Standing approvals | may a signed-in AI app's own auto-approve limits pay without a per-claim approval (hosted MCP) — IXO's own oracles say yes | `policies.allowStandingApprovals` (required) |
 | Custom lanes | per judgment-call name: do you control the endpoint / is a stock AI check the right judge | the `src/facts/` table (`write-facts`) |
 | Identity | a fresh wallet, or an existing mnemonic to derive from | `derive`, `.dev.vars` + `wrangler.jsonc` vars |
-| Owner | who owns this oracle — the AuthHub login whose subscription pays the engine | `login`, `delegation --for engine` |
+| Owner | who owns this oracle — the AuthHub login whose engine credits pay for decisions | `login`, `delegation --for engine` |
 | Funding | nothing to ask — `oracle init` keeps the wallet topped up to 1 IXO for gas | `oracle init` (the `fund` step) |
 | Hosts | the did:web host per env (it IS the identity): a custom domain, or the free `workers.dev` host | `ORACLE_HOSTNAME`, `routes` (none for `workers.dev`) |
 | Contact | the address that gets pause / review notices | `register --contact-email` |
@@ -418,7 +466,7 @@ the required fee (`pricing.byProtocol` for that collection's protocol, else the
 | --- | --- |
 | Reading `rubric.json` to work out what to produce | read the manifest — `protocol review` / `manifest <did>` |
 | A stub that returns a fake `ok` so a run looks green | `fact.error("not implemented: <name>")` |
-| Register answers 402 and the agent retries | it is the owner's credits — send them to the printed portal URL, then re-run |
+| Register answers 402 and the agent retries | it is the owner's credits — send them to the printed credits page, then re-run |
 | `.dev.vars` edited but the old value still in play | a running `wrangler dev` reloads source, not secrets — restart it |
 | `ORACLE_ADDRESS` typed by hand | must match the mnemonic exactly — asserted at first use |
 | Guessing `EVALUATION_MIN_AMOUNT` | ask what the collection's on-chain evaluation payment is (or will be) — set too high and register 402s |
@@ -467,6 +515,6 @@ restart, re-register. Restart both dev servers after any `.dev.vars` edit.
 The review output from step 2, the stock-vs-custom verdict and the handlers written (or stubbed,
 named), the `src/index.ts` config block, the `.dev.vars` / `wrangler.jsonc` lines to set (never
 committed, never printed), the `facts run --preview` decision, and — plainly — what the provider
-still owes: credits on the owner's subscription, the on-chain Evaluate grant (or the step-10
+still owes: the owner's engine credits, the on-chain Evaluate grant (or the step-10
 self-hire), the deployment that replaces `localhost`, the `oracle init` re-run that re-points
 `#eval` at it, and any name still on a stub.

package/skills/decision-api-client/SKILL.md

@@ -19,10 +19,11 @@ A source in billing mode `x402` answers a submit with `402`. The payer pays it w
 customer's **payment delegation**, a UCAN to the facilitator carrying a `billing/pay` cap. The
 price is held when the claim is accepted and paid only on the engine's receipt.
 
-The worked target is IXO's devnet example: SwiftDrop, at `https://shipment-delivery-oracle.devnet.ixo.earth`,
-protocol `did:ixo:entity:c2f5a188d28f3d4bf6351873d3d268ea`, price 60¢. Its `/demo/orders?route=<id>`
-issues a fresh courier route per id, with real order ids and delivery codes. Use a new route per
-test claim, so the duplicate lane never sees a repeat.
+Point it at your own oracle, or at IXO's public demo: SwiftDrop, at
+`https://shipment-delivery-oracle.devnet.ixo.earth`, protocol
+`did:ixo:entity:c2f5a188d28f3d4bf6351873d3d268ea`, price 60¢. Its `/demo/orders?route=<id>` issues
+a fresh courier route per id, with real order ids and delivery codes. Use a new route (or, on your
+own oracle, new answers) per test claim, so the duplicate lane never sees a repeat.
 
 **Core principle: run it, don't recite it.** Every step below is an action you perform. A test
 claim spends real devnet PAY from the session's deed, so say how many claims you will send before
@@ -30,8 +31,9 @@ sending them.
 
 ## When to use
 
-- "Test the SDK / CLI / MCP against devnet", "does the paid flow still work", "mint a test key".
-- Before a client release, or after a facilitator or engine change the payer depends on.
+- "Call this oracle from my app", "test the SDK / CLI / MCP against devnet", "does the paid flow
+  work", "mint a test key".
+- Before you ship an integration, or after the oracle changes its price, protocols or plan.
 - Any symptom in the table at the end.
 
 Not for: standing up or deploying the oracle (`decision-api-oracle`), or the chain lane
@@ -143,25 +145,17 @@ the console) must make the next claim ask again. "Don't ask again" works only on
 `policies.allowStandingApprovals` is `true`; otherwise setting it is refused (`403`, reason
 `standing_approvals_off`) and every claim asks.
 
-### 4. Card scenarios (devnet, Stripe test mode)
-
-Card needs an oracle whose protocol costs **≥ 50¢ per claim** (Stripe's minimum capture; the
-example is 60¢ for this) and whose plan accepts `card`. Which scenario runs is set on the
-**facilitator side**: the payer's default saved card and default way to pay. Saving a test card and
-completing 3-D Secure need the facilitator's Stripe test key, so that half belongs to whoever runs
-the facilitator. This half pays — an SDK submit with `prefer: "card"` (`"upay"` = PAY first; unset =
-the payer's console default), and after a 3-D Secure confirm a resume with the SAME offer and key
-(`{ idempotencyKey: err.idempotencyKey, resumePayment: err.paymentRequired }`):
-
-| Payer's default card (facilitator side) | Submit with | Expect |
-| --- | --- | --- |
-| `pm_card_authenticationRequired` | `prefer: "card"` | `CARD_AUTHENTICATION_REQUIRED` + `confirmUrl`; once confirmed, the resume → paid with the SAME PaymentIntent. Left unconfirmed, the facilitator cancels it ~17 min later, never charged |
-| `pm_card_chargeCustomerFail` | `prefer: "card"` | declined at authorize → paid with PAY for the same 402 |
-| `pm_card_createDispute` | `prefer: "card"`, then again once the dispute is open | paid by card; then `card_blocked` → PAY (no PaymentIntent created); after the dispute is won, card again |
-| `pm_card_visa`, preference `card` | no `prefer` | the SDK reads `/v1/payer/preferences` with the delegation → card |
-
-Every claim's record names the rail: `stripe-manual-capture` / `usd` / cents, or `ixo-pay` / `upay`.
-A run that answers `SPEND_CAP` has used up the delegation's `maxAmount`: mint a new one.
+### 4. Paying by card
+
+Card is offered only when the protocol costs **≥ 50¢ per claim** (Stripe's minimum capture) and the
+oracle's plan accepts `card`. The payer saves a card once in the Decision Console. An SDK submit
+takes `prefer: "card"` (`"upay"` = PAY first; unset = the payer's console default). When the bank
+asks for 3-D Secure the submit throws `CARD_AUTHENTICATION_REQUIRED` with a `confirmUrl`: confirm
+there, then resume with the SAME offer and key
+(`{ idempotencyKey: err.idempotencyKey, resumePayment: err.paymentRequired }`). Left unconfirmed,
+the hold is cancelled and nothing is charged. Every claim's record names the rail:
+`stripe-manual-capture` / `usd` / cents, or `ixo-pay` / `upay`. A run that answers `SPEND_CAP` has
+used up the delegation's `maxAmount`: mint a new one.
 
 ## When something fails