@ixo/decision-oracle 0.2.1 → 0.2.3

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

@@ -1,6 +1,6 @@
 ---
 name: decision-api-client
-description: Use when testing a Decision API oracle from the CUSTOMER side — minting a test source, API key and payment delegation on devnet, running the TypeScript SDK (@ixo/decision-oracle-client) or its CLI against a live oracle, connecting Claude Code to an oracle's hosted MCP server (/v1/mcp), running the docs agent test — or when debugging a client-side failure (402 not paid, SCOPE, DELEGATION_EXPIRED, terms_mismatch, a receipt that will not verify).
+description: Use when testing a Decision API oracle from the CUSTOMER side — minting a test source, API key and payment delegation on devnet, running the TypeScript SDK (@ixo/decision-oracle-client) or its CLI against a live oracle, connecting Claude Code to an oracle's hosted MCP server (/v1/mcp), or when debugging a client-side failure (402 not paid, SCOPE, DELEGATION_EXPIRED, terms_mismatch, a receipt that will not verify).
 ---
 
 # The Decision API from the customer side, on devnet
@@ -10,17 +10,17 @@ description: Use when testing a Decision API oracle from the CUSTOMER side — m
 A Decision API oracle (`API_LANE` on; set one up with `decision-api-oracle`) is used by customers
 through three doors, all over the same `/v1/api` routes with an API key:
 
-- the SDK and CLI, `@ixo/decision-oracle-client` (`packages/client` in this repo);
+- the SDK and CLI, `@ixo/decision-oracle-client` (on npm);
 - the hosted MCP server at `https://<oracle>/v1/mcp` (four tools, the same key, or a sign-in
   through AuthHub with an approval per submit);
-- plain HTTP, with the docs (`site`, and its `llms-full.txt` for agents).
+- plain HTTP, with the Decision API docs (their `llms-full.txt` is written for agents).
 
 A source in billing mode `x402` answers a submit with `402`. The payer pays it with the
 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 20¢. Its `/demo/orders?route=<id>`
+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.
 
