@ixo/decision-oracle 0.2.30 → 0.2.32

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

@@ -1,9 +1,9 @@
 ---
 name: decision-api-oracle
-description: Use when setting up, deploying or testing a Decision API oracle (API_LANE on) — the shipment-delivery example on devnet (shipment-delivery-oracle.devnet.ixo.earth), or a provider turning the lane on for their own oracle — or when debugging one - a 401 on the console, PROTOCOL_NOT_ALLOWED, 503 payments-disabled, plan_inactive, an oracle the Decision Console does not list, member or review emails that never arrive.
+description: Use when setting up, deploying or testing a Decision API oracle (API_LANE on) — a provider turning the lane on for their own oracle, from protocol to a verified paid claim — or when debugging one - a 401 on the console, PROTOCOL_NOT_ALLOWED, 503 payments-disabled, plan_inactive, an oracle the Decision Console does not list, member or review emails that never arrive.
 ---
 
-# A Decision API oracle, from nothing to a passing smoke
+# A Decision API oracle, from nothing to a verified claim
 
 ## Overview
 
@@ -14,73 +14,77 @@ plan from the moment it registers, unless IXO sets another);
 the payments facilitator settles each claim the ways that plan allows — by card and/or USDC on Base
 for a third-party oracle, PAY only for IXO-run ones — into the oracle's own earnings addresses
 (`EARNINGS_ADDRESS` / `EARNINGS_BASE_WALLET`); the Decision Console
-(`decision-console.devnet.ixo.earth`) is the UI over all of it.
+(`decision-console.devnet.ixo.earth` on devnet) is the UI over all of it.
 
-The worked run is IXO's own example deployment, **SwiftDrop Express** (`shipment-delivery`) — a
-fictional last-mile courier with cash on delivery, IXO's devnet deployment at
-`shipment-delivery-oracle.devnet.ixo.earth`. Its README has the outcome table, the demo orders API
-and the courier demo page (`/courier`). A provider's own project (from
-`decision-oracle init`) follows the same steps with their names. Where the example has a script the
-template does not (`deploy:devnet`, an env-scoped `db:migrate:remote`, `bun run smoke`), the step
-says **example** and gives the template's equivalent — use that in a provider's project.
+The run below is a provider's own project (from `decision-oracle init`), deployed to one wrangler
+env (`devnet`, `testnet` or `production` in the template). `<project-name>` is the name `init` was
+given, `<env>` the wrangler env, `<host>` that env's `ORACLE_HOSTNAME`.
 
 **Core principle: every step is an action you perform, in this order.** Run the commands; don't
 recite them. Steps only a human can do are marked **HUMAN** — say exactly what to do and wait.
 **Anything that signs on chain or changes an identity (publish, `oracle init`, a key the oracle
 already uses) is dry-run first, shown, and run with `--yes` only on the owner's explicit OK.**
 
+**IXO's public demo.** SwiftDrop Express, a fictional courier with cash on delivery, runs this lane
+on devnet at `https://shipment-delivery-oracle.devnet.ixo.earth` (its courier page is `/courier`).
+Use it to see the lane working from the customer's side (`decision-api-client`); build your own
+from the steps below.
+
 ## When to use
 
-- "Set up / deploy / test the Decision API example", "stand up shipment-delivery-oracle on devnet"
-- A provider turning `API_LANE` on for their own oracle
+- "Turn on / deploy / test the Decision API for my oracle"
+- A provider adding `API_LANE` to an oracle that already serves the chain lane
 - Any symptom in the troubleshooting table below
 
 Not for: the chain lane's collections (`create-collection`), authoring a rubric (`create-rubric`),
-writing handlers (`write-facts`).
+writing handlers (`write-facts`), changing the price after launch (`update-pricing`), day-2
+operations (`operate-oracle`).
 
 ## The run — in order
 
-Work from the project directory. `bunx decision-oracle`
-is the package CLI.
+Work from the project directory. `bunx decision-oracle` is the package CLI.
 
 ### 0. Prerequisites
 
 ```bash
-bunx wrangler whoami                        # the Cloudflare account the oracle deploys to
-bunx decision-oracle login --network devnet     # the OWNER's AuthHub session — once
+bunx wrangler whoami                            # the Cloudflare account the oracle deploys to
+bunx decision-oracle login --network devnet     # the OWNER's AuthHub session — once per network
 ```
 
 - `login` opens a browser: run it in the background and tell the human to finish there (**HUMAN**).
   The session is the owner: it publishes the protocol, owns the oracle entity, and is the operator.
   Put the session's OWN DID (`did:ixo:<address>` — `login` prints the address) in
