@ixo/decision-oracle 0.2.1 → 0.2.3

package/dist/routes/v1/api/openapi.gen.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.gen.js","sourceRoot":"","sources":["../../../../src/routes/v1/api/openapi.gen.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iGAAiG;AACjG,sEAAsE;AAEtE,mGAAmG;AACnG,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAA4B,IAAI,CAAC,KAAK,CAAC,++jXAA++jX,CAAC,CAAC"}
+{"version":3,"file":"openapi.gen.js","sourceRoot":"","sources":["../../../../src/routes/v1/api/openapi.gen.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iGAAiG;AACjG,sEAAsE;AAEtE,mGAAmG;AACnG,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAA4B,IAAI,CAAC,KAAK,CAAC,+gkXAA+gkX,CAAC,CAAC"}

package/docs/api.md

@@ -1582,7 +1582,7 @@ once deployed. Every value is validated by Zod at isolate start, so a bad env fa
 | `EARNINGS_ADDRESS` | vars | unset | Where your earnings for decisions land in PAY and USDC on IXO: your own `ixo1…` account, sent as each offer's `payTo` (the facilitator checks it, never picks one). Checked at start, checksum included. Needed only when IXO's plan for the oracle takes PAY (the engine's `GET /v1/oracles/me` `accepts` holds `upay`; KV-cached 5 min): unset then ⇒ new x402 submits answer `503 SOURCE_PAUSED { reason: payments-disabled }`. A plan without PAY (card and/or USDC on Base) sends no ixo-pay terms and never reads it; a plan the engine cannot tell is the same 503 |
 | `EARNINGS_BASE_WALLET` | vars | unset | Your Base wallet (`0x…`) for USDC on Base. Unset ⇒ that way to pay is not offered |
 | `BILLING_ENGINE_URL` | vars | unset | Charge lookups and the spend figures on `/v1/api/me`. No trailing slash |
-| `CONSOLE_URL` | vars | unset | The Decision Console — every error's `docsUrl`, the 402's `fundingUrl`, and every email link (the `balance.low` email's is `<CONSOLE_URL>/credits`). Unset ⇒ the API lane's emails are logged skips. No trailing slash |
+| `CONSOLE_URL` | vars | unset | The Decision Console — every error's `docsUrl`, the 402's `fundingUrl`, and every email link (the `balance.low` email's is `<CONSOLE_URL>/billing/credits`). Unset ⇒ the API lane's emails are logged skips. No trailing slash |
 | `AUTH_HUB_URL` | vars | per `IXO_NETWORK` (`https://dev.auth.ixo.earth`, `https://test.auth.ixo.earth`, `https://auth.ixo.earth`) | IXO AuthHub, the OAuth server of `/v1/mcp`: the protected-resource metadata's `authorization_servers`, the exact `iss` of an access token (its JWKS at `<url>/.well-known/jwks.json`), the approve link's host, and the one `did:web` (`did:web:<its host>`) the approvals back-channel accepts. Set it only for a local AuthHub. No trailing slash |
 | `ORACLE_ADMIN_DIDS` | vars | unset | Comma-separated `did:ixo` admins of this oracle — the oracle's operator's own people — allowed on `GET /v1/admin/status` and `/v1/api/admin/*`. Unset ⇒ nobody |
 | `STATUS_READER_DIDS` | vars | unset | Comma-separated DIDs of any method (`did:web:…`, `did:ixo:…`, each checked as `did:<method>:<id>`) allowed to read `GET /v1/admin/status` and nothing else — for a monitoring service, e.g. your decision engine's status board, identified by its DID. Kept apart from `ORACLE_ADMIN_DIDS` so a monitor is never made an operator. Unset ⇒ nobody |
@@ -2069,7 +2069,7 @@ receivers de-duplicate on `Oracle-Event-Id`. An erased row stays erased and goes
 minutes) reads each active source's payer balance against its `refillFloorCents`. The first read
 below the floor sends one `balance.low` webhook (`{ sourceId, balanceCents, floorCents }`) and one
 email to the source's `contactEmail`: the source's name, the balance and the floor as dollars, and
-an "Add credits" link to `${CONSOLE_URL}/credits`. The webhook goes once per crossing (a recovery
+an "Add credits" link to `${CONSOLE_URL}/billing/credits`. The webhook goes once per crossing (a recovery
 above the floor re-arms it). The email goes once per UTC day while the balance stays under the
 floor (`notice_balance_low:<sourceId>:<yyyy-mm-dd>`): still low tomorrow is a new email, a balance
 bobbing around its floor within a day is one, and a send that fails is retried on the next check.

package/docs/guide.md

@@ -1280,7 +1280,7 @@ claim is ever blocked on one.
 facilitator configured, the balance watch (every 5 minutes) sends a `balance.low` webhook the
 first time the payer's balance drops below it, and emails the source's `contactEmail` once per UTC
 day while it stays below (a send that fails is retried on the next check): the balance against the floor in dollars, and an "Add credits" link to your console's
-Credits page (`CONSOLE_URL/credits`). Without `CONSOLE_URL` or a sender, the email is a logged skip.
+Credits page (`CONSOLE_URL/billing/credits`). Without `CONSOLE_URL` or a sender, the email is a logged skip.
 
 **Uptime and status.** Point your uptime monitor (Sentry Uptime, or any HTTP checker, every
 minute) at `GET /health/ready`, not `/health`: `/health` only proves the worker boots, while

package/openapi/decision-api.yaml

@@ -335,10 +335,10 @@ info:
 
 
     **Changes in 1.19.0.** No wire change. The CLI gains the console's onboarding steps:
-    `decision-oracle org create` (an organisation entity, idempotent by name), `decision-oracle api source
-    link <sourceId>` (signs the organisation's link, PUTs it to the engine and calls `POST
-    /v1/api/sources/{sourceId}/company/sync`: `pending-link` → `active`), `decision-oracle org balance`
-    and `decision-oracle logout`.
+    `decision-oracle org create` (an organisation entity, idempotent by name), `decision-oracle api
+    source link <sourceId>` (signs the organisation's link, PUTs it to the engine and calls `POST
+    /v1/api/sources/{sourceId}/company/sync`: `pending-link` → `active`), `decision-oracle org
+    balance` and `decision-oracle logout`.
 
 
     **Changes in 1.20.0.** Additive: `ClaimRecord.decision.erroredFacts` and
@@ -7754,14 +7754,14 @@ components:
                           maxTimeoutSeconds: 120
                           extra:
                             nonce: 7c1e2a4b-9d3f-4e8a-b6c5-2f1d0e9a8b7c
-                            fundingUrl: https://console.ixo.earth/credits
+                            fundingUrl: https://console.ixo.earth/billing/credits
                     price:
                       amountMicroUsd: 1200000
                       amountCents: 120
                       currency: USD
                       amount: "1200000"
                       asset: upay
-                    fundingUrl: https://console.ixo.earth/credits
+                    fundingUrl: https://console.ixo.earth/billing/credits
                   docsUrl: https://console.ixo.earth/docs/errors#PAYMENT_REQUIRED
             SPEND_CAP:
               value:
@@ -7777,7 +7777,7 @@ components:
                       currency: USD
                       amount: "1200000"
                       asset: upay
-                    fundingUrl: https://console.ixo.earth/credits
+                    fundingUrl: https://console.ixo.earth/billing/credits
                   docsUrl: https://console.ixo.earth/docs/errors#SPEND_CAP
             INSUFFICIENT_CREDITS:
               value:
@@ -7793,7 +7793,7 @@ components:
                       currency: USD
                       amount: "1200000"
                       asset: upay
-                    fundingUrl: https://console.ixo.earth/credits
+                    fundingUrl: https://console.ixo.earth/billing/credits
                   docsUrl: https://console.ixo.earth/docs/errors#INSUFFICIENT_CREDITS
     NotFound:
       description: "`NOT_FOUND` — unknown, or another source's (never 403 across sources)."

package/package.json

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

package/skills/README.md

@@ -17,3 +17,5 @@ installed package (leaving any skill of your own in that directory alone).
 
 `reference/engine-contract.md` (here, beside the skills) is the decision engine's contract —
 background for all eight, not an interface anyone codes against.
+`reference/linked-docs.md` is the linked-document rules: where an entity's documents are uploaded,
+each proof's format, and how to read one.

package/skills/add-openhands-support/SKILL.md

@@ -21,7 +21,7 @@ and wait for their OK. Dry-run every chain step first (`create-oracle` step 8's
 ## The adapter (copy, don't rewrite)
 
 Source of truth: `examples/street-check-oracle` in the eval-oracle repo (an `init` project with
-the adapter added, deployed on devnet), itself ported from `ixoworld/openhands-oracle`. Copy:
+the adapter added, deployed on devnet). Copy:
 
 | Path | What it is |
 | --- | --- |
@@ -48,20 +48,23 @@ bun run db:migrate:remote                # must apply BOTH databases — copy th
 bun run cf-typegen && bun run check
 ```
 
-## Pricing — never leave it at 0
+## Pricing — set it deliberately per env
 
 `src/pricing.ts` `CHECK_PRICE_DENOM` / `CHECK_PRICE_AMOUNT` feed `pricing.evaluation` AND the
-ceiling written on every minted grant. Denom = the app's `NEXT_PUBLIC_ASK_DENOM` (`uixo` on
-devnet, `upay` on testnet/mainnet). At 0 the oracle works for free while the engine bills its
-owner per decision. The picker shows the price from `/v1/info`, and the poster's escrow carries it;
-an ask escrowing less is refused 402 and never judged. Default, unless the provider names one:
-`350_000` base units — 0.35 IXO on devnet, 0.35 PAY ($0.35) on testnet/mainnet, Openhands' own
-check fee (`QI_CHECKER_BASE_UPAY`), which covers the engine's $0.30 per decision.
+ceiling written on every minted grant. Denom = the app's ask denom (`uixo` on devnet, `upay` on
+testnet/mainnet). In a template project the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars in
+`wrangler.jsonc` override `pricing.evaluation` for that env — so set `EVALUATION_DENOM=upay` and
+`EVALUATION_MIN_AMOUNT=<the check price>` in the testnet AND mainnet envs (mainnet will not boot
+without them), or `EVALUATION_MIN_AMOUNT=0` for an oracle IXO bills per review (its collections
+carry an empty evaluation leg). Outside per-review billing, 0 means the oracle works for free while
+the engine bills its owner per decision. The picker shows the price from `/v1/info`, and the
+poster's escrow carries it; an ask escrowing less is refused 402 and never judged. Default, unless
+the provider names one: `350_000` base units — 0.35 IXO on devnet, 0.35 PAY ($0.35) on
+testnet/mainnet, Openhands' own check fee, which covers the engine's $0.30 per decision.
 
 ## Being listed and hired
 
-The app's picker (`packages/openhands-data/src/oracles.ts`, with `NEXT_PUBLIC_CHECKER_ADDRESS`
-UNSET) lists an oracle when its entity has: `#acard` with a **`check-openhands`** service (next to
+The app's picker lists an oracle when its entity has: `#acard` with a **`check-openhands`** service (next to
 `check-measure`, priced in PAY — the app reads the service id, and `check-openhands` is what marks
 the oracle Openhands-compatible); `#orz` granting `ORACLE_ADDRESS`; `#eval` = an https base URL
 whose `/v1/info` answers that address, the ask denom, and `policies.allowAiChecks: true` (else it
@@ -77,10 +80,8 @@ bunx decision-oracle oracle init --protocol <any ask's protocol, or the app's cl
   --kit-url https://<host> --logo https://<host>/logo.svg --openhands --network <n>   # dry run; then --yes
 ```
 
-Hire/scan nudges go to the PICKED oracle's `#eval`; that routing is the `demo/oracle-picker` change
-in openhands-network. The app build has it when `packages/openhands-data/src/oracles.ts` reads the
-`#eval` endpoint and `app/ask/post.ts` passes `checker.endpoint` to `notifyOracle` — and in use,
-when the hire nudge shows up in THIS oracle's logs after a post.
+Hire/scan nudges go to the PICKED oracle's `#eval`; you know the app routes to you when the hire
+nudge shows up in THIS oracle's logs after a post.
 
 Then, right after deploy: `bunx decision-oracle engine register --env <env> --env-file .dev.vars`.
 The Openhands app lists only registered oracles, and otherwise the engine (and the Decision
@@ -105,9 +106,9 @@ Console) learns the oracle only at its first decision.
 | --- | --- |
 | Hire nudge 404 | the adapter's routes are not wrapped in `src/index.ts` `fetch` |
 | Every claim rejected `weather` "unreachable" | `weather` left as a stub; copy `src/facts/weather.ts` (Open-Meteo, no key) |
-| Oracle missing from the picker | no `check-openhands` service on `#acard`, no `#orz`/https `#eval`, not `engine register`ed, price unreadable, or `NEXT_PUBLIC_CHECKER_ADDRESS` set (single-checker mode) |
-| Picker shows the oracle at 0 | `pricing.ts` still 0, or its denom ≠ the ask denom |
+| Oracle missing from the picker | no `check-openhands` service on `#acard`, no `#orz`/https `#eval`, not `engine register`ed, or its price unreadable |
+| Picker shows the oracle at 0 | `pricing.ts` / that env's `EVALUATION_MIN_AMOUNT` still 0 on an oracle not billed per review, or the denom ≠ the ask denom |
 | `withinRadius` fails for everyone | the ask's place was geocoded from a word ("You" → a village in Burkina Faso); set the place by name |
 | Console "Could not read this oracle's prices" | the console reads the Decision API price list; a chain-lane oracle has none (`API_LANE` off) — console-side, not an oracle fault |
-| Wrangler can't resolve `protobufjs/minimal.js` | inside the eval-oracle workspace there is one hoisted protobufjs; drop openhands-oracle's `alias` |
+| Wrangler can't resolve `protobufjs/minimal.js` | inside the eval-oracle workspace there is one hoisted protobufjs; drop any protobufjs `alias` you copied in |
 | `chain.test.ts` fails after a denom change | the "foreign denom" fixtures used your new denom; give them one you are not paid in |

package/skills/create-collection/SKILL.md

@@ -60,11 +60,13 @@ protocol.
      `create-deed` refuses a protocol without one)
    - the deed: an existing domain entity DID that already links the protocol, OR a title (+ optional
      description) for a new one — the title is what the portal's picker shows
-   - evaluation payment: denom + amount. This is the oracle's income per decision AND the minimum
-     that oracle's own `pricing.evaluation` accepts, so confirm the number with whoever owns the
-     oracle rather than guessing
+   - evaluation payment: denom + amount. This is the oracle's income per decision AND must meet the
+     minimum that oracle accepts (its `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT`), so confirm the
+     number with whoever owns the oracle rather than guessing
    - optional admin funding amount (`--fund`) — covers the first evaluation payouts, see the gotcha
    - the oracle address to grant Evaluate; the agent address(es) to grant Submit (comma-separated)
+     — `--submit addr1,addr2` is also how to restrict who may claim, e.g. a payouts collection only
+     two people may submit to
    - quota and window in days if the defaults (100, 90) aren't right — state them explicitly rather
      than silently applying them
 
@@ -94,6 +96,10 @@ protocol.
      [--max-custom-amount 0uixo] [--phase collection|fund|grants|all] [--yes]
    ```
 
+   `--eval-denom` must equal the oracle's `EVALUATION_DENOM` — on mainnet the USDC ibc denom or
+   `upay`, never `uixo`. `--eval-amount 0` writes an EMPTY evaluation leg (the chain refuses a zero
+   coin): that is what a collection for a per-review-billed or 0-minimum oracle registers with.
+
    `--max-custom-amount` is the evaluate grant's `MaxCustomAmount`, written explicitly (`0<eval
    denom>` by default). The chain holds EVERY non-empty evaluation amount to it (its denom must be
    listed), and the oracle sends an ordinary claim's own coins by default — so if the protocol's
@@ -161,6 +167,12 @@ protocol.
 
 7. **Report the run** — the output contract below.
 
+Payout ASKS (a deed or request with its organisation links and `#payoutTerms`) are posted only
+through OpenHands, not with these commands. A company paying people from its OWN collection runs
+its own self-hosted payouts facilitator instead: enable the collection there
+(`/v1/payouts/collections`) with a `fromDecision` rule on `$.<amount field>`, and name the same
+amount field and currency in the oracle's `payouts` config.
+
 ## Output contract
 
 Always end with this block, verbatim, filled in from this run:
@@ -187,7 +199,8 @@ account, a phase that was dry-run but never confirmed, or a delegation nobody ha
 | Creating the collection before the deed links the protocol | run `create-deed --phase claims`; the picker reads `linkedClaim` → claims-config |
 | Granting Evaluate and expecting the oracle to pull claims | it also needs the claim-bot delegation (step 5) |
 | Leaving the admin account unfunded | every evaluation debits it, rejects included — pass `--fund` |
-| Guessing the evaluation amount | it must meet the oracle's `pricing.evaluation.minAmount`, or register 402s |
+| Guessing the evaluation amount | it must meet the oracle's `EVALUATION_MIN_AMOUNT` in its `EVALUATION_DENOM`, or register 402s |
+| `--eval-amount 0` expecting a zero coin | it writes an empty evaluation leg — right only for a per-review-billed or 0-minimum oracle |
 | Running with `--yes` first | dry-run, show the plan, then confirm |
 | Re-running `create-deed --phase claims` for no reason | it rewrites the doc under a new cid and adds a second `linkedClaim` — resume from `claims` only when that phase actually failed |
 

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

@@ -36,7 +36,8 @@ First the portal's gate: `--entity` must not be a protocol, must have a `linkedC
 the protocol, `startDate` = now − 1 day, `endDate` = now + `--days`, `quota`, and four payment legs
 (submission / approval / rejection / evaluation), each `Payment{ account: <deed admin>, amount,
 isOraclePayment: false }` — only `evaluation` carries a nonzero amount (`--eval-amount` /
-`--eval-denom`); the other three legs are empty. `isOraclePayment` is never turned on by this command
+`--eval-denom`); the other three legs are empty. With `--eval-amount 0` all four are empty — the
+chain refuses a zero coin, so `0` means no evaluation payment at all. `isOraclePayment` is never turned on by this command
 on ANY leg: the chain rule is that it is only ever legal on the approval leg, so setting it on
 evaluation would be a protocol violation. After signing, it polls Blocksync for a few seconds waiting
 for the new collection to index before moving on to fund/grants.

package/skills/create-oracle/SKILL.md

@@ -17,6 +17,33 @@ a protocol's rubric declares (`bunx decision-oracle protocol review <did>`); thi
 those names and nothing else. It never parses a rubric, never binds a form, never decides. If the
 manifest is `unusable`, there is nothing to build against yet — stop and say so.
 
+## Which skill do I need?
+
+Run an oracle for a protocol → this skill. Write the code that answers each fact → `write-facts`.
+Write the rules claims are judged by → `create-rubric`. Put a claim form and its rules on chain →
+`publish-protocol`. Open a place for claims to be submitted and hire an oracle on it →
+`create-collection`. Let apps and agents ask the oracle for decisions over HTTP →
+`decision-api-oracle`; test that from the customer's side → `decision-api-client`. Be hireable from
+the Openhands app → `add-openhands-support`.
+
+**Words used throughout:**
+
+- **Oracle** — the service this package is: it gathers the evidence for each claim and asks the
+  engine for a verdict.
+- **Protocol** — a published kind of claim: the form people fill in plus the rules it is judged by.
+- **Rubric** — those rules, written down: what counts as approve, reject or "needs a person".
+- **Claim** — one submission: someone's answers (and files) on a protocol's form.
+- **Collection** — a place on chain where claims for one protocol are submitted and paid for.
+- **Engine** — IXO's decision engine: it reads the facts your oracle sends and gives the verdict.
+- **Decision / receipt** — the engine's verdict, and its signed proof that it gave it; the oracle
+  records both and puts the proof on chain.
+- **PAY / `upay`** — IXO's US-dollar token (1 PAY = 1 USD); `upay` is its smallest unit, a
+  millionth of a PAY.
+- **did:web** — this oracle's web identity, a name tied to its domain; other services check its
+  signatures by fetching `https://<host>/.well-known/did.json`.
+- **Delegation** — a signed permission one party gives another, such as the owner letting the engine
+  bill their subscription, or letting the oracle read their claims.
+
 ## When to use
 
 - "Build / set up / configure an oracle for protocol X", "what would my oracle need to produce"
@@ -86,11 +113,18 @@ and any `ERROR: this source will not be called` (the audience is not the endpoin
 the name shows as `refused: fix the rubric`, the command exits 1, and only the protocol owner can fix
 it; no handler stands in). Then fill in `src/index.ts` with the provider's answers (the interview
 table below):
