@ixo/decision-oracle 0.2.30 → 0.2.32

package/skills/operate-oracle/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: operate-oracle
+description: Use when a deployed oracle built on @ixo/decision-oracle needs looking after — "upgrade the package", "pause / resume a collection", "why is my collection paused", "renew the delegation", "the Matrix token expired", "rotate a key", "answer a review", "a claim never landed on chain", "erase a claim", "what is my oracle doing", "set up alerts", "top up the admin account", admin-unfunded, engine-credits, engine-no-grant.
+---
+
+# Operating a deployed oracle
+
+## Overview
+
+Day-2 work on an oracle that `create-oracle` already deployed and got hired: upgrades, pauses,
+renewals, reviews, recovery, and seeing what is going on. Each recipe below is short and ordered.
+`<env>` is the wrangler env (`devnet`, `testnet`, `production` in the template), `<host>` that env's
+`ORACLE_HOSTNAME`, `<n>` its network (`devnet` / `testnet` / `mainnet`).
+
+**Core rule: run it, don't recite it.** Anything that signs on chain, deploys, or changes an
+identity is dry-run first (no `--yes`), shown to the owner, and run only on their explicit OK.
+Commands that call the oracle as your login take `--kit https://<host> --network <n>`; without
+`--kit` they call the `ORACLE_HOSTNAME` in `.dev.vars` (usually localhost).
+
+## When to use
+
+- A new `@ixo/decision-oracle` release is out
+- A collection is paused, or should be
+- A delegation, grant or Matrix token ran out; a key must change
+- A review is waiting, a decision never reached the chain, or a claim's data must be erased
+- Setting up logs, status and alerts
+
+Not for: first setup (`create-oracle`), price changes (`update-pricing`), the Decision API's
+sources and keys (`decision-api-oracle`).
+
+## 1. Upgrade the package
+
+```bash
+bun update @ixo/decision-oracle             # within your range; add --latest to cross a 0.x minor
+bunx decision-oracle skills sync            # refresh .claude/skills from the installed package
+bun run db:migrate                          # the new migrations, on the local D1
+bun run check                               # typecheck + lint + your handler tests
+bunx wrangler d1 migrations apply DB --remote --env testnet      # BEFORE that env's deploy
+bunx wrangler deploy --env testnet
+curl -s https://<testnet host>/health/ready                     # {"ok":true}
+```
+
+Then the same three remote lines for `production`. Migrations ship inside
+`node_modules/@ixo/decision-oracle/migrations`; new code against an old schema fails its
+queries, so migrate first, every env. Compare your `wrangler.jsonc` with the new
+`node_modules/@ixo/decision-oracle/templates/project/wrangler.jsonc` for a new binding, var or cron
+trigger, and run `bun run cf-typegen` after adding one. Deploy testnet first and watch it before
+mainnet.
+
+## 2. Pause and resume a collection
+
+**Why it paused.** `GET /v1/admin/status` (section 5) counts paused collections by reason, and the
+owner got a notice (Matrix + email) naming the reason and the fix:
+
+| Reason | What happened | Lifts itself? |
+| --- | --- | --- |
+| `engine-credits` | the oracle owner's engine credits ran out — every collection pauses | yes, once the engine says billing is `ok` (the owner buys credits in the Decision Console) |
+| `admin-unfunded` | the collection's admin account cannot pay an evaluation | yes, once topped up (section 7) — parked decisions are re-delivered |
+| `engine-no-grant` | the Evaluate grant is gone (expired, revoked, or its quota used up) | no — re-grant, then re-register (section 3) |
+| `rubric-unusable` | the anchored rubric no longer binds to its claim form | no — fix the rubric or `#vct`, then resume |
+| `payer-credits` | per-review billing: the paying organisation's credits ran short | yes, once they top up |
+| `oracle-plan` | per-review billing: IXO's plan no longer allows it | yes, once IXO's plan allows it |
+| `payer-delegation` | per-review billing: nobody can pay (no live delegation) | yes, when the organisation signs a new one in the Decision Console |
+
+An operator's own pause has no reason and nothing lifts it but a resume.
+
+**Resume** — as the collection's owner, or whoever registered it: register again. It re-runs the
+four gates (who, hired, protocol, paid), stores a fresh delegation if you pass one, and flips
+`paused` → `active`:
+
+```bash
+bunx decision-oracle register --collection <id> [--delegation delegation.car] --kit https://<host> --network <n>
+```
+
+**Pause** — there is no CLI command. It is `POST /v1/collections/<id>/pause` (and `…/resume`) with a
+UCAN invocation, allowed for the collection's owner, the registrant (while it still holds an
+Evaluate grant) or an `ORACLE_ADMIN_DIDS` operator. One self-signed invocation per call:
+`can: "collections/pause"` (or `collections/resume`), `with: "ixo:eval-oracle"`, audience the
+oracle's did:web, no proofs, a short expiry. With `@ixo/ucan` (`bun add @ixo/ucan` if your project
+cannot import it):
+
+```ts
+// call.ts — bun call.ts POST /v1/collections/<id>/pause collections/pause
+import { createInvocation, serializeInvocation, signerFromMnemonic } from "@ixo/ucan";
+
+const [method = "GET", path = "/v1/admin/status", can = "admin/status"] = process.argv.slice(2);
+const url = process.env.ORACLE_URL as string; // https://<host>
+// The caller's Ed25519 signing key — the one on its did:ixo document. Read from the environment,
+// never pasted into a chat or committed.
+const { signer } = await signerFromMnemonic(
+  process.env.CALLER_ED_MNEMONIC as string,
+  process.env.CALLER_DID as `did:ixo:${string}`,
+);
+const audience = ((await (await fetch(`${url}/.well-known/did.json`)).json()) as { id: string }).id;
+const token = await serializeInvocation(
+  await createInvocation({
+    issuer: signer,
+    audience,
+    capability: { can: can as `${string}/${string}`, with: "ixo:eval-oracle" },
+    proofs: [],
+    expiration: Math.floor(Date.now() / 1000) + 120,
+    facts: [{ nonce: crypto.randomUUID() }],
+  }),
+);
+const res = await fetch(`${url}${path}`, {
+  method,
+  headers: { authorization: `Bearer ${token}`, "x-auth-type": "ucan", "content-type": "application/json" },
+  ...(method === "GET" ? {} : { body: "{}" }),
+});
+console.log(res.status, await res.text());
+```
+
+To stop all chain writes at once without pausing anything, set `"AUTO_SIGN": "false"` in that env's
+`vars` and redeploy: decisions are still recorded, nothing is signed until it is back on.
+
+## 3. Renewals
+
+| What | Lifetime | Renew |
+| --- | --- | --- |
+| Owner → oracle claim-bot delegation (per collection) | 30 days by default | as the collection's owner: `bunx decision-oracle delegation --for bot --audience did:ixo:<ORACLE_ADDRESS> --out delegation.car --network <n>` (dry run, then `--yes`), then `register --collection <id> --delegation delegation.car`. Only Matrix-stored claim bodies need it |
+| `OWNER_DELEGATION_CAR` (engine billing) | 100 years by default (`--days` shortens it) | as the oracle's owner: `delegation --for engine --audience did:web:<engine host> --oracle did:web:<host> --out owner-delegation.car --yes`, then `bunx wrangler secret put OWNER_DELEGATION_CAR --env <env> < owner-delegation.car` and `engine register --env <env> --env-file .dev.vars.<env>` (update that file too) |
+| Evaluate grant | 365 days, and an `agentQuota` of 100 `MsgEvaluateClaim`s (a reviewed claim uses 2) | the collection's owner: `create-collection --entity <deed> --protocol <did> --phase grants --evaluate <ORACLE_ADDRESS>` (dry run, then `--yes`), then `register --collection <id>` to lift `engine-no-grant` |
+| `ORACLE_MATRIX_ACCESS_TOKEN` | until the homeserver drops it | `bunx decision-oracle oracle init --protocol <did> --kit-url https://<host> --relogin --network <n>` (dry run, then `--yes`; it mints a new Matrix device and writes the token into `.dev.vars`), then `bunx wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN --env <env>` |
+| Oracle wallet gas | `oracle init` tops it to 1 IXO | `oracle init … --only fund` (dry run, then `--yes`) |
+
+**Key rotation is an identity change — warn the owner before doing it.** A new
+`ORACLE_SECP_MNEMONIC` is a new `ORACLE_ADDRESS` and `ORACLE_DID`: every collection must grant the
+new address, re-mint its claim-bot delegation for the new DID and re-register, the engine must be
+re-bound (`engine register --yes` prints old → new), and `oracle init` must run again for the new
+address (wallet, IID, key, Matrix account, `#orz`). A new `SERVICE_ED25519_MNEMONIC` changes the
+did:web key: re-run `oracle init` so the `key` step puts the new key on the IID. A new host is a new did:web: re-mint
+`OWNER_DELEGATION_CAR` for it and re-run `oracle init` with the new `--kit-url`. Never rotate
+`UNIQUE_HMAC_KEY` or `WEBHOOK_ENCRYPTION_KEY`. Update your private backup of the secrets after any
+change.
+
+## 4. Day-to-day operations
+
+**Reviews.** A `review` verdict waits for a person the collection's company named (a current
+controller of the collection's entity grants a reviewer `claims/review` for at most 30 days). The
+oracle posts a card in the collection's Matrix review room and emails the registered contact; the
+reviewer answers from that card or the Portal's claim page, and on the Decision API lane from the
+Decision Console. You — the oracle's owner and operators — cannot answer: the engine refuses your
+identities. `GET /v1/reviews/<claimId>` shows what is pending.
+
+**CLI operator commands** (signed as your login; `--kit https://<host> --network <n>`):
+
+| Command | Who | What |
+| --- | --- | --- |
+| `redeliver <claimId> [--yes]` | `ORACLE_ADMIN_DIDS` | a decided claim parked `blocked` because its facts could not be rebuilt: rebuilds them and signs its evaluation on chain |
+| `reviewer-note <claimId>` | `ORACLE_ADMIN_DIDS` | (re)makes a held claim's reviewer note — one more AI call |
+| `relink [--collection <id>]…` | `ORACLE_ADMIN_DIDS` | links watched collections to their company's Decision API sources, as register does |
+| `erase (<claimId>… \| --collection <id>) [--yes]` | the collection's current chain owner | erases claims' transcripts and registry text; the decision, receipt and digests stay. The oracle never erases on its own |
+| `scan --collection <id>` | anyone who may read the collection (its owner, the registrant, an Evaluate-grant holder) | finds new claims now instead of at the next tick |
+
+**A decision that never reached the chain.** Read `chainStatus` / `chainError` on
+`GET /v1/claims/<claimId>` (a UCAN `claims/read`, same snippet). `blocked` with no grant ⇒ re-grant;
+an unfunded admin ⇒ section 7; `held` ⇒ your own `policies.act` hook parked it; `flagged` ⇒ waiting
+for a review; facts not rebuilt ⇒ `redeliver`.
+
+**An errored ingest.** In the Cloudflare dashboard (Workers → Workflows → the claim-ingest
+workflow) rerun the errored instance; the ledger converges.
+
+## 5. See what is happening
+
+```bash
+bunx wrangler tail --env <env>                 # live logs; add --format pretty
+curl -s https://<host>/health/ready            # {"ok":true} or 503 {"ok":false}
+```
+
+- **`GET /v1/admin/status`** — which readiness check failed (and the command to fix `identity` /
+  `owner-delegation`), pending reviews, paused collections by reason, and the engine's billing
+  status. Only DIDs in `ORACLE_ADMIN_DIDS` (operators, `did:ixo`) or `STATUS_READER_DIDS`
+  (read-only monitors, any DID method) may call it; with both unset it is `403` for everyone. Call
+  it with the snippet in section 2 (its defaults are this route).
+- **Workers Logs** — every log line and metric, in the Cloudflare dashboard (Observability).
+- **Sentry** — `bunx wrangler secret put SENTRY_DSN --env <env>`. Each condition that needs a
+  person (a pause, a dead webhook, a lost settlement, a failing cron job) becomes one issue tagged
+  `alert`; the cron triggers check in as monitors. Tune with the `SENTRY_TRACES_SAMPLE_RATE` and
+  `SENTRY_ENVIRONMENT` vars.
+- **Slack alerts** — `bunx wrangler secret put OPS_ALERT_WEBHOOK_URL --env <env>` (a Slack-compatible
+  incoming webhook): one message per condition per 30 minutes.
+- **Uptime** — point a monitor at `GET /health/ready` every minute, not `/health`.
+
+`node_modules/@ixo/decision-oracle/docs/guide.md` §12 has the full alert list and a ten-minute
+Sentry setup.
+
+## 6. Notices
+
+Pause, resume and review notices go to Matrix (needs `ORACLE_MATRIX_ACCESS_TOKEN`) and email (needs
+`EMAIL_FROM_ADDRESS` on a domain onboarded to Cloudflare Email Service). Either unset is a logged
+skip, never a blocked claim. The email goes to the contact given at register
+(`register --contact-email <addr>` changes it).
+
+## 7. Top up a collection's admin account
+
+The collection's admin account (the deed's) pays every evaluation, rejects included, plus the
+verdict's own payment. When it cannot, the decision is parked `blocked` and the collection pauses
+`admin-unfunded`; the owner's notice names the account and the amount needed. Check and top up:
+
+```bash
+bunx decision-oracle org balance --entity <deed did> --network <n>
+bunx decision-oracle create-collection --entity <deed did> --protocol <protocol did> \
+  --phase fund --fund <amount in uixo base units> --network <n>             # dry run, then --yes
+```
+
+`--fund` sends `uixo` from your login's wallet. For USDC on mainnet:
+`bunx decision-oracle org fund --entity <deed did> --amount <whole USDC> --coin usdc --network mainnet`.
+Within a minute the oracle sees the balance, resumes the collection and re-delivers the parked
+decisions — nothing to re-run.
+
+## Troubleshooting
+
+| Symptom | Cause → fix |
+| --- | --- |
+| `no such column` / `no such table` errors after an upgrade | the remote D1 is missing the new migrations — `bunx wrangler d1 migrations apply DB --remote --env <env>` |
+| `/health/ready` 503 | `GET /v1/admin/status` names the check; `identity` ⇒ `ORACLE_ENTITY_DID` missing from that env's `vars` |
+| Collection paused `engine-credits` | the owner buys engine credits in the Decision Console (Billing › Credits); it resumes by itself |
+| Collection paused `engine-no-grant`, engine says `NO_EVALUATE_GRANT` | the grant expired or its 100 slots are used — re-grant (`--phase grants`), then `register` |
+| Collection paused `admin-unfunded`, `payment withdrawal failed` | section 7 |
+| Collection paused `rubric-unusable` | `bunx decision-oracle protocol review <did>` prints the issues; fix the anchored rubric or form, then resume |
+| Matrix-stored claims fail to pull after a month | the claim-bot delegation expired — re-mint `--for bot` and `register --delegation` |
+| Review cards stopped appearing | `ORACLE_MATRIX_ACCESS_TOKEN` was dropped — `oracle init --relogin`, then `wrangler secret put` |
+| `MsgEvaluateClaim` fails `insufficient funds` | the oracle's own wallet is out of gas — `oracle init … --only fund --yes` |
+| `chainStatus: flagged` for days | a person has not answered the review — nudge the company's reviewers |
+| `register` / `redeliver` 401 | `--kit` names a different host than the did:web, or the call went to localhost — pass `--kit https://<host>` |
+| `redeliver` / `relink` / `reviewer-note` 403 | your login's DID is not in that env's `ORACLE_ADMIN_DIDS` |
+| `erase` 403 | only the collection's current chain owner may erase |
+| `.dev.vars` edited but nothing changed | a running `wrangler dev` reloads source, not secrets — restart it; deployed secrets change only with `wrangler secret put` |
+
+## Output contract
+
+Say plainly: what was run per env (versions, migrations, deploys), the `/health/ready` answer, each
+collection's status and reason before and after, what was renewed and when it next expires, any
+transaction hashes, and every step still waiting on the owner.