-  `ORACLE_ADMIN_DIDS` in every `vars` block of `wrangler.jsonc`. The example ships IXO's DID there —
-  a copy of it must replace it with the owner's.
-- A custom domain is optional. Without one, delete each env's `routes` entry and set that env's `ORACLE_HOSTNAME` to the Worker's free `<worker name>.<account subdomain>.workers.dev` host (the first deploy prints it). With one, the account must hold the zone of the host, or the Custom Domain cannot attach — if `whoami` shows another account, stop and say so (**HUMAN**). Either way the host IS the did:web: pick it before `oracle init`.
+  `ORACLE_ADMIN_DIDS` in every `vars` block of `wrangler.jsonc`.
+- A custom domain is optional. Without one, delete each env's `routes` entry and set that env's
+  `ORACLE_HOSTNAME` to the Worker's free `<worker name>.<account subdomain>.workers.dev` host (the
+  first deploy prints it). With one, the account must hold the zone of the host, or the Custom
+  Domain cannot attach — if `whoami` shows another account, stop and say so (**HUMAN**). Either way
+  the host IS the did:web: pick it before `oracle init`.
+
+### 1. The protocol
 
-### 1. The protocol (example: publish `protocol/`; a provider: their protocol's DID)
+Use an existing protocol's DID, or publish your own form and rubric (the `create-rubric` and
+`publish-protocol` skills):
 
 ```bash
 bunx decision-oracle rubric validate --rubric protocol/rubric.json --form protocol/form.json
 bunx decision-oracle publish-protocol --rubric protocol/rubric.json --form protocol/form.json --network devnet
 ```
 
-The second line is a dry run: show the plan, get the owner's OK, then re-run it with `--yes`. The
-`publish-protocol` skill has the phases and failure modes. Then put the printed protocol DID in
-`src/protocol.ts` (`SHIPMENT_PROTOCOL_DID = "did:ixo:entity:…"`) and keep whatever
-`publish-protocol` left in `protocol/` — those are the anchored bytes. The rubric's four `ext`
-sources share the endpoint `https://shipment-delivery-oracle.devnet.ixo.earth/demo/orders`: it
-answers once step 5 deploys. Each is called with a UCAN from this oracle's did:web to the
-endpoint's own did:web (`did:web:shipment-delivery-oracle.devnet.ixo.earth`), capability
-`ixo:external-source` — the oracle never signs a capability the rubric names, and never an IXO
-service's (`api.md`, "How an external source is called"). Check the work order:
+The second line is a dry run: show the plan, get the owner's OK, then re-run it with `--yes`. Keep
+whatever `publish-protocol` left in `protocol/` — those are the anchored bytes. Put the protocol DID
+in `supportedProtocols` in `src/index.ts`. Then read the work order:
 
 ```bash
 bunx decision-oracle protocol review <protocol did> --network devnet
 ```
 
-It must list `ext.orderKnown`, `ext.deliveryCodeValid`, `ext.cashReconciled`,
-`ext.dropoffNearAddress` (custom — one group of ours), `ai.photoShowsDelivery`, `unique`,
-`frequency`.
+It lists every `ext` source and `ai` check the oracle must answer, plus any `unique` / `frequency`
+rule. Write a handler for each name that needs one (`write-facts`) and get `bun run check` green.
+An `ext` source is called with a UCAN from this oracle's did:web to the endpoint's own did:web,
+capability `ixo:external-source` — the oracle never signs a capability the rubric names, and never
+an IXO service's (`api.md`, "How an external source is called"). An endpoint you host yourself must
+be live before claims arrive.
 
 ### 2. Identity
 