@@ -46,45 +46,42 @@ bunx decision-oracle login --network devnet     # once; a browser step for the h
 ```
 
 The session's DID must be in the oracle's `ORACLE_ADMIN_DIDS` to set a source's billing mode and
-protocols. For IXO's example it already is. Its deed needs devnet PAY; top up in the console
+protocols — on someone else's oracle, ask its operator to do those two steps. Its deed needs devnet PAY; top up in the console
 (`decision-console.devnet.ixo.earth`, Credits).
 
 ### 1. Credentials: a source, two keys and a delegation
 
-**In this repo** (one command; secrets are written to the file with mode 600 and never printed):
-
-```bash
-cd packages/client
-bun run devnet:credentials -- --oracle https://shipment-delivery-oracle.devnet.ixo.earth \
-  --protocol did:ixo:entity:c2f5a188d28f3d4bf6351873d3d268ea --out ~/.ixo/decision-api-devnet.env
-#   --source src_…      reuse an existing source; --max-pay 2 (PAY); --days 7
-```
-
-It writes `IXO_ORACLE_URL`, `IXO_PROTOCOL_DID`, `IXO_SOURCE_ID`, `IXO_API_KEY` (claims:write,
-claims:read, webhooks:manage), `IXO_API_KEY_READONLY` (claims:read) and `IXO_PAYMENT_DELEGATION`.
-
-**Anywhere else:**
-
 ```bash
 eo() { bunx decision-oracle "$@" --kit https://<oracle> --network devnet --json; }
-eo api source create --name <n> --contact <email>        # sourceId + webhookSecret, shown once
+eo api source create --name <n> --contact <email> --entity <org did>   # sourceId + webhookSecret, shown once
 eo api admin billing-mode <sourceId> x402 --yes          # operator only
 eo api admin protocols <sourceId> <protocolDid> --yes    # operator only
 eo api key create --source <sourceId> --scopes claims:write,claims:read --name test
 ```
 
-For the delegation, use the console's Keys page ("Payment delegation"), which shows
-`IXO_PAYMENT_DELEGATION` once.
+`--entity` is required: the organisation the source belongs to, which the login must control (make
+one with `decision-oracle org create --name …`). The source stays `pending-link` until
+`eo api source link <sourceId> --yes`. For the delegation, use the console's Keys page ("Payment
+delegation"), which shows `IXO_PAYMENT_DELEGATION` once.
+
+Keep the values in a file of your own (mode 600), never printed: the client reads `IXO_ORACLE_URL`,
+`IXO_API_KEY` and `IXO_PAYMENT_DELEGATION` from the environment. Mint a second, read-only key
+(`--scopes claims:read`) for the `SCOPE` check.
 
 Revoke keys you no longer need: `eo api key revoke --source <id> <8-char prefix> --yes`.
 
-### 2. The SDK smoke (this repo)
+### 2. The CLI and the SDK
+
+With the `IXO_*` variables from step 1 in the environment:
 
 ```bash
-cd packages/client && bun run build && node dev/devnet-smoke.ts   # --env <file> --photo <jpg>
+npx @ixo/decision-oracle-client submit claim.json      # waits up to 60 s; pays the 402
+npx @ixo/decision-oracle-client watch apc_…            # the timeline to the decision
+npx @ixo/decision-oracle-client keys                   # the source's keys, masked
 ```
 
-It runs under plain node, through the BUILT dist. That is what a customer installs. It checks:
+The SDK is the same package (`npm i @ixo/decision-oracle-client`; pass `paymentDelegation` to pay
+402s). A passing run shows:
 
 - the work order and its price;
 - an upload;
@@ -92,25 +89,12 @@ It runs under plain node, through the BUILT dist. That is what a customer instal
 - a decision, and a payment on the record;
 - `verifyReceipt` against the engine's did.json;
 - events;
-- a replay with the same key naming the same claim;
-- `SCOPE` for the read-only key;
-- the CLI reading the claim.
-
-It spends one claim. Every line must read `PASS`. Any verdict counts (`reject` is normal for a
-parcel photo that doesn't match).
+- a replay with the same idempotency key naming the same claim;
+- `SCOPE` for the read-only key.
 
-### 3. The CLI by hand
-
-```bash
-set -a; . ~/.ixo/decision-api-devnet.env; set +a
-node packages/client/dist/cli/index.js submit claim.json      # waits up to 60 s; pays the 402
-node packages/client/dist/cli/index.js watch apc_…            # the timeline to the decision
-node packages/client/dist/cli/index.js keys                   # the source's keys, masked
-```
+Any verdict counts (`reject` is normal for a parcel photo that doesn't match).
 
-Outside this repo: `npx @ixo/decision-oracle-client …` (once published).
-
-### 4. MCP from Claude Code
+### 3. MCP from Claude Code
 
 The route ships with the oracle package, so the oracle must be deployed from a version that has
 `src/routes/v1/mcp`. Check with `curl -s -o /dev/null -w "%{http_code}" -X POST https://<oracle>/v1/mcp`:
@@ -159,55 +143,25 @@ 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.
 
-### 5. The docs agent test (this repo)
-
-```bash
-(cd site && bun install && bun run build)
-set -a; . ~/.ixo/decision-api-devnet.env; set +a
-bun site/agent-test/run.ts            # exit 0 pass · 1 fail · 2 skipped (no credentials)
-```
-
-A Claude model gets only the site's `llms-full.txt`, the key, the delegation and one
-`http_request` tool locked to the oracle's origin. It must reach a decision it paid for itself.
-The script checks the result, not the model's word. It costs a few cents of model usage plus
-one claim.
-
-### 6. Card scenarios (devnet, Stripe test mode)
+### 4. Card scenarios (devnet, Stripe test mode)
 
-Card needs an oracle whose protocol costs **≥ 50¢ per claim** (Stripe's minimum capture; SwiftDrop 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 owns the facilitator
-(ixo-pay-facilitator `.claude/skills/devnet-card-check`). This half pays:
+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 }`):
 
-```bash
-cd packages/client && bun run build
-node dev/devnet-card.ts submit card      # prefer card; `upay` = PAY first; `none` = the console default
-node dev/devnet-card.ts resume           # after a 3-D Secure confirm: the SAME offer, same key
-```
-
-| Payer's default card (facilitator side) | Run | Expect |
+| Payer's default card (facilitator side) | Submit with | Expect |
 | --- | --- | --- |
-| `pm_card_authenticationRequired` | `submit card` | `CARD_AUTHENTICATION_REQUIRED` + `confirmUrl`; once confirmed, `resume` → paid with the SAME PaymentIntent. Left unconfirmed, the facilitator cancels it ~17 min later, never charged |
-| `pm_card_chargeCustomerFail` | `submit card` | declined at authorize → paid with PAY for the same 402 |
-| `pm_card_createDispute` | `submit 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` | `submit none` | the SDK reads `/v1/payer/preferences` with the delegation → card |
+| `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. Proven end to
-end on 2026-10-01, pre-company-authority (2026-10-10) (SwiftDrop at 60¢; each card capture paid IXO
-its 20% fee).
-
-## Working on the client in this repo (maintainers)
-
-- **`@ixo/x402-ixo-pay` comes from npm** (0.5.2, published from ixo-pay-facilitator
-  `packages/x402-ixo-pay`) as an ordinary runtime dependency; the client's `dist/` imports it. A
-  facilitator wire change means a new version published there, then a bump here.
-- **`packages/client/scripts/pack-test.sh`** (run first by `pack-smoke.sh`) proves the tarball
-  stands alone: every dependency is a registry version (no git, `file:` or workspace spec), it
-  installs with git turned off, and it pays and runs its bin under plain node.
-- **Types come from the OpenAPI.** Run `bun run generate` after the OpenAPI changes. It uses
-  `npx` with TypeScript 5, because TS 7 has no JS compiler API and openapi-typescript needs one.
+A run that answers `SPEND_CAP` has used up the delegation's `maxAmount`: mint a new one.
 
 ## When something fails
 
@@ -218,11 +172,11 @@ its 20% fee).
 | MCP `SUBMITTER_REQUIRED` | The protocol has a frequency rule (its work order says `facts.frequency: true`), so `submit_claim` needs `submitter`, your stable id for the person (e.g. the courier id). Without it the engine would reject the claim, so it is refused before any approval or charge. |
 | The AI asks you to upload a photo | There is no upload over sign-in. Give it an https link; `submit_claim` attaches `{ question, url }` and the oracle fetches it. No `mediaType` is needed: the oracle reads it from the URL's extension, else a `HEAD`, when it accepts the claim. |
 | Claude Code refuses `submit_claim` ("real-world transaction") | Its safety check is holding back a tool that may spend. Allow only this tool: `/permissions` › Allow › `mcp__<server>__submit_claim`. Never turn the safety check off. Every charge still needs the user's AuthHub approval or their auto-approve limits. |