package/skills/publish-protocol/SKILL.md

@@ -38,8 +38,9 @@ There are two jobs here, and picking the wrong one fails on chain:
   `--yes` after they explicitly say to proceed. These commands spend real funds (gas).
 - **Signing is an AuthHub session, not a mnemonic.** `bunx decision-oracle login --network <n>` once —
   it opens the login URL, waits for the callback, and saves a session under the user's home
-  directory. Every command after that reads it automatically. The session is also the Matrix
-  identity the `resources`/`room` phases use. Never ask anyone to paste a mnemonic or a session file
+  directory. Every command after that reads it automatically. Uploads (the form, the rubric, the
+  profile) go to the IXO Vault, else the IXO IPFS gateway; only the `room` phase uses Matrix, as the
+  session's own Matrix user. Never ask anyone to paste a mnemonic or a session file
   into a message.
 
 ## When to use

package/skills/reference/engine-contract.md

@@ -78,14 +78,14 @@ entries are exactly what a handler returns, after the runner normalized it.
 | 400 `INVALID_ADDRESS_PROOF` | register proof bad | non-retryable; `ORACLE_SECP_MNEMONIC` ≠ `ORACLE_ADDRESS` — a config bug |
 | 403 `NO_EVALUATE_GRANT` | not hired for this collection | retry once (a grant may have just landed), then pause the collection |
 | 402 `INSUFFICIENT_CREDITS` | the OWNER's credits are exhausted | pause every watched collection, log `details.manageSubscriptionUrl`; the cron resumes when `/me` says ok |