@@ -88,17 +92,20 @@ Do `create-oracle` step 1 (two `derive --new --write` runs, the first `--as SERV
 the second is `ORACLE_SECP_MNEMONIC`) and step 6 (the owner's engine delegation), with:
 
 - the three public lines (`ORACLE_ADDRESS`, `ORACLE_DID`, `ORACLE_MATRIX_USER_ID`) written into BOTH
-  the top-level and `env.devnet` `vars` of `wrangler.jsonc`;
+  the top-level and `env.<env>` `vars` of `wrangler.jsonc`;
 - the delegation minted for THIS host:
-  `bunx decision-oracle delegation --for engine --audience did:web:decision-engine.devnet.ixo.earth --oracle did:web:shipment-delivery-oracle.devnet.ixo.earth --out owner-delegation.car --yes`.
+  `bunx decision-oracle delegation --for engine --audience did:web:<engine host> --oracle did:web:<host> --out owner-delegation.car --yes`
+  (the engine host is `decision-engine.devnet.ixo.earth`, `decision-engine.testnet.ixo.earth` or
+  `decision-engine.ixo.earth`).
 
 An oracle that already has keys keeps them — replacing a live oracle's key is an identity change:
 ask first. Never print a mnemonic or the CAR.
 
+Turn the lane on in that env's `vars`: `"API_LANE": "true"`.
+
 ### 3. Secrets
 
-Write `.dev.vars.<env>` (git-ignored, like `.dev.vars`; the example's is `.dev.vars.devnet`) —
-never echo a value to the terminal:
+Write `.dev.vars.<env>` (git-ignored, like `.dev.vars`) — never echo a value to the terminal:
 
 ```bash
 {
@@ -106,31 +113,41 @@ never echo a value to the terminal:
   printf 'OWNER_DELEGATION_CAR="%s"\n' "$(cat owner-delegation.car)"
   printf 'WEBHOOK_ENCRYPTION_KEY="%s"\n' "$(openssl rand -base64 32)"
   printf 'UNIQUE_HMAC_KEY="%s"\n' "$(openssl rand -base64 32)"
-} > .dev.vars.<env>
+} > .dev.vars.<env> && chmod 600 .dev.vars.<env>
 ```
 
-The example's AI photo check runs on the Cloudflare AI Gateway (`AI_GATEWAY_ID` in
-`wrangler.jsonc` + the `ai` binding — no secret; the account needs AI Gateway credits). Only with
-`AI_PROVIDER=openrouter`: `OPENROUTER_API_KEY` — ask the owner for the key, **HUMAN**, and append it
-the same way. Optional: `SENTRY_DSN`. `ORACLE_MATRIX_ACCESS_TOKEN` is required but
-comes later — `oracle init` writes it (step 7).
+AI checks run on the Cloudflare AI Gateway by default (`AI_GATEWAY_ID` in `wrangler.jsonc` + the
+`ai` binding — no secret; the account needs AI Gateway credits). Only with `AI_PROVIDER=openrouter`:
+`OPENROUTER_API_KEY` — ask the owner for the key, **HUMAN**, and append it the same way. Optional:
+`SENTRY_DSN`. `ORACLE_MATRIX_ACCESS_TOKEN` is required but comes later — `oracle init` writes it
+(step 7).
 `WEBHOOK_ENCRYPTION_KEY` and `UNIQUE_HMAC_KEY` are for life — generate them ONCE per deployment;
 on an existing deployment, never regenerate (rotating strands every webhook secret / blinds the
-duplicate registry). `.dev.vars` needs its own `WEBHOOK_ENCRYPTION_KEY` for `bun run dev`.
+duplicate registry). **Keep a private backup of this file outside the repo** (a password manager,
+or a 0600 file only the owner can read): Cloudflare never shows a secret again. `.dev.vars` needs
+its own `WEBHOOK_ENCRYPTION_KEY` for `bun run dev`.
 
 ### 4. Cloudflare resources
 
-The example's names (a provider: their own, one set per env; `<env>` is the wrangler env you
-deploy — `devnet` in the example, `testnet` / `production` in the template):
+One set per env, named as `init` printed them (the env's block already names the database and the
+bucket this way):
 
 ```bash
-bunx wrangler d1 create shipment-delivery-oracle-devnet          # → env.<env> d1 database_id
-bunx wrangler kv namespace create <project>-cache-devnet          # → env.<env> kv id
-bunx wrangler r2 bucket create shipment-delivery-oracle-uploads-devnet
+bunx wrangler d1 create <project-name>-<env>                   # → env.<env> d1 database_id
+bunx wrangler kv namespace create <project-name>-cache-<env>    # → env.<env> kv id
+bunx wrangler r2 bucket create <project-name>-uploads-<env>     # optional: file uploads
 ```
 
 Paste each printed id over its placeholder in `env.<env>` (only there — the top level is local
-dev). Then `bun run cf-typegen` and `bun run check`.
+dev). For uploads, uncomment that env's `API_UPLOADS` line in `wrangler.jsonc`:
+
+```jsonc
+"r2_buckets": [{ "binding": "API_UPLOADS", "bucket_name": "<project-name>-uploads-<env>" }],
+```
+
+Without it `PUT /v1/api/uploads` answers 501 and claims can still attach https URLs. If you also
+bind `ANSWERS_ARCHIVE`, both go in the ONE `r2_buckets` array. Then `bun run cf-typegen` and
+`bun run check`.
 
 ### 5. Migrate and deploy
 
@@ -140,11 +157,6 @@ bunx wrangler deploy --env <env> --secrets-file .dev.vars.<env>   # code + secre
 curl -s https://<host>/.well-known/did.json
 ```
 