-`supportedProtocols: ["<protocol did>"]`, `pricing.evaluation` (denom + `minAmount` in integer base
-units — the on-chain evaluation payment a collection must carry, or register refuses it; optionally
-`pricing.byProtocol` to charge a different fee per protocol DID — `minAmount: "0"` accepts a
-collection whose evaluation leg is empty, for a protocol whose income isn't the evaluation split),
-and `policies`: `allowAiChecks` true iff anything asks for a model (an `ai` check, or a `unique` rule
+`supportedProtocols: ["<protocol did>"]`, the evaluation fee, and `policies`.
+
+The fee is the on-chain evaluation payment a collection must carry, or register refuses it. Set it
+per wrangler env with the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars (both or neither; the
+minimum in integer base units) — they replace `pricing.evaluation` from `defineOracle`, and they
+are REQUIRED on mainnet: the worker refuses to start without them. A third-party oracle typically
+charges Noble USDC (`ibc/6BBE9BD4246F8E04948D5A4EEE7164B2630263B9EBB5E7DC5F0A46C62A2FF97B`); an
+IXO-managed oracle billed per review uses `upay` / `0`, which accepts a collection whose evaluation
+leg is empty. `pricing.byProtocol` still wins for the protocols it names. The effective price is
+what `GET /v1/info` shows as `pricing`.
+
+The `policies`: `allowAiChecks` true iff anything asks for a model (an `ai` check, or a `unique` rule
 with its judge on), `allowImageChecks` true iff a check reads a photo and the provider wants C2PA
 screening, `autoSign` true only when unattended chain writes are deliberate (the `AUTO_SIGN` var
 gates it too — both must be on), and `allowStandingApprovals` — REQUIRED, no default: `true` lets a
@@ -158,6 +192,10 @@ printf 'OWNER_DELEGATION_CAR="%s"\n' "$(cat owner-delegation.car)" >> .dev.vars
   before it lapses.
 - Only the human can do the login. Run it in the background so the loopback callback lands, and tell
   them to finish in the browser.
+- **The owner must hold an IXO subscription before `engine register`**, or it answers 402
+  `NO_SUBSCRIPTION`. A subscription created by the subscriptions workflow (not the portal) also
+  needs a Stripe customer: the owner calls the subscriptions API's `POST /api/v1/payments/intent`
+  once (a SetupIntent — nothing is charged).
 - **A 402 at register is the owner's credits, not a bug**: `NO_SUBSCRIPTION` (none at all) or
   `INSUFFICIENT_CREDITS` (below one decision's price, carrying `manageSubscriptionUrl`). Send the
   owner to that portal URL to buy credits, then register again — nothing here can fake it.
@@ -183,10 +221,11 @@ finds this oracle. One command does all of it:
 
 ```bash
 bunx decision-oracle oracle init --protocol <protocol did> --kit-url http://localhost:8787 \
-  [--logo <url>] [--only <step>] [--relogin] [--network <n>] [--yes]
+  [--logo <url>] [--openhands [--price-pay <n>]] [--only <step>] [--relogin] \
+  [--network <n>] [--yes]
 ```
 
-**A full on-chain identity is mandatory** (owner, 2026-10-01): every oracle built with this kit gets
+**A full on-chain identity is mandatory**: every oracle built with this kit gets
 its entity, its `#pro` profile, its `#dmn` domain card and its `#acard` Agent Card — this command
 does all four. `--logo <url>` is optional, but ASK the provider for one: without it the portal and
 the console show a placeholder, and every run prints `⚠ recommended: --logo`.
@@ -260,7 +299,8 @@ where a live token would have skipped (it mints a new Matrix device — not a ca
 ### 9. Deploy it
 
 ```bash
-bun run db:migrate:remote        # BEFORE the first deploy of that environment
+bun run db:migrate:remote        # BEFORE the first deploy of the default env; for a named env:
+                                 #   bunx wrangler d1 migrations apply DB --remote --env <env>
 bun run deploy                   # or deploy:testnet / deploy:production
 wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN     # the value step 8 wrote into .dev.vars
 ```
@@ -308,18 +348,20 @@ bunx decision-oracle register --collection <collection id> [--delegation delegat
 bunx decision-oracle scan --collection <collection id>     # discover claims now, not at the next tick
 ```
 
-`--delegation` is the owner→oracle claim-bot CAR (`delegation --for bot --audience
-did:ixo:<ORACLE_ADDRESS>`): without it the oracle holds the on-chain grant but still cannot pull
-claim bodies from Matrix. A refusal names its gate — not the chain owner, no Evaluate grant for
-`ORACLE_ADDRESS`, or an evaluation payment below the required fee (`pricing.byProtocol` for that
-collection's protocol, else `pricing.evaluation.minAmount`).
+Claim bodies are pulled from the VFS claims lane first (under the oracle's own Evaluate grant), then
+the Matrix claim bot, then the IPFS gateway or a declared cellnode. `--delegation` is the
+owner→oracle claim-bot CAR (`delegation --for bot --audience did:ixo:<ORACLE_ADDRESS>`); it matters
+only for claims stored in Matrix — without it those bodies cannot be pulled. A refusal names its
+gate — not the chain owner, no Evaluate grant for `ORACLE_ADDRESS`, or an evaluation payment below
+the required fee (`pricing.byProtocol` for that collection's protocol, else the env's
+`EVALUATION_MIN_AMOUNT`).
 
 ## Interview slots (ask, don't assume)
 
 | Slot | Ask | Lands in |
 | --- | --- | --- |
 | Protocol | the DID, and which network | `--protocol`, `supportedProtocols` |
-| Pricing | denom + minimum per-evaluation payment; any protocol priced differently (incl. free)? | `pricing.evaluation`, optionally `pricing.byProtocol` |
+| Pricing | denom + minimum per-evaluation payment per network; any protocol priced differently (incl. free)? | `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` per env, optionally `pricing.byProtocol` |
 | AI / image policy | does the work order declare `ai` checks; do any read images | `policies.allowAiChecks` / `allowImageChecks` |
 | Auto-sign | should this oracle sign `MsgEvaluateClaim` unattended | `policies.autoSign` + the `AUTO_SIGN` var |
 | Standing approvals | may a signed-in AI app's own auto-approve limits pay without a per-claim approval (hosted MCP) — IXO's own oracles say yes | `policies.allowStandingApprovals` (required) |
@@ -352,7 +394,8 @@ collection's protocol, else `pricing.evaluation.minAmount`).
 | Register answers 402 and the agent retries | it is the owner's credits — send them to the printed portal URL, then re-run |
 | `.dev.vars` edited but the old value still in play | a running `wrangler dev` reloads source, not secrets — restart it |
 | `ORACLE_ADDRESS` typed by hand | must match the mnemonic exactly — asserted at first use |
-| Guessing `pricing.evaluation.minAmount` | ask what the collection's on-chain evaluation payment is (or will be) — too low and register 402s |
+| Guessing `EVALUATION_MIN_AMOUNT` | ask what the collection's on-chain evaluation payment is (or will be) — set too high and register 402s |
+| No `EVALUATION_DENOM` in the mainnet env | the worker refuses to start — set both vars in every env you deploy |
 | `allowAiChecks: false` while the work order declares AI checks | every `ai` fact freezes `error` and the rubric's `onError` decides — ask first |
 | `ORACLE_HOSTNAME` ≠ the deployed Custom Domain | callers resolve the did:web by fetching that host — they must be the same string |
 | `ORACLE_ENTITY_DID` left unset after `oracle init` (or set only at the top level) | the deployed oracle fails `/health/ready` (`identity`); the Matrix review card can't resolve it, so reviews only work from the portal page |
@@ -360,7 +403,7 @@ collection's protocol, else `pricing.evaluation.minAmount`).
 | Skipping `--logo` without asking | the identity is still complete, but the portal and the console show a placeholder — ask the provider for a logo URL and pass `--logo` |
 | Not re-running `oracle init` after the deploy | `#eval` and both cards still name `localhost` and `#pro` may be missing — re-run with the deployed `--kit-url` and `--yes` |
 | Treating `⚠ domain indexer …` as a failure | it is a warning and the exit code is 0 — the entity is on chain either way |
-| Registering with the on-chain grant but no claim-bot delegation | the oracle can't pull bodies — mint `delegation --for bot` and pass `--delegation` |
+| Registering with the on-chain grant but no claim-bot delegation | Matrix-stored claims can't be pulled — mint `delegation --for bot` and pass `--delegation` |
 
 ## Worked example
 
@@ -389,6 +432,8 @@ restart, re-register. Restart both dev servers after any `.dev.vars` edit.
   default and cap; the routes, cron lanes, pause reasons and billing the package already owns).
 - `../reference/engine-contract.md` — the engine's side: register, the error table, billing,
   receipts, review folds. Background, not an interface.
+- `../reference/linked-docs.md` — the linked-document rules: Vault first, the IXO IPFS gateway as
+  the fallback, each proof's format, and `readLinkedDoc`.
 
 ## Output contract
 

package/skills/create-rubric/SKILL.md

@@ -93,8 +93,9 @@ default here is the author's call — ask.
 
 ## Rules that bite (the engine's, not opinions)
 
-- `claimSchema.proof` is the chain's `#vct` proof copied verbatim (a CID, compared as a string) —
-  never computed.
+- `claimSchema.proof` is the chain's `#vct` proof copied verbatim, compared as a string — sha256 hex
+  for a protocol published with the CLI, a CID for one published through the Portal. Never
+  computed.
 - File content is never machine-judged: presence / type / size only. "Does the photo show X" is
   `ManualScore` + `ReviewTask`, `answer` boolean or enum, `map` covering every answer — or an
   `aiChecks` entry, which an oracle answers.

package/skills/create-rubric/reference/format-cheatsheet.md

@@ -16,7 +16,7 @@ format still shows `constants` / `@const` refs; those do not exist (inline liter
     "@type": "Rubric",
     "title": "…", "description": "…",                        // display-only
     "claimSchema": { "@type": "ClaimSchemaBinding", "protocol": "did:ixo:entity:…", "resource": "#vct",
-                     "proof": "<the protocol's #vct LinkedResource proof, VERBATIM — a CID, compared as a string>" },
+                     "proof": "<the protocol's #vct LinkedResource proof, VERBATIM — sha256 hex (CLI) or a CID (Portal), compared as a string>" },
     "derived":   [ … ],   "gates": [ … ],   "scoring": { … },   "review": { … },   "settlement": { … },
     "sources":   [ … ],   "aiChecks": [ … ],   "unique": { … },   "frequency": { … }
   }