-| 402 `NO_SUBSCRIPTION` (register) | the delegated owner has no subscription | non-retryable; the owner subscribes in the portal, then register again. A subscription made 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, no charge) |
+| 402 `NO_SUBSCRIPTION` (register) | the delegated owner has no IXO credits account yet | non-retryable; the owner buys credits in the Decision Console (Billing › Credits), signed in as the account that minted `OWNER_DELEGATION_CAR` — the first purchase opens the account — then registers again |
 | 403 `DELEGATION_NOT_FOR_ORACLE` (register) | the CAR's `billing/pay` names a different oracle | non-retryable; re-mint with `--oracle did:web:<this host>` |
 | 400 `BAD_REQUEST` (register, naming `ownerDelegation`) | the CAR is malformed, mis-addressed or expired | non-retryable; re-mint, then register again |
 | 409 `RUBRIC_PIN_MISMATCH` | our pin ≠ the chain's `#rub` proof | invalidate the cached manifest, re-read, rebuild, retry once |
 | 409 `STALE_REVIEW` | the review answered against a stale digest | refetch the decision, ask the reviewer again |
 | 409 `CONTENT_MISMATCH` | `claimContent` doesn't match the claim (`details.reason` names the check) | non-retryable. Decide: a `decisions` row `status: content_mismatch`, `chainStatus: skipped`, the ingest fails and alerts. Fold: `foldError` |
 | 413 `PAYLOAD_TOO_LARGE` | the body (6 MiB) or the decoded `document` (2 MiB) is over the cap | non-retryable. Decide: a `decisions` row `status: payload_too_large`, `chainStatus: skipped`, the ingest fails and alerts. Fold: `foldError` |