-**Example:** `bun run db:migrate:remote` and `bun run deploy:devnet -- --secrets-file
-.dev.vars.devnet` are those two lines for `devnet`; also check the demo orders API and the
-courier page answer (`curl -s https://shipment-delivery-oracle.devnet.ixo.earth/demo/orders/ORD-1-C`,
-`/courier`). The template has no env-scoped migrate script — use the `wrangler` line.
-
 Later deploys: `bunx wrangler deploy --env <env>` (secrets persist); one secret: `bunx wrangler
 secret put <NAME> --env <env>`. The did.json `id` must be `did:web:<host>`.
 
@@ -163,29 +175,26 @@ bunx decision-oracle engine register --env <env> --env-file .dev.vars.<env>
 ```
 
 It proves the oracle's address to the engine (ADR-36) with the owner's delegation and prints the
-billing status. A 402 is the owner's credits: send them to the printed URL (**HUMAN**), then re-run.
+billing status. A 402 is the owner's engine credits: the owner buys them in the Decision Console
+(Billing › Credits), signed in as the account that minted the delegation (**HUMAN**), then re-run.
 If the engine already binds this did:web to a DIFFERENT address, it prints old → new and refuses:
 that is an identity change — ask the owner before re-running with `--yes`.
 
 Registering is the whole step for a provider: an oracle with no plan of its own runs at the
 engine's **Standard** plan at once (payable by card and/or USDC on Base, into the oracle's earnings
-addresses; listed in the Decision Console). PAY is for IXO-run oracles only. Nothing to request. Done when the oracle appears in the engine's
-`GET /v1/oracles` (the console's list).
-
-An oracle IXO runs for itself moves to an IXO plan only on IXO's side: ask IXO to move it
-(**HUMAN**), and it is done when IXO confirms the plan.
+addresses; listed in the Decision Console). PAY is for IXO-run oracles only. Nothing to request.
+Done when the oracle appears in the engine's `GET /v1/oracles` (the console's list).
 
 ### 7. On chain — the full identity (mandatory)
 
 Every oracle built with the kit has a full on-chain identity — the entity, its `#pro` profile, its
-`#dmn` domain card and its `#acard` Agent Card (which lists the `decision-api` service at the lane's published
-price) — even when the API lane is all it serves. **Required, not optional:** a deployed oracle
-without `ORACLE_ENTITY_DID` fails `/health/ready` (its `identity` check). In order:
+`#dmn` domain card and its `#acard` Agent Card (which lists the `decision-api` service at the lane's
+published price) — even when the API lane is all it serves. **Required, not optional:** a deployed
+oracle without `ORACLE_ENTITY_DID` fails `/health/ready` (its `identity` check). In order:
 
-1. Run `create-oracle` step 8 — `bunx decision-oracle oracle init --protocol <did> --kit-url https://shipment-delivery-oracle.devnet.ixo.earth --network devnet`
+1. Run `create-oracle` step 8 — `bunx decision-oracle oracle init --protocol <did> --kit-url https://<host> --logo <url|file> --network devnet`
    as a dry run, show the plan, and re-run the identical line with `--yes` only on the owner's OK.