-| `PaymentError DELEGATION_WRONG_ORACLE` | The delegation is bound to other oracles. Re-sign it naming this oracle's `did:web` (console Keys › Payment delegation; `devnet:credentials` binds to `--oracle`). |
+| `PaymentError DELEGATION_WRONG_ORACLE` | The delegation is bound to other oracles. Re-sign it naming this oracle's `did:web` (console Keys › Payment delegation). |
 | `PaymentError CARD_NOT_SAVED` | The payer has no saved card and the 402 took card only (or `prefer: "card"` with no PAY to fall back to). Save a card on the console's card page, or pay with PAY. |
 | `PaymentError CARD_AUTHENTICATION_REQUIRED` | The bank wants 3-D Secure. Open `err.confirmUrl` and confirm within 15 min, then resubmit with `{ idempotencyKey: err.idempotencyKey, resumePayment: err.paymentRequired }` — never a fresh offer. `OFFER_EXPIRED` on the resume: the gate no longer takes that offer; submit afresh. `INVALID_RESUME`: the offer passed is not this oracle's card 402. |
 | `402 INSUFFICIENT_CREDITS` (+ `fundingUrl`) | The session's deed has too little devnet PAY. Top up in the console. |
-| `402 SPEND_CAP` | The key's daily cap or the delegation's `maxAmount` is spent. Mint a delegation with a higher `--max-pay`. |
+| `402 SPEND_CAP` | The key's daily cap or the delegation's `maxAmount` is spent. Mint a new delegation with a higher cap (console Keys › Payment delegation). |
 | `403 PAYER_NOT_MEMBER` | The delegation's issuer isn't the source's owner or a member. Mint it from the owner's session. |
 | `409 IDEMPOTENCY_MISMATCH` | Same `Idempotency-Key`, different body. Use a new key per new claim. |
 | `terms_mismatch` on the paid resend | `accepted` wasn't the offer entry verbatim. Hand-built headers must copy it byte for byte. |

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