-| 400 `REVIEWER_GRANT_INVALID` | the fold's `reviewerGrant` is absent (the decision has a company), malformed, mis-signed, expired or mis-scoped | non-retryable; `foldError` — the reviewer answers again with a valid grant (the chain reviewer-grant routes land with CA-M5a) |
+| 400 `REVIEWER_GRANT_INVALID` | the fold's `reviewerGrant` is absent (the decision has a company), malformed, mis-signed, expired or mis-scoped | non-retryable; `foldError` — the reviewer reads their grant from `GET /v1/collections/:id/reviewers` and answers again |
 | 403 `REVIEWER_NOT_AUTHORIZED` | the grant's root is not a current controller, or an oracle/evaluator is in the chain | non-retryable; `foldError` — ask a company reviewer |
 | 400 `VALIDATION` | the facts' shape is wrong | non-retryable; a producer bug — fails loudly |
 | 429 `RATE_LIMITED` | the engine's per-IP limiter | retryable; the step backs off (`Retry-After` honoured) |
@@ -120,8 +120,15 @@ pay the evaluation leg) is package-side only — the engine never sees it.
 `decision.status` is one of `decided` / `pending_review` / `unusable`. `receipt` is null ONLY for
 `pending_review` (it is minted after the fold); `decided` and `unusable` both carry one — an
 `unusable` receipt proves the engine refused and why, in codes. The package stores both `cid` and