-   `--logo <url>` is optional but recommended (without it the portal and the console show a
-   placeholder) — ask the owner for one.
+   Ask the owner for a logo (without it the portal and the console show a placeholder).
 2. Pin the entity DID it prints as `ORACLE_ENTITY_DID` in `wrangler.jsonc` — the top-level `vars`
    AND every `env.<name>.vars` (named envs don't inherit).
 3. `bunx wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN --env <env>` with the value it wrote into
@@ -198,16 +207,16 @@ The oracle is not done until readiness passes. A 503 there names nothing; the op
 
 ### 8. Operator: a source, its protocol, its billing, a key
 
-The smoke (step 9) does all of this itself; for a real partner. A source belongs to an
-organisation entity (`--entity`): the partner's, or one made with `org create` (`org balance` /
-`org fund` check and top up its admin account):
+A source belongs to an organisation entity (`--entity`): the partner's, or one made with
+`org create` (`org balance` / `org fund` check and top up its admin account):
 
 ```bash
 bunx decision-oracle org create --name "<partner>" --network devnet --yes      # → { entityDid } — once, idempotent by name
-K="--kit https://shipment-delivery-oracle.devnet.ixo.earth --network devnet"
+K="--kit https://<host> --network devnet"
 bunx decision-oracle api source create --name "<partner>" --contact <email> --entity <org did> $K  # as a controller of the org; pending-link; secret shown ONCE
-bunx decision-oracle api admin protocols <sourceId> <protocol did> $K              # dry run → --yes
-bunx decision-oracle api admin billing-mode <sourceId> none $K                     # only for a partner who must not pay; dry run → --yes
+bunx decision-oracle api source link <sourceId> $K                             # dry run → --yes; pending-link → active
+bunx decision-oracle api admin protocols <sourceId> <protocol did> $K          # dry run → --yes
+bunx decision-oracle api admin billing-mode <sourceId> none $K                 # only for a partner who must not pay; dry run → --yes
 bunx decision-oracle api key create --source <sourceId> --scopes claims:write,claims:read,webhooks:manage $K
 bunx decision-oracle api review-billing enable --source <sourceId> $K   # --cap <PAY> (default 1000); "Pay for reviews": as the org's CHAIN OWNER; dry run → --yes
 bunx decision-oracle api review-billing status --source <sourceId> $K
@@ -217,32 +226,36 @@ bunx decision-oracle api review-billing disable --source <sourceId> $K
 `review-billing` exists only while IXO's plan bills the oracle's reviews per review (`/v1/info`
 `reviewBilling.mode: "x402"`; `enable` refuses otherwise), and needs `API_LANE` AND `API_PAYMENTS`
 on, a published `pricing.api` price, and the organisation's collections created with
-`--eval-amount 0` (an empty evaluation leg — `create-collection`). The login must be the organisation's
-owner on chain — the reviews come out of ITS credits — and `--cap` (PAY) is a lifetime total,
-never refunded: raise it by running `enable` again with a higher `--cap`.
+`--eval-amount 0` (an empty evaluation leg — `create-collection`). The login must be the
+organisation's owner on chain — the reviews come out of ITS credits — and `--cap` (PAY) is a
+lifetime total, never refunded: raise it by running `enable` again with a higher `--cap`.
 
 The source is `pending-link` (no keys, no claims) until a controller of the organisation signs its
 `SourceCompanyLink`, PUTs it to the engine and syncs — the Decision Console's "add oracle" does all
-three, and so does `bunx decision-oracle api source link <sourceId> --yes`. The session runs `source create` / `key create` only as a controller; the operator's own
-session should not be one where its oracle's reviews matter (the engine refuses a review chain
-through the oracle's owner).
+three, and so does `api source link <sourceId> --yes`. The session runs `source create` /
+`key create` only as a controller; the operator's own session should not be one where its oracle's
+reviews matter (the engine refuses a review chain through the oracle's owner).
 
 A new source allows exactly the oracle's `supportedProtocols` (empty until step 1's DID is in
-`src/protocol.ts` and deployed) — `admin protocols` REPLACES the list.
-
-### 9. Verify — the smoke (example)
-
-The smoke is the example's (`scripts/smoke.ts`, over its protocol and fixtures); a provider's
-project has none — verify theirs with step 8's key: `PUT /v1/api/uploads`, `POST /v1/api/claims`
-with `Prefer: wait=60`, one claim per outcome their rubric can reach, and the review through the
-console. An upload attachment carries the `cid` its upload returned —
-`attachments[].{ question, uploadId, cid }`; accept refuses one without it or with another upload's.
-For the example:
-
-```bash
-bun run smoke -- --url https://shipment-delivery-oracle.devnet.ixo.earth \
-  [--entity <org did>] [--org-controller <key file|address>] [--reviewer <address>]
-```
+`src/index.ts` and deployed) — `admin protocols` REPLACES the list.
+
+### 9. Verify — one claim per outcome
+
+With step 8's key (`Authorization: Bearer <key>` on `https://<host>/v1/api`), or the
+`@ixo/decision-oracle-client` SDK/CLI (`decision-api-client`):
+
+1. `GET /v1/api/protocols/<protocol did>` — the work order and the price.
+2. `PUT /v1/api/uploads` — a file, if the protocol takes one (needs step 4's bucket). An upload
+   attachment carries the `cid` its upload returned — `attachments[].{ question, uploadId, cid }`;
+   accept refuses one without it or with another upload's. Without uploads, attach
+   `{ question, url }` with an https link.
+3. `POST /v1/api/claims` with `Prefer: wait=60` — one claim per outcome the rubric can reach
+   (approve, reject, review), each with its own answers so the duplicate lane never sees a repeat.
+   Send `submitter` (your stable id for the person) when the rubric has a `frequency` rule.
+4. Answer a `review` claim in the Decision Console as a reviewer (below), and watch it fold to a
+   final decision.
+5. With `API_PAYMENTS` on and a source in billing mode `x402`, one paid claim — the
+   `decision-api-client` skill has the payer side.
 
 Three people, three keys — never the same account twice:
 
@@ -250,37 +263,21 @@ Three people, three keys — never the same account twice:
   `api admin billing-mode` and `api admin protocols`. It must NOT be the organisation's
   controller or the reviewer: the engine refuses any review grant chain through the oracle's
   identities, its owner included.
-- **the organisation's controller** (`--org-controller`, a key file or an account address; pass
-  `--entity` with the organisation it controls — the smoke's defaults are the example's own
-  devnet accounts): a source belongs to an organisation, so the controller creates it (`POST /v1/api/sources { entityDid }` →
-  `pending-link`), signs the `SourceCompanyLink` (kid = the did:key of the Ed25519 key on its IID,
-  canonical payload) and PUTs it to the ENGINE (`PUT /v1/sources/:oracleDid/:sourceId/company`,
-  UCAN `company/link`), syncs (`POST /v1/api/sources/:id/company/sync` → `active`), mints and
-  revokes the keys, and invites the reviewer. Its key needs no chain write: it already controls the
-  entity.
-- **the reviewer** (`--reviewer <address|did>`, a third account that is neither of the two): a
-  MEMBER. The
-  controller invites it by DID with role `reviewer` and PUTs its role grant (≤ 30 days); the member
-  registers a `did:key` reviewer key, grants it `claims/review` on the source and answers through
-  the API with that two-link `reviewerGrant` (controller → member → key).
-
-Every line `PASS`, then `ALL PASS`. It creates a free source (billing `none`), uploads the
-fixtures, decides one stop per row of the example's outcome table (approve prepaid · approve COD ·
-review cash short · review GPS far · partial refused · reject wrong code · reject unknown order ·
-review reused photo, held on `unique:SD-DUP-1` with its `duplicates[]` naming the earlier claim ·
-reject the same order claimed again by its courier (same `submitter`) · review dispatch down), answers the cash review (and the
-claim-level `SD-RT-CHECKS` asked beside it) as a member does in the Decision Console (never an
-oracle operator's account, which the engine refuses in a reviewer grant), waits for the engine's fold (`decided partial`), walks
-the rest of the surface, then revokes its keys and DELETEs its sources as the controller (`--keep`
-keeps both). Each run spends ~13 engine decisions (and one review fold) of the owner's
-credits. Then, on the owner's OK:
-
-- `--frequency` — one courier over the daily limit (26 more decisions);
-- `--paid` — one x402 claim paid from the session's own devnet deed. Needs a **subscription deed**
-  whose admin holds PAY and has granted the payments facilitator's address a `SendAuthorization` —
-  the subscriptions service's devnet purchase / top-up does both (**HUMAN** if absent). Check:
-  `curl "https://devnet.ixo.earth/rest/cosmos/authz/v1beta1/grants?granter=<deed admin>&grantee=<facilitator address>&msg_type_url=/cosmos.bank.v1beta1.MsgSend"`.
-  Spends one decision price of PAY (60¢ in the example).
+- **the organisation's controller**: a source belongs to an organisation, so the controller
+  creates it (`POST /v1/api/sources { entityDid }` → `pending-link`), signs the `SourceCompanyLink`
+  (kid = the did:key of the Ed25519 key on its IID, canonical payload) and PUTs it to the ENGINE
+  (`PUT /v1/sources/:oracleDid/:sourceId/company`, UCAN `company/link`), syncs
+  (`POST /v1/api/sources/:id/company/sync` → `active`), mints and revokes the keys, and invites the
+  reviewer. `api source link` does the link and the sync. Its key needs no chain write: it already
+  controls the entity.
+- **the reviewer** (a third account that is neither of the two): a MEMBER. The controller invites
+  it by DID with role `reviewer` and PUTs its role grant (≤ 30 days); the member registers a
+  `did:key` reviewer key, grants it `claims/review` on the source and answers through the API with
+  that two-link `reviewerGrant` (controller → member → key). The Decision Console does all of this
+  for the member.
+
+Each decision spends one of the owner's engine credits; a review fold is free. Revoke test keys
+afterwards (`api key revoke`).
 
 ### 10. Verify — the six member / review emails
 
@@ -294,27 +291,34 @@ With the owner's email as the test inbox, in the console (**HUMAN** clicks; you
 | 1 | "<inviter> invited you to <source>" | the owner invites a reviewer by email (Members → Invite) |
 | 2 | "<member> accepted your invitation to <source>" | the invitee accepts — to the inviter (a source owner without a member email gets it at the source's contact) |
 | 3 | "Your access to <source> is ready" | the acceptance grants the delegation — to the member |
-| 4 | "Review needed: <protocol> claim for <source>" | a claim goes `pending_review` (example: a COD stop with the cash short, from the courier page's stop 4) — to each member with `claims/review`, an email and `notifyReviews` on |
+| 4 | "Review needed: <protocol> claim for <source>" | a claim goes `pending_review` — to each member with `claims/review`, an email and `notifyReviews` on |
 | 5 | "<n> claims need your review for <source>" | a second review claim inside 15 min is held, then sent as one batch by the minute tick |
 | 6 | "Still waiting" / "Two weeks waiting: …" | reminders at 3 and 14 days for an unanswered claim — confirm it is scheduled, don't wait |
 
-### 11. Payments on (a provider turning it on)
+### 11. Payments on
+
+In the env's vars:
+
+- `API_PAYMENTS: "true"`;
+- `X402_FACILITATOR_URL` — IXO's facilitator for the env's network: devnet
+  `https://facilitator.devnet.ixo.earth`, testnet `https://facilitator.testnet.ixo.earth`, mainnet
+  `https://facilitator.ixo.earth`;
+- `X402_NETWORK` — `cosmos:devnet-1` / `cosmos:pandora-8` / `cosmos:ixo-5`;
+- the payees: `EARNINGS_ADDRESS` (your own `ixo1…`, each offer's `payTo` for PAY and USDC on IXO;
+  unset ⇒ no PAY) and `EARNINGS_BASE_WALLET` (your `0x…`, for USDC on Base).
 
-`API_PAYMENTS: "true"`, `X402_FACILITATOR_URL`, `X402_NETWORK` (`cosmos:devnet-1` / `cosmos:pandora-8`
-/ `cosmos:ixo-5`) and the payees — `EARNINGS_ADDRESS` (your own `ixo1…`, each offer's `payTo` for
-PAY and USDC on IXO; unset ⇒ no PAY) and `EARNINGS_BASE_WALLET` (your `0x…`, for USDC on Base) —
-in the env's vars, a price (`pricing.api` in `defineOracle`, whole cents), and the
-oracle registered with the engine (step 6) — the facilitator reads the oracle's terms from its plan
-(Standard unless IXO set another). `API_PAYMENTS:
-"false"` is the kill switch: new x402 submits answer 503 `payments-disabled`, `none` sources keep
-deciding. The example's devnet env ships with payments on.
+Plus a price (below) and the oracle registered with the engine (step 6) — the facilitator reads the
+oracle's terms from its plan (Standard unless IXO set another). `API_PAYMENTS: "false"` is the kill
+switch: new x402 submits answer 503 `payments-disabled`, `none` sources keep deciding.
 
 ### Pricing and card
 
-The price per decision is `pricing.api` in `src/oracle.ts` (micro-USD, whole cents; `byProtocol` per
-protocol), or the `API_PRICE_USD_CENTS` var when `pricing.api` is absent. Change it and redeploy;
-the facilitator picks it up within ~5 min. **Card needs ≥ 50¢ per decision** (Stripe's minimum,
-checked per claim), so a cheaper price offers PAY only. The example is 60¢ for that reason. The
+The price per decision is `pricing.api` in `defineOracle` in `src/index.ts`:
+`pricing: { api: { amountMicroUsd: 600_000, byProtocol?: { "<protocol did>": … } } }` — micro-USD
+(1 USD = 1 000 000), a whole number of cents (a multiple of 10 000). With no `pricing.api`, the
+`API_PRICE_USD_CENTS` var is the price. Change it and redeploy; the facilitator picks it up within
+~5 min — the `update-pricing` skill walks the change, the card refresh included. **Card needs ≥ 50¢
+per decision** (Stripe's minimum, checked per claim), so a cheaper price offers PAY only. The
 Decision Console shows the price and card eligibility read-only.
 
 ## Troubleshooting
@@ -325,17 +329,18 @@ Decision Console shows the price and card eligibility read-only.
 | Worker 500s on every request after deploy; logs say `WEBHOOK_ENCRYPTION_KEY: required when API_LANE is on` | the secret is missing in that env — `bunx wrangler secret put WEBHOOK_ENCRYPTION_KEY --env <env>` (for a new deployment only; never replace an existing one) |
 | Worker 500s on every request; logs say `CHAIN_LANE is off and API_LANE is not on` | an oracle with no lane — set `"API_LANE": "true"` in that env's `vars` (with its secrets), or remove `CHAIN_LANE` |
 | `register` / `scan` / an OpenHands webhook answers 409 `chain_lane_off` | the oracle is API-only (`CHAIN_LANE` `"false"`) — by design; set it back to `"true"` and redeploy to take chain hires again |
+| `PUT /v1/api/uploads` answers 501 | no `API_UPLOADS` bucket bound in that env — step 4 |
 | `PROTOCOL_NOT_ALLOWED` on submit | the source's allow-list lacks it — empty means NONE; `api admin protocols <src> <did> --yes` |
 | 503 `SOURCE_PAUSED` `payments-disabled` | `API_PAYMENTS` is off and the source bills `x402` — turn payments on, or `api admin billing-mode <src> none` |
 | 402 again after a `PAYMENT-SIGNATURE` | the facilitator refused the payer: no deed / no `SendAuthorization` / not enough PAY — the fresh 402's error says which |
 | offers refused `plan_inactive`, `accepts: []` | the facilitator finds no active plan for the oracle: it is not registered with the engine (step 6 — registered, it runs on Standard at once), or, for an IXO-run oracle, IXO has not activated its plan (**HUMAN**: ask IXO). A way to pay whose payee is unset (`EARNINGS_ADDRESS` for PAY / USDC on IXO, `EARNINGS_BASE_WALLET` for USDC on Base) is simply not offered |
-| Not listed in the console | not registered with the engine (step 6), or not payable (the row above); or `https://<ORACLE_HOSTNAME>/.well-known/did.json` does not answer; or `CORS_ORIGINS` lacks `https://decision-console.devnet.ixo.earth` |
-| Every API claim rejects with `frequency` | the caller sends no `submitter` — an uncountable window fails closed; send the courier id |
+| Not listed in the console | not registered with the engine (step 6), or not payable (the row above); or `https://<ORACLE_HOSTNAME>/.well-known/did.json` does not answer; or `CORS_ORIGINS` lacks the console's origin |
+| Every API claim rejects with `frequency` | the caller sends no `submitter` — an uncountable window fails closed; send a stable id for the person |
 | 409 `REVIEW_EXPIRED` on a review answer | the paid claim's `answerBy` (its x402 reservation's expiry: extended up to 30 days for the review, else 24 h after verify) has passed — it can no longer be paid, and nothing was written. Answer paid reviews before the date the emails state |
-| Claims go `pending_review` on `SD-RT-CHECKS` (example) | an errored fact (onError `review`) held them for a person: the AI provider unavailable (the photo check — no gateway credits, or `OPENROUTER_API_KEY` missing on `openrouter`), or the orders endpoint unreachable (`DEMO_ORDERS` off, or an `ORD-…-E` order) — read the claim's report; fix it, and new claims decide again (the held ones are answered in the console). A rubric without a claim-level ReviewTask parks such claims `review` with NO task — give it one |
+| Claims go `pending_review` on a claim-level review task you did not expect | an errored fact (onError `review`) held them for a person: the AI provider unavailable (no gateway credits, or `OPENROUTER_API_KEY` missing on `openrouter`), or an `ext` endpoint unreachable — read the claim's report; fix it, and new claims decide again (the held ones are answered in the console). A rubric without a claim-level ReviewTask parks such claims `review` with NO task — give it one |
 | `engine register` refuses: "registered … as <old> — this would re-bind it to <new>" | the did:web is bound to another key on the engine — the configured `ORACLE_SECP_MNEMONIC` is not the one it registered with. Restore the old key, or (owner's OK) `--yes` |
 | No emails at all | the `EMAIL_FROM_ADDRESS` domain is not onboarded, or `CONSOLE_URL` is unset — the lane logs and skips |
-| `engine register` 402 | the owner's credits — top up at the printed URL, re-run |
+| `engine register` 402 | the owner's engine credits — buy them in the Decision Console (Billing › Credits), re-run |
 | `/health/ready` 503 while the worker otherwise serves | `GET /v1/admin/status` names the failed check; `identity` ⇒ no `ORACLE_ENTITY_DID` on a deployed host — finish step 7 (`oracle init`, pin it in every `vars` block, redeploy) |
 | `engine register` fails resolving the did:web | the env is not deployed yet, or `--env <env>` was left off (it registered `localhost`) |
 
@@ -344,5 +349,5 @@ Decision Console shows the price and card eligibility read-only.
 Say plainly what is done and what is owed: the protocol DID and where it was written, the
 worker's host and did:web, the oracle entity DID (`/v1/info` `entityDid`) and the `/health/ready`
 answer, which ids and secrets were set (names only), the engine registration and
-billing status, whether the oracle is listed/payable, the smoke's last line and
-any FAIL lines verbatim, the email rows seen, and every HUMAN step still open.
+billing status, whether the oracle is listed/payable, each verify claim's outcome, the email rows
+seen, and every HUMAN step still open.