@@ -11,7 +11,9 @@ The Decision API (`API_LANE`) is an oracle's second intake: paid, off-chain clai
 `/v1/api`, decided by the same engine, never written to chain. The oracle holds the sources, keys,
 uploads, reviews and webhooks; the engine decides and bills per the oracle's **plan** (the Standard
 plan from the moment it registers, unless IXO sets another);
-the payments facilitator settles each claim in PAY; the Decision Console
+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.
 
 The worked run is **`examples/shipment-delivery`** in this package's repo — SwiftDrop Express, a
@@ -44,18 +46,16 @@ is the package CLI.
 ### 0. Prerequisites
 
 ```bash
-bunx wrangler whoami                        # the Cloudflare account that owns the ixo.earth zone
+bunx wrangler whoami                        # the Cloudflare account that owns your host's zone
 bunx decision-oracle login --network devnet     # the OWNER's AuthHub session — once
 ```
 
 - `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; the session file
-  `~/.ixo/publish-session-<network>.json` has the `did`) 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.
-- The account must hold the zone of the host (`*.ixo.earth` for IXO's deployments), or the Custom
-  Domain cannot attach. If `whoami` shows another account, stop and say so (**HUMAN**).
+  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.
+- 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**).
 
 ### 1. The protocol (example: publish `protocol/`; a provider: their protocol's DID)
 
@@ -160,15 +160,14 @@ If the engine already binds this did:web to a DIFFERENT address, it prints old
 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 in PAY, take 20%, paid to the owner's deed account,
-listed in the Decision Console). Nothing to request. Done when the oracle appears in the engine's
+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).
 
-**Example only (IXO's own oracles):** IXO staff switch the oracle to the IXO-owned plan in the
-engine's admin plan editor (**HUMAN**, IXO staff) — the example's README names its terms. Done when
-IXO confirms the oracle's plan version is > 0 (Standard is version 0).
+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.
 
-### 7. On chain — the full identity (mandatory, owner 2026-10-01)
+### 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
@@ -191,9 +190,12 @@ 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:
+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):
 
 ```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"
 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
@@ -205,7 +207,9 @@ 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). The login must be the organisation's
+`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`.
 
@@ -238,18 +242,16 @@ 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 test account's key file or its address in
-  `~/.ixo/test-accounts-registry.json`; on devnet the default is SwiftDrop's admin Sara,
-  `~/.config/ixo-payouts/test-accounts/swiftdrop-sara.json`, controller of `--entity`'s default,
-  SwiftDrop's organisation `did:ixo:entity:2eeb3a4c03f3755872ada894734e47d2`): a source belongs to
-  an organisation (D10), so the controller creates it (`POST /v1/api/sources { entityDid }` →
+- **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`, from `~/.ixo/test-accounts.json`; default the network's first
-  account that is neither of the two — make one with the `ixo-test-account` skill): a MEMBER. The
+- **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).
@@ -259,19 +261,18 @@ fixtures, decides one stop per row of the example's outcome table (approve prepa
 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 (devnet's
-reviewer is Dan — never an oracle operator's account, which the engine refuses in a reviewer grant), waits for the engine's fold (`decided partial`), walks
+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 facilitator (`ixo173l540tvyu43ghmtstl2wu2lqztdt5e05e05c6`)
-  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=ixo173l540tvyu43ghmtstl2wu2lqztdt5e05e05c6&msg_type_url=/cosmos.bank.v1beta1.MsgSend"`.
-  Spends one decision price of PAY (60¢ in the example). The next SwiftDrop smoke after the
-  company-authority joint deploy runs with `--paid`.
+  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).
 
 ### 10. Verify — the six member / review emails
 