-`jws` on the decision row, signs `MsgEvaluateClaim` only for `decided`, and puts the receipt CID in
-`verification_proof`. Receipts resolve publicly at the engine's `GET /v1/receipts/:cid`.
+`jws` on the decision row and, for a `decided` verdict, signs `MsgEvaluateClaim` with the receipt
+CID as `verification_proof`. Receipts resolve publicly at the engine's `GET /v1/receipts/:cid`.
+
+Since 0.2.31 a `pending_review` claim is signed too (when signing is on), so the chain shows that a
+person is deciding: `MsgEvaluateClaim` with status FLAGGED (EvaluationStatus `5`), no amount, and
+`verification_proof` = the decision's `resultDigest` (there is no receipt before the fold). The
+decision row's `chainStatus` becomes `flagged`. FLAGGED pays nothing and is not final: the fold's
+verdict is signed over it later, with the fold's receipt CID. Each `MsgEvaluateClaim` uses one slot
+of the evaluate grant's `agentQuota`, so a reviewed claim uses TWO.
 
 ## Human review
 
@@ -152,10 +159,6 @@ names no URL and any 408/429; retryable). Replacing a stored answer therefore ta
 signature. A fold's receipt names the attestation in `evidence` by CID, and the fold's Matrix card
 edit says "Signed by \<did\>".
 