@@ -292,7 +293,8 @@ With the owner's email as the test inbox, in the console (**HUMAN** clicks; you
 ### 11. Payments on (a provider turning it on)
 
 `API_PAYMENTS: "true"`, `X402_FACILITATOR_URL`, `X402_NETWORK` (`cosmos:devnet-1` / `cosmos:pandora-8`
-/ `cosmos:ixo-5`) and `EARNINGS_ADDRESS` (the operator's own `ixo1…`, each offer's `payTo`; unset ⇒ no PAY)
+/ `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:
@@ -316,7 +318,7 @@ Decision Console shows the price and card eligibility read-only.
 | `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 engine has nobody to pay: the oracle is not registered (step 6), or its owner has no oracle claims collection / deed account to receive the Standard payout (the owner's subscription sets that up — **HUMAN**); the refusal's reason 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 the host is not a `*.ixo.earth` Custom Domain; 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 |
 | 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 |
@@ -332,5 +334,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 (for IXO's own: the plan version IXO confirmed), the smoke's last line 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.

package/skills/publish-protocol/SKILL.md

@@ -14,8 +14,9 @@ submissions against it. This skill composes two things:
 
 - **`create-rubric`** authors and validates the form + rubric pair. The decision engine owns the
   rubric format; `bunx decision-oracle rubric validate` is that engine over HTTP.
-- **`bunx decision-oracle publish-protocol`** does the chain authoring: `MsgCreateEntity` → Matrix
-  upload → `MsgAddLinkedResource` (`#vct` + `#rub`) + `MsgAddService` → source the Matrix room.
+- **`bunx decision-oracle publish-protocol`** does the chain authoring: `MsgCreateEntity` → upload
+  to the IXO Vault (else the IXO IPFS gateway; never Matrix media) → `MsgAddLinkedResource` (`#vct`
+  + `#rub`) + `MsgAddService` → source the Matrix room.
   Phases `entity` / `resources` / `room` (default `all`), resumable with `--entity <did> --phase <p>`.
   Plus `rub`, which is a different job — see below.
 
@@ -89,6 +90,17 @@ There are two jobs here, and picking the wrong one fails on chain:
    protocols are linked to this entity". `create-collection`'s `reference/claims-stack.md` has the
    model.
 
+**Proofs.** Both proofs this command writes are the sha256 HEX of the exact uploaded bytes — the
+engine string-compares them, and the `#rub` proof IS the rubric's id. A protocol published through
+the Portal carries a CID as its `#vct` proof instead. Never recompute someone else's proof: read the
+anchored value off chain and use it verbatim (`--phase rub` does exactly that).
+`../reference/linked-docs.md` has the rules for every linked document in one place.
+
+**No profile yet — the protocol shows as "Unnamed".** `publish-protocol` writes no `#pro` profile,
+so Portals and Consoles list the protocol as "Unnamed" until one is anchored on it. The profile is a
+`#pro` linked resource: type `Settings`, `application/ld+json`, its proof the CIDv1 of the uploaded
+bytes. This CLI has no flag for it — tell the user it is still owed.
+
 ## Adopting a protocol that already has its form — `--phase rub`
 
 Use this when the protocol EXISTS and carries a `#vct` already: IXO's own oracle-service-claim
@@ -116,7 +128,7 @@ Three things to expect:
   prints `already anchored` and does nothing — no upload, no transaction, no fee.
 - **Only the protocol's owner can anchor.** If the session doesn't own it, the rubric is still
   uploaded and the exact messages are printed, composed for the owner to broadcast. Send them those
-  lines; they sign them. (Same posture as `oracle init --phase backlink`.)
+  lines; they sign them. (Same posture as `oracle init --only backlink`.)
 - **The room is not this command's business.** A protocol that already has claims already has its
   room; `--phase rub` never touches it.
 
@@ -149,3 +161,6 @@ owed: a phase that failed, an un-invited bot, or a rubric change that would need
 
 `reference/publishing.md` — phase-by-phase detail (what each signs and uploads), resuming a partial
 run, the Matrix identity rule, and the network endpoints.
+
+`../reference/linked-docs.md` — the linked-document rules: where uploads go, each proof's format,
+and how to read one.

package/skills/publish-protocol/reference/publishing.md

@@ -64,7 +64,7 @@ bunx decision-oracle publish-protocol --phase rub --protocol <did> \
 **Ownership.** The chain checks the signer against the DID's authentication relationship, so only
 the protocol's owner can anchor. When the session is not the owner the messages are composed for the
 owner, printed, and not broadcast — the upload has already happened, so all they have to do is sign
-the printed lines. Same behaviour as `oracle init --phase backlink`.
+the printed lines. Same behaviour as `oracle init --only backlink`.
 
 `--form` stays required: it is what the engine's binder validates the rubric against before anything
 is written. Get it with `rubric fetch-form --protocol <did> --out form.json`, which downloads the

package/skills/reference/engine-contract.md

@@ -78,7 +78,7 @@ 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 |
+| 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) |
 | 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 |

package/skills/reference/linked-docs.md

@@ -0,0 +1,35 @@
+# Linked documents (what an entity's LinkedResources point at)
+
+Every public document an entity carries — a protocol's form (`#vct`) and rubric (`#rub`), an
+oracle's `#orz`, `#pro` profile, `#dmn` domain card and `#acard` Agent Card, an ask's documents —
+is a LinkedResource: an https URL (`serviceEndpoint`) plus a hash of the exact bytes (`proof`).
+The CLI writes and reads them for you; these are the rules it follows, for anything you write or
+read yourself.
+
+## Where the bytes go
+
+1. **The IXO Vault first** — `https://{devnet.|testnet.|}vfs.ixo.earth/public/cid/<cid>`, uploaded
+   under a UCAN signed by the document's OWNER (the AuthHub session). Public at once, no auth.
+2. **The IXO IPFS gateway as the fallback** — `https://ipfs.gateway.ixo.world/ipfs/<cid>`. Never a
+   public gateway (`ipfs.io` and friends rate-limit).
+3. **Never Matrix media for a new document.** Old documents keep their Matrix download URLs and stay
+   readable; nothing new is written there.
+
+`serviceEndpoint` is always that full https URL — never a bare `ipfs:` or `mxc://`.
+
+## The proof, by resource
+
+| Resource | `proof` |
+| --- | --- |
+| `#vct`, `#rub`, `#orz` (`application/json`) | **sha256 hex** of the bytes. The engine string-compares it: a rubric's `claimSchema.proof` must equal the `#vct` proof verbatim, and a `#rub` proof is the rubric's id |
+| `#pro` (type `Settings`), `#dmn`, `#acard` (`application/ld+json`) | **CIDv1, raw, sha256** (`bafkrei…`) of the bytes |
+
+A protocol published through the Portal has a CID as its `#vct` proof. **Never recompute someone
+else's proof** — read the anchored value off chain and use it verbatim.
+
+## Reading one
+
+`readLinkedDoc(resource)` from `@ixo/decision-oracle/facts` (node-safe): a plain GET with no auth.
+It accepts Vault and gateway URLs, bare `ipfs:` / `ipfs://` CIDs (resolved through the IXO
+gateway) and old Matrix download URLs, hashes the bytes the way the proof was made (hex or CID), and
+fails closed on a mismatch. `linkedDocUrl(endpoint)` gives just the fetchable URL.

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

@@ -88,8 +88,8 @@ over whatever a handler put there. **A handler cannot turn its own failure into
 **A deterministic failure is a fact; a transient one is a retry.** Don't `catch` a transient
 engine/chain error yourself and turn it into `fact.error(...)` — that freezes a verdict over
 trouble that was never the claim's fault, and a claim is decided once, so it can never be re-run
-(task-14, 2026-09-14: a devnet claim was held for review on every fact because the engine's own 5xx
-got frozen this way). `tools.agreement()` and `tools.chain.*` already let a retryable failure
+(a claim whose every fact froze over the engine's own 5xx this way is held for review on all of
+them). `tools.agreement()` and `tools.chain.*` already let a retryable failure
 propagate instead of catching it — see below.
 
 ## One call, many facts
@@ -149,7 +149,7 @@ does: `readAnswer(answers, "$q.row.col")` and `rootQuestionName("$deliveryPhoto"
 answers `[]`. Blocksync being *unreachable* is a different thing and throws, which the runner passes
 through as the step's retry signal — so a chain outage retries instead of freezing a verdict. Catch
 it only if "could not read the chain" is genuinely the fact you mean, and then say so with
-`fact.error`. `tools.agreement()` follows the same rule against the eval engine (task-14): a real
+`fact.error`. `tools.agreement()` follows the same rule against the eval engine: a real
 "no agreement on file" is `null`, a transient engine outage throws.
 
 **There is no GENERAL chain message-history read, and you must not build one.** The one thing an