-**Deploy order:** portal first (an older package's review body schema is not strict, so the extra
-field is harmless), then engine and package TOGETHER — both require it, and the engine's fold body
-schema is strict, so forwarding `attestation` to an older engine 400s every fold into `foldError`.
-
 ## Dev lane
 
 `POST /v1/decisions/preview` — the same request, with `rubric` allowed as `{ doc }` and

package/skills/update-pricing/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: update-pricing
+description: Use when a running oracle built on @ixo/decision-oracle should charge a different price, become free, or charge per protocol — "make my checker cost $1", "make checks free", "change the evaluation fee", "change the Decision API price", "the app still shows the old price", a hire or register refused 402.
+---
+
+# Changing an oracle's price
+
+## Overview
+
+An oracle has up to three prices. Each lives in ONE place, and each needs a redeploy (and, for
+what a card shows, a card refresh) to change:
+
+| Price | What it is | Where it is set | Who pays |
+| --- | --- | --- | --- |
+| **Check fee** (`pricing.evaluation`) | the minimum on-chain evaluation payment a collection must carry; checked when a collection is hired or registered | `src/index.ts` `defineOracle({ pricing: { evaluation } })`, replaced per env by the `EVALUATION_DENOM` + `EVALUATION_MIN_AMOUNT` vars (REQUIRED on mainnet) | the collection (the ask's escrow), paid by the chain on every evaluation |
+| **Per-protocol fee** (`pricing.byProtocol`) | a different check fee for named protocols (incl. `"0"`) | `defineOracle({ pricing: { byProtocol: { "<protocol did>": { denom, minAmount } } } })` | same |
+| **Decision API price** (`pricing.api`) | the price per decision on the HTTP lane (`/v1/api`), micro-USD | `defineOracle({ pricing: { api: { amountMicroUsd, byProtocol? } } })`, or the `API_PRICE_USD_CENTS` var when `pricing.api` is absent | the API caller (x402), held on accept, paid on the receipt |
+
+Separate from all three: the **engine's per-decision fee** is billed to the account that registered
+the oracle (`decision-oracle engine register`). You don't set it here; it's your plan with the
+decision engine.
+
+**Core rule: every step is an action you perform, in order. The price change is a deploy, and the
+card refresh signs on chain — dry run first, show it, and run with `--yes` only on the owner's OK.**
+
+## When to use
+
+- The owner wants a new check fee, a free oracle, or a different fee for one protocol.
+- The Decision API price changes.
+- An app (e.g. the Openhands checker picker) still shows the old price.
+- Hires or registers are refused `402 evaluation_underpaid`.
+
+## The run — in order
+
+Work from the oracle project's directory.
+
+### 1. Read what is live now
+
+```bash
+curl -s https://<host>/v1/info | jq '{pricing, supportedProtocols, openhands}'
+```
+
+`pricing.evaluation` is what the hire/register gate demands today; `pricing.api` is the API price.
+
+### 2. Pick the coin and the amount
+
+Amounts are **integer base units** (6 decimals: `1000000` = 1 coin). The denom is matched EXACTLY.
+
+- **Third-party oracle:** IXO (`uixo`) anywhere, or on mainnet USDC — USDC.inj,
+  `ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6`. **Never PAY (`upay`)**:
+  register refuses it on an oracle IXO does not run (`pay_requires_ixo_managed`).
+- **IXO-managed oracle:** PAY (`upay`, 1 PAY = $1) is allowed.
+- **Free:** `minAmount: "0"` — any evaluation leg, or none, is accepted. Bound your engine spend
+  with an `openhands.admit` hook (an allow-list, a daily budget) if anyone can hire you.
+- Price it so your 80% share covers the engine's per-decision fee: the chain pays each evaluation
+  payment 80% to the oracle, 10% to the network and 10% to the relayer node (chain parameters).
+
+### 3. Edit — both places
+
+1. `src/index.ts`: `pricing.evaluation` (devnet/testnet use it as written), plus `byProtocol` /
+   `api` if those change.
+2. `wrangler.jsonc`: in EVERY env that sets them, `EVALUATION_DENOM` and `EVALUATION_MIN_AMOUNT`
+   (both or neither). Mainnet MUST set both — the worker refuses to start without them — and they
+   win over `src/index.ts` there. Named envs don't inherit vars: edit each one.
+3. Update anything in your README / protocol docs that quotes the old price.
+
+Then `bun run check`.
+
+### 4. Deploy, per env
+
+```bash
+bunx wrangler deploy --env <env>          # testnet first, then production
+curl -s https://<host>/v1/info | jq .pricing
+```
+
+`/v1/info` must show the new `pricing` before you go on. No migration is needed for a price change.
+
+### 5. Refresh the Agent Card (what apps show)
+
+The card's price is what portals and the Openhands picker display. It does NOT update by itself.
+
+```bash
+bunx decision-oracle oracle init --protocol <your protocol did> --kit-url https://<host> \
+  --logo <your CURRENT logo url> [--openhands] --network <net>        # dry run: only `acard  do`
+# owner's OK, then the same line with --yes
+```
+
+- Pass your **current** logo URL (read it from your entity's `#pro`), or the run may replace it.
+- The Openhands card's price is `pricing.api` if set, else `--price-pay <n>`, else the check fee when
+  it is in `upay`. `--price-pay` must be positive; for a free check in PAY just drop the flag.
+- The dry run should show only `acard  do  replace (drifted …)`; everything else `skip`.
+
+Verify: read the card back (`#acard` on your oracle entity) and check `price`.
+
+### 6. Tell the apps
+
+Apps that escrow your fee read `/v1/info` `pricing.evaluation` and your card. If an app hard-codes a
+price for your oracle, tell its team the new `{denom, minAmount}`: an ask escrowing less is refused
+402 at hire and its claims are never judged.
+
+## What changes for collections already hired
+
+- The gate runs when a collection is hired/registered, not afterwards. A collection already watched
+  keeps working at whatever evaluation leg it carries, and the chain pays that leg.
+- New hires must meet the new minimum.
+- A collection whose admin account cannot cover the leg on an evaluation is parked
+  `admin-unfunded` until it is topped up (the owner is told the amount).
+
+## Where the fee lands
+
+On every final `MsgEvaluateClaim` (approve AND reject) the chain pays the collection's evaluation
+leg to the evaluating agent — your oracle's `ORACLE_ADDRESS` — less the network and relayer shares.
+A claim marked FLAGGED while a person reviews pays nothing until its final verdict.
+
+## Troubleshooting
+
+| Symptom | Cause → fix |
+| --- | --- |
+| Worker fails to start on mainnet | `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` missing or only one set → set both |
+| `/v1/info` shows the old price after deploy | mainnet: the env vars win over `src/index.ts` → edit the env's vars |
+| Hire/register `402 evaluation_underpaid` | the collection's evaluation leg is below the minimum or in another denom → the app must escrow your coin and amount |
+| Register refuses `pay_requires_ixo_managed` | PAY on a third-party oracle → use `uixo` or USDC.inj |
+| App shows the old price | card not refreshed (step 5) or the app hard-codes it (step 6) |
+| `--price-pay must be a positive PAY amount` | free check: drop `--price-pay` |
+
+## Output contract
+
+Say plainly: the old and new `pricing` per env (from `/v1/info`), the deployed version per env, the
+card refresh tx (or why it was skipped), and which apps were told.

package/skills/write-facts/SKILL.md

@@ -148,7 +148,7 @@ failure it is most likely to meet (an unmatched URL in `fakeTools` is a network
 ### 5. Run them against a real claim
 
 ```bash
-bunx decision-oracle facts run --protocol <protocol did> --claim protocol/sample-claim.json \
+bunx decision-oracle facts run --protocol <protocol did> --claim claim.json \
   [--collection <id>] [--preview] [--facts src/facts/index.ts] [--network devnet] [--json]
 ```
 
@@ -156,12 +156,22 @@ Pulls the live manifest, runs your table over that claim, and prints the facts p
 issue (exit 1 if there are issues). `--preview` sends them to the engine's preview lane and prints
 the decision they would produce — nothing persisted, nothing billed, no grant needed.
 
-`--claim` takes either a flat answers object (the same file `submit-claim --answers` posts — the
-passport example's `protocol/sample-claim.json` is one) or the `{ answers, attachments?: [...] }`
-envelope. A flat file has no attachments, so a handler that reads one fails closed: run the passport
-example against its sample claim and the AI fact comes back `error` (the guard's path), not a stock
-verdict. To exercise a lane that needs files, hand `--claim` an envelope whose `attachments` entry
-points at a local photo.
+`--claim` takes either a flat answers object (the claim form's answers, keyed by question name —
+the same file `submit-claim --answers` posts) or an envelope when a handler needs files:
+
+```json
+{
+  "answers": { "orderId": "ORD-1", "deliveredAt": "2026-11-01T10:00:00Z" },
+  "attachments": [
+    { "question": "deliveryPhoto", "name": "door.jpg", "mediaType": "image/jpeg", "path": "./door.jpg" }
+  ]
+}
+```
+
+`question` is the form question the file answers (what `tools.attachments.on()` filters by) and
+`path` a local file, relative to the claim file. A flat file has no attachments, so a handler that reads one fails closed: an AI
+check over a photo comes back `error` (its guard's path), not a stock verdict. To exercise a lane
+that needs files, use the envelope.
 
 ## The rules a handler must never break
 
@@ -175,10 +185,12 @@ points at a local photo.
   manifest is the only work order, and the engine is the only judge.
 - **Read the agreement last.** `tools.agreement()` right before returning the fact it feeds — the
   engine records the snapshot current at decision time on its receipt.
-- **Read the chain through `tools.chain`, never by hand.** `linkedResources(entityDid)` for what an
-  entity anchors (and each resource's `proof`), `messages(filter)` for what an account did on chain
-  and when, `query()` for chain RPC. An empty answer is a FACT ("nothing anchored", "no such
-  message"); an unreachable Blocksync throws, and the step retries.
+- **Read the chain through `tools.chain`, never by hand.** It has three reads, all read-only:
+  `linkedResources(entityDid)` for what an entity anchors (and each resource's `proof`),
+  `claimIntent({ agentAddress, collectionId, before, after? })` for the newest `MsgClaimIntent` that
+  agent filed on the collection (or `null`), and `query()` for the chain RPC query client (balances,
+  grants, module state). There is no general message-history read. An empty answer is a FACT
+  ("nothing anchored", "no intent filed"); an unreachable Blocksync throws, and the step retries.
 - **One clock, one fan-out.** Use `ctx.now`, never `Date.now()`. Don't spawn your own concurrency:
   the runner already caps ext+ai at 4 in flight and caches every answer so a step retry never
   re-buys it.

package/skills/write-facts/reference/facts-api.md

@@ -1,7 +1,7 @@
 # The facts API — cheat sheet
 
-Full reference: `node_modules/@ixo/decision-oracle/docs/api.md` (or `packages/eval-oracle/docs/api.md`
-in this repo) — every export, every default, every cap. This page is the working subset.
+Full reference: `node_modules/@ixo/decision-oracle/docs/api.md` — every export, every default,
+every cap. This page is the working subset.
 
 Everything a handler is handed, everything it may hand back, and the rules the runner enforces
 around it. Import surface: `@ixo/decision-oracle/facts` (node-safe) and `@ixo/decision-oracle/testing`

package/templates/project/CLAUDE.md

@@ -26,9 +26,10 @@ asks for, sends them to the IXO decision engine, and signs the verdict on chain.
 
 `.claude/skills/` holds the skills shipped with the package — `create-oracle` (the build runbook),
 `write-facts` (one fact handler at a time), `create-rubric`, `publish-protocol`,
-`create-collection`, `decision-api-oracle` (the Decision API lane: deploy, register, verify). Use
-them for those workflows rather than improvising, and refresh them after upgrading:
-`bunx decision-oracle skills sync`.
+`create-collection`, `decision-api-oracle` (the Decision API lane: deploy, register, verify),
+`decision-api-client` (calling it as a customer), `add-openhands-support`, `update-pricing` (changing
+the price) and `operate-oracle` (upgrades, pauses, renewals, alerts). Use them for those workflows
+rather than improvising, and refresh them after upgrading: `bunx decision-oracle skills sync`.
 
 ## The two rules