@ixo/decision-oracle 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,111 @@
+# Creating a collection — reference
+
+`reference/claims-stack.md` is the model (protocol → deed → collection); this file is the
+message-level detail of `bunx decision-oracle create-deed` and `bunx decision-oracle create-collection`.
+
+## `create-deed` phases
+
+### `entity`
+
+`MsgCreateEntity` of `--type` (default `deed`), owner/controller = the AuthHub session's DID, relayer
+node from the network map — the same builder `publish-protocol` uses for a protocol. The new DID is
+read from the tx events; if that fails, the tx still landed and the DID must be found by hand (a
+Blocksync `entities` query filtered by owner) before resuming with `--entity`.
+
+### `room`
+
+The rooms bot sources the room, the session's Matrix user joins, the claim bot is invited, then the
+state bot is invited through the state-bot client (which also sets its power level). Both invites run
+as the session's Matrix user. Idempotent: re-running on an existing room just re-invites.
+
+### `claims`
+
+Builds the claims-config doc, computes its CID (CIDv1, raw codec, sha256), and — with the session's
+UCAN only, no Matrix token — writes it into room state at key `claims`, path `<cid>`, then sets the
+public ACL. Then ONE tx: `MsgAddLinkedClaim` (`{id}#claims`, `matrix:<cid>`, proof `<cid>`) +
+`MsgAddService` (`{id}#matrix`). Re-running rewrites the doc under a new cid (its `createdAt`
+changes) and adds a second `linkedClaim` — harmless to the picker (it dedupes by protocol) but avoid
+it; resume from `claims` only when that phase actually failed.
+
+## `create-collection` phases
+
+### `collection`
+
+First the portal's gate: `--entity` must not be a protocol, must have a `linkedClaim`, and its
+`matrix:` docs must name `--protocol`. Then `MsgCreateCollection`: `entity` = the deed, `protocol` =
+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
+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.
+
+### `fund`
+
+A plain `MsgSend` from the signer to the DEED's admin account. Skipped — not defaulted to zero — when
+`--fund` is omitted; it says so rather than silently sending nothing.
+
+### `grants`
+
+One `MsgGrantEntityAccountAuthz` per address in `--evaluate` / `--submit`, `id` = the deed, granter =
+the deed's `admin` account (looked up from Blocksync's `entity.accounts`, NOT the signer's address),
+365-day expiration. Grant body: `EvaluateClaimAuthorization{ admin, constraints: [{ collectionId,
+claimIds: [], agentQuota, beforeDate: <expiry>, maxCustomAmount: [<--max-custom-amount>] }] }`
+(mirrored for `SubmitClaimAuthorization`, which has no amount). `MaxCustomAmount` is written
+explicitly — `0<--eval-denom>` unless the owner passes `--max-custom-amount <amount><denom>`. The
+chain checks EVERY non-empty evaluation amount against it (x/claims `IsCoinsInMaxConstraints`; the
+denom must be listed), and the act lane sends an ordinary claim's own coins by default, so claims
+that carry coins need a cap ≥ the largest claim amount in each denom — at `0` their approvals fail
+at MsgExec. It is also the owner's cap on any amount an evaluator sets (company authority D7); the
+oracle side's own switch is the owner's `operatorAmounts` (`PATCH /v1/collections/:id/settings`),
+honoured only while the owner who set it still owns the collection. All grant messages for one run
+broadcast as ONE tx. No addresses given ⇒
+it says nothing was granted and returns cleanly, no tx signed.
+
+## Resuming
+
+There is no `--collection` flag — every phase resolves the collection FROM the (`--entity`,
+`--protocol`) pair via Blocksync (one protocol backs many deeds, so `protocol` alone is not an
+identity). Re-running `--phase all` on a deed that already holds a collection for the protocol logs
+that it exists and proceeds to fund/grants. There is no risk of creating a second collection for the
+same pair by re-running.
+
+## The admin-funding gotcha, in full
+
+The collection's `admin` account (an entity-module sub-account of the DEED, NOT the wallet that signs
+these commands) is what `MsgEvaluateClaim` actually debits for every evaluation payment. It starts at
+zero balance. And it pays on EVERY evaluation, not only approvals — a reject debits the same amount.
+On the same message it also pays the approval payment of an ordinary approve (the claim's own coins,
+else the collection's approval default; an intent claim's comes from escrow) or the rejection
+payment of a reject, and chain v8 fails the whole message unless the account covers every leg.
+If nothing funds it — no `--fund`, no other transfer — the FIRST `MsgEvaluateClaim` an oracle submits
+against this collection fails with `payment withdrawal failed`, not a clean 403: the collection,
+grants and delegation all look correct, decisions get made, but the payout write on chain fails.
+
+The oracle treats that failure as what it is — deterministic, not a blip. It parks the decision
+`chainStatus: blocked` (no retries) and pauses the collection `pausedReason: admin-unfunded`; the
+owner is told once, through the same channel as every other pause (a Matrix notice in the
+collection's review room plus an email to `contactEmail`), and the notice names the admin account,
+the full amount the failed claim needs (evaluation + its verdict's payment, per denom) and its
+balance. Scanning stops, so the engine stops billing the owner's credits for decisions that could
+not be paid out. Once the account is topped up, the oracle's funding cron sees the balance cover the
+largest single parked delivery, resumes the collection, sends the paired "resumed" notice and
+re-delivers the parked decisions — within a minute, nothing to re-run.
+
+Fund by EVALUATIONS plus the approval payouts the admin pays: enough to cover the volume you
+expect before the next top-up. Nothing here
+schedules recurring funding, and the admin's balance is not one of the columns `create-collection`
+reports at the end — check it separately (Blocksync, or a bank-balance query) before the oracle does
+it for you.
+
+## The delegation's identity
+
+`bunx decision-oracle delegation` reads no env file at all: the owner is whoever is logged in
+(`bunx decision-oracle login`), the same AuthHub session `create-collection` used — the deed owner is
+also the collection's funder in most flows. It signs with the session's own signing mnemonic (no
+Matrix-vault PIN). The default (`--for bot`) resource is always the Matrix claims bot, and `--days`
+(default 30) sets that delegation's expiry, independent of the grants' 365-day expiration — renew it
+on its own schedule. `--for engine` is a different delegation entirely: the oracle OWNER's billing
+delegation to the decision engine (`create-oracle` step 6), 100 years by default — nothing renews
+that one.

package/skills/create-oracle/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: create-oracle
+description: Use when someone wants to run an evaluation oracle for an IXO protocol or collection — "build an oracle for protocol X", "what would my oracle need to produce", onboarding a provider onto a protocol, or setting up / deploying a project built on @ixo/decision-oracle (init, identity, register, oracle init, get hired).
+---
+
+# Building an oracle for a protocol
+
+## Overview
+
+`@ixo/decision-oracle` is the whole oracle except the facts: it pulls each new claim from the collections
+this oracle was hired for, produces the facts the rubric asks for, sends them to the IXO **decision
+engine**, and signs the verdict on chain. A provider writes `src/facts/*.ts` — one function per named
+fact — plus a few config values. This skill is the runbook from an empty directory to a hired oracle.
+
+**Core principle: the manifest is the work order — never the rubric doc.** The engine publishes what
+a protocol's rubric declares (`bunx decision-oracle protocol review <did>`); this oracle produces exactly
+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.
+
+## When to use
+
+- "Build / set up / configure an oracle for protocol X", "what would my oracle need to produce"
+- Onboarding a provider onto a protocol whose rubric is already anchored (`#rub`)
+- Deploying, declaring on chain, or getting an existing oracle hired
+
+Not for: authoring the rubric (`create-rubric` — its anchored `#rub` is this skill's input), or the
+handlers themselves (`write-facts`, handed off to at step 3).
+
+## The pipeline — every step, in order
+
+### 0. The project
+
+```bash
+bunx @ixo/decision-oracle init <dir> [--name <project-name>]
+cd <dir> && bun install
+bun run cf-typegen                       # after ANY wrangler.jsonc binding/var change, too
+wrangler d1 create <project-name>        # paste the id into wrangler.jsonc
+wrangler kv namespace create CACHE_KV    # paste the id into wrangler.jsonc
+bun run db:migrate                       # the package's own migrations, applied to the local D1
+cp .dev.vars.example .dev.vars           # git-ignored; secrets only
+```
+
+Three files are the provider's: `src/index.ts` (what the oracle IS), `src/facts/index.ts` (how it
+answers), `wrangler.jsonc` (where it runs).
+
+### 1. Identity — two keys
+
+```bash
+bunx decision-oracle derive --new     # run TWICE
+```
+
+- Run one: take the mnemonic line and paste it into `.dev.vars` **relabelled** as
+  `SERVICE_ED25519_MNEMONIC=` — `derive` always prints it as `ORACLE_SECP_MNEMONIC=`, so a verbatim
+  paste silently sets the wrong key. This is the did:web key that signs every UCAN invocation this
+  oracle mints and backs `/.well-known/did.json`; ignore the `ORACLE_*` lines this run prints.
+- Run two: the mnemonic is `ORACLE_SECP_MNEMONIC` (the chain wallet that signs `MsgEvaluateClaim`);
+  the same run prints `ORACLE_ADDRESS`, `ORACLE_DID` and `ORACLE_MATRIX_USER_ID` — those three are
+  **public vars**, so they go in `wrangler.jsonc` `vars`, not `.dev.vars`.
+
+Also set `ORACLE_HOSTNAME` (the host the did:web is served from — `localhost:8787` locally, and it
+must equal the Custom Domain in `routes` for any env you deploy), `IXO_NETWORK`, and
+`UNIQUE_HMAC_KEY` in `.dev.vars` (any long random string; rotating it orphans every registered
+duplicate digest). `derive "<existing mnemonic>"` uses a wallet the provider already holds instead of
+minting one. `ORACLE_ADDRESS` is asserted against the mnemonic before the first proof or signature:
+a hand-typed one that differs fails loud, never signs as someone else.
+
+Both keys are only strings in files at this point: funding the wallet, the on-chain IID document and
+Ed25519 verification method, and the Matrix account behind `ORACLE_MATRIX_ACCESS_TOKEN` are all
+step 8's job. Never ask the provider to obtain that token — `oracle init` writes it.
+
+### 2. The work order
+
+```bash
+bunx decision-oracle protocol review <protocol did> [--network devnet|testnet|mainnet] [--json]
+```
+
+Present it in plain words: the claim-form **fields** the product submits, the `ctx`/`derived` values
+the rules read, then the work order itself — each `ext` source (name, endpoint, `send`,
+`boolean`/`score`, `onError`), each `ai` check (name, instructions, `send`, `onError`), and the
+`unique`/`frequency` rules (stock lanes cover those — no code). It also says which names need a
+handler. Per `ext` source it prints what the oracle will sign and to whom (`calls POST <endpoint> —
+UCAN from this oracle's did:web to <audience>, capability ixo:external-source`): relay any
+`WARNING` (the rubric declares a `capability` — ignored, the oracle's developer owns what its key
+signs; a handler that needs one sets it in code via `tools.http.json(url, { ucan: { capability } })`)
+and any `ERROR: this source will not be called` (the audience is not the endpoint's own did:web —
+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
+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
+signed-in AI app's own auto-approve limits (the hosted MCP's "Don't ask again") pay for a submit
+without a per-claim approval; `false` means every such submit waits for the user's approval of that
+claim. IXO's own oracles turn it on; anyone else decides it explicitly — ask.
+
+### 3. The handlers → the `write-facts` skill
+
+```bash
+bunx decision-oracle facts scaffold <protocol did> [--all] [--dir src/facts]
+```
+
+One `src/facts/<name>.ts` per name that needs a handler — each stubbed as
+`fact.error("not implemented: <name>")` — plus a test beside it; nothing existing is overwritten, and
+you list each export in `src/facts/index.ts`. **Hand off to `write-facts` here** — it has the
+input/tools cheat sheet, the stock-vs-custom table and two worked handlers. Come back when
+`bun run check` is green.
+
+### 4. Test the handlers
+
+```bash
+bun run test        # plain vitest in node: the real runner, fake tools, no Worker and no network
+```
+
+A handler with only a happy-path test is not tested — cover the failure it will meet.
+
+### 5. Run them against a claim
+
+```bash
+bunx decision-oracle facts run --protocol <protocol did> --claim <answers file> \
+  [--collection <id>] [--preview] [--facts src/facts/index.ts] [--json]
+```
+
+`--claim` takes either a flat answers object (the same file `submit-claim --answers` posts) or the
+`{ answers, attachments?: [...] }` envelope when a handler needs files. It prints the facts your
+table produced plus any validation issue (exit 1 if there are issues); `--preview` sends them to the
+engine's preview lane and prints the decision they would produce — nothing persisted, nothing billed,
+no grant needed. This is the first end-to-end proof.
+
+A flat answers file has no attachments, so any fact that reads one fails closed: in the passport
+example the AI check freezes as an `error` (its guard's path) rather than reaching the stock judge.
+Exercising that lane needs a claim file with an `attachments` entry pointing at a local photo.
+
+### 6. The owner's delegation (engine billing)
+
+The engine bills the oracle OWNER's credits, so the owner — whoever holds the IXO subscription —
+mints a delegation to the engine before register will work. **Do this step, don't just quote it.**
+
+```bash
+bunx decision-oracle login --network <devnet|testnet|mainnet>     # once per network; a browser login
+bunx decision-oracle delegation --for engine \
+  --audience did:web:<engine host> --oracle did:web:<ORACLE_HOSTNAME> \
+  --out owner-delegation.car [--days 36500] [--network <n>] --yes
+printf 'OWNER_DELEGATION_CAR="%s"\n' "$(cat owner-delegation.car)" >> .dev.vars
+```
+
+- The engine host is the one this oracle is configured against: the per-network default
+  (`decision-engine.<network>.ixo.earth`) unless `EVAL_ENGINE_HOSTNAME` overrides it. A `:` in a host
+  is `%3A` inside a did:web.
+- **Never print the CAR** — it is a bearer credential. Deployed:
+  `wrangler secret put OWNER_DELEGATION_CAR < owner-delegation.car`. **Restart `wrangler dev` after
+  editing `.dev.vars`** — a running one reloads source, not secrets. The CAR's lifetime is 100 years
+  by default, because nothing renews it; if you shorten it with `--days`, re-mint AND re-register
+  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.
+- **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.
+
+### 7. Run it locally — and leave it running
+
+```bash
+bun run dev                                            # local D1 under .wrangler/state, cron fireable:
+curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"
+```
+
+`GET /v1/info` is the public listing, `GET /.well-known/did.json` the identity. Step 8 reads that
+`/v1/info` for the oracle's on-chain profile, so keep this server up while you run it.
+
+### 8. Provision the oracle on chain
+
+Everything `derive` produced is, so far, only strings in the provider's files. On chain the wallet is
+**unfunded** (it cannot pay for a `MsgEvaluateClaim`), `did:ixo:<ORACLE_ADDRESS>` has **no IID
+document and no Ed25519 verification method** (so the claim bot and the UCAN Store refuse every
+invocation minted as it), there is **no Matrix account** (so `ORACLE_MATRIX_ACCESS_TOKEN` has no
+producer and the review-card lane no-ops), and **no oracle entity**, so nobody browsing the protocol
+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]
+```
+
+**A full on-chain identity is mandatory** (owner, 2026-10-01): 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`.
+
+Thirteen steps, always in this order. Each reads live state and prints one aligned line — `do` or
+`skip` plus the reason. A dry run over a half-provisioned oracle looks like this:
+
+```
+entity  : <entity did> (#orz grants <ORACLE_ADDRESS>)
+
+  fund      skip  <ORACLE_ADDRESS> holds 5000000uixo (≥ 1000000uixo)
+  iid       skip  did:ixo:<ORACLE_ADDRESS> already has an IID document
+  key       skip  <did>#<key> is already a verification method
+  matrix    skip  .dev.vars holds a live token for <mxid>
+  entity    skip  <entity did> is this oracle's (#orz grants <ORACLE_ADDRESS>)
+  orz       skip  #orz already on <entity did>
+  profile   do    #pro Settings → "<name>" from https://<host>/v1/info
+  domain    do    add #dmn domainCard "<name>" (no --logo: the portal and the console show a placeholder — pass --logo <url>)
+  acard     do    add #acard agentCard "<name>" (services: claim-evaluation)
+  linked    skip  edge → <protocol did> already on <entity did>
+  service   do    re-point #eval: https://old.example.com → https://<host>
+  backlink  skip  edge → <entity did> already on <protocol did>
+  index     do    POST https://domain-indexer.devnet.ixo.earth/index { did: <entity did> } — no #dmn anchored yet
+
+  DRY RUN — nothing signed, created or written. Re-run with --yes to execute.
+```
+
+On a fresh oracle every line is a `do` instead — `entity`, for one, reads
+`MsgCreateEntity (oracle) owned by <session did>, carrying #matrix, #eval and the protocol edge —
+none of this session's oracle entities is bound to this oracle (#orz granting <ORACLE_ADDRESS>, or
+#eval at <kit-url>); if you created one moments ago, wait for the indexer before --yes or a second
+entity is minted`.
+
+**The entity is found by THIS oracle, never by its owner** — one AuthHub session may own several
+oracles' entities. `ORACLE_ENTITY_DID`, when set, pins it (checked to be an oracle entity the session
+owns); otherwise it is the session's oracle entity whose `#orz` grants `ORACLE_ADDRESS`, else whose
+`#eval` is `--kit-url`. Two matches stop the run — set `ORACLE_ENTITY_DID` and re-run.
+
+| Step | Signer | What it does |
+| --- | --- | --- |
+| `fund` | the AuthHub session | tops `ORACLE_ADDRESS` up to 1 IXO (`1000000uixo`) — the gas for every verdict it signs. A **floor check**, not a once-only step: a later run finds the balance below 1 IXO and sends another full top-up |
+| `iid` | the **oracle's own** wallet | `MsgCreateIidDocument` for `did:ixo:<ORACLE_ADDRESS>` + a `#matrix` service |
+| `key` | the oracle's own wallet | `MsgAddVerification` putting the `SERVICE_ED25519_MNEMONIC` public key on it — what makes the claim-bot and UCAN-Store lanes resolve and verify this oracle |
+| `matrix` | the oracle's own wallet (it signs the rooms bot's challenge) | creates the Matrix account if absent, logs in, **writes `ORACLE_MATRIX_ACCESS_TOKEN` into `.dev.vars`** (never printed) |
+| `entity` | the session | `MsgCreateEntity (oracle)` owned by the session DID, carrying `#matrix`, `#eval` and the protocol edge in one tx; its DID is written into `.dev.vars` as `ORACLE_ENTITY_DID` at once, so a re-run never mints a second |
+| `orz` | the session | `#orz` `oracleAuthZConfig` — the portal's entity → `ORACLE_ADDRESS` bridge |
+| `profile` | the session | `#pro` `Settings`, built from the running oracle's `GET <kit-url>/v1/info` (+ `--logo`); add-only, except a differing `--logo` replaces it as a merge (the portal's avatar) |
+| `domain` | the session | `#dmn` `domainCard` — the portal's `ixo:DomainCard` credential (name, description, `url` = kit URL, logo only with `--logo`); added, or deleted + re-added in ONE tx — merged onto the live card, the provider's own fields kept — when a field the kit owns drifted or the proof is not the CID of its bytes; an unreadable card is left alone with a `⚠` |
+| `acard` | the session | `#acard` `agentCard` — an `ixo:AgentCard` credential (`claim-evaluation` when the kit publishes evaluation pricing, `decision-api` when its Decision API publishes a price for `--protocol` — at the oracle's effective prices), validated against the engine's schema first; same skip/replace rule. To be listed in the Openhands app pass `--openhands`: it adds a `check-openhands` service priced in PAY (`/v1/info`'s `pricing.api`, else `--price-pay <n>`); the oracle must also be `engine register`ed (`add-openhands-support`) |
+| `linked` / `backlink` | the session | the oracle → protocol edge, and the protocol's edge back (the marketplace filter) |
+| `service` | the session | `#eval` → `--kit-url`; a different endpoint is deleted and re-added in ONE tx |
+| `index` | — | tells the domain indexer the entity exists — after `domain`, so it reads the card; on `--yes` only, skipped when the indexer serves the anchored `#dmn` with `status: completed` (a dry run asks it nothing) |
+
+**The contract: dry-run, read the plan out loud, then — on the provider's OK — re-run the identical line with `--yes`.**
+Without `--yes` nothing is signed, created or written — the planners only read — so the plan shown is
+exactly the plan that executes. Every step is idempotent against live chain / homeserver / entity
+state, never against a marker the command wrote, so a re-run after a partial failure or a redeploy is
+always safe.
+
+**Then 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) — and restart / redeploy. Required, not
+optional: a deployed oracle without it fails `/health/ready` (the `identity` check), and its reviews
+can only be answered from the portal's claim page, not from a Matrix card.
+The entity is owned by whoever logged in via AuthHub, while `ORACLE_ADDRESS` / `ORACLE_DID` stay this
+oracle's runtime identity — what signs `MsgEvaluateClaim` and what a commissioner's grant must name.
+Keep `supportedProtocols` in step with what you declared; nothing reconciles that drift for you.
+
+`--only <step>` runs exactly one step when a run got stuck; `--relogin` forces a fresh Matrix login
+where a live token would have skipped (it mints a new Matrix device — not a casual flag).
+
+### 9. Deploy it
+
+```bash
+bun run db:migrate:remote        # BEFORE the first deploy of that environment
+bun run deploy                   # or deploy:testnet / deploy:production
+wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN     # the value step 8 wrote into .dev.vars
+```
+
+Before deploying: the D1/KV ids for that env are real, the Custom Domain equals that env's
+`ORACLE_HOSTNAME`, and every secret is set with `wrangler secret put`. **Then run step 8 again with
+`--kit-url https://<the deployed host>` and `--yes`**: the `service` step re-points `#eval` at the
+real host and `profile` anchors the `#pro` it had to skip. `fund` may act again too — it is a floor
+check, so a wallet the first run's own `iid`/`key` transactions left below 1 IXO is topped back
+up with another full 1 IXO. The rest say `skip`.
+
+**Done only when readiness passes:**
+
+```bash
+curl -s https://<host>/v1/info | jq .entityDid     # the ORACLE_ENTITY_DID you pinned — never null
+curl -s https://<host>/health/ready                # {"ok":true}
+```
+
+A `503` names nothing; `GET /v1/admin/status` (a UCAN from a DID in `ORACLE_ADMIN_DIDS`) shows the
+failed check — `identity` means `ORACLE_ENTITY_DID` is missing from that env's `vars`.
+
+**Then register with the engine — do it now, don't wait for the first claim:**
+
+```bash
+bunx decision-oracle engine register --env <env> --env-file .dev.vars
+```
+
+The chain lane proves its address lazily, on its first `decide`; until then the engine — and the
+Decision Console, which lists the engine's `GET /v1/oracles` — does not know this oracle exists.
+`billing: ok` is done; a 402 is the owner's credits (step 6).
+
+### 10. Get hired
+
+Hired from the Openhands app (asks, the Yoma youth world) rather than a portal collection? That is
+the `add-openhands-support` skill — the hire/scan adapter, the bridge's fact names, the picker's
+card fields.
+
+A real commissioner grants `ORACLE_ADDRESS` the Evaluate role on their collection and registers it
+(the portal makes that call). To prove the loop yourself, hire yourself with the `create-collection`
+skill — same AuthHub session — then:
+
+```bash
+bunx decision-oracle register --collection <collection id> [--delegation delegation.car] \
+  [--contact-email <addr>] [--kit <url>]
+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`).
+
+## 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` |
+| 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) |
+| Custom lanes | per judgment-call name: do you control the endpoint / is a stock AI check the right judge | the `src/facts/` table (`write-facts`) |
+| Identity | a fresh wallet, or an existing mnemonic to derive from | `derive`, `.dev.vars` + `wrangler.jsonc` vars |
+| Owner | who owns this oracle — the AuthHub login whose subscription pays the engine | `login`, `delegation --for engine` |
+| Funding | nothing to ask — `oracle init` keeps the wallet topped up to 1 IXO for gas | `oracle init` (the `fund` step) |
+| Hosts | the did:web host per env (it IS the identity) | `ORACLE_HOSTNAME`, `routes` |
+| Contact | the address that gets pause / review notices | `register --contact-email` |
+
+## Safety rules
+
+- **Never invent a fact value.** A stub is a visible `fact.error("not implemented: <name>")`, never a
+  fake pass — a wrong value that passes shape validation is worse than a loud failure the rubric
+  routes itself. And **the oracle never decides**: no thresholds, no gates, no rubric parsing in `src/`.
+- **No secrets in code or commits.** Identities come from `derive` into `.dev.vars` /
+  `wrangler secret put`; the delegation CAR is written to a file and never printed.
+- **Chain writes are real.** `oracle init` and everything under `create-collection` sign real
+  transactions and spend gas — and `oracle init`'s `fund` step moves the owner's own IXO into the
+  oracle's wallet: dry-run first, show the plan, only then `--yes`. `--network` defaults to devnet —
+  testnet and mainnet are always explicit.
+- **`bun run check` (typecheck + lint + test) stays green** after any `src/` edit.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Reading `rubric.json` to work out what to produce | read the manifest — `protocol review` / `manifest <did>` |
+| A stub that returns a fake `ok` so a run looks green | `fact.error("not implemented: <name>")` |
+| Register answers 402 and the agent retries | it is the owner's credits — send them to the printed portal URL, then re-run |
+| `.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 |
+| `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 |
+| Running `oracle init --yes` with nothing serving `--kit-url` | `profile`, `domain` and `acard` skip (all three are built from the live `GET /v1/info`) — start `bun run dev`, or deploy, before the run that should anchor them |
+| 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` |
+
+## Worked example
+
+`examples/passport-delivery` in this package's repo is a generated project, filled in: `protocol/`
+holds the claim form and rubric, `src/facts/handoverPhotoLooksReal.ts` answers the one AI check that
+rubric declares (a guard for a claim with no photo, otherwise the stock judge), `test/facts/` runs it
+under `runFacts`, and `supportedProtocols` is `[]`. It is the shape steps 2–5 produce.
+
+## Appendix — a local engine (engine developers only)
+
+A provider never needs this. With the decision engine running on your own machine:
+`EVAL_ENGINE_HOSTNAME=localhost:8787` in this oracle's `.dev.vars`, this oracle on another port (its
+`ORACLE_HOSTNAME` says which), and decisions work over plain localhost. **Register does not**: the
+hosted subscriptions API resolves the ENGINE's did:web when it presents the owner delegation, so that
+leg needs a public tunnel to the engine — its host in both the engine's own hostname var and this
+oracle's `EVAL_ENGINE_HOSTNAME`, and the CAR minted with `--audience did:web:<tunnel host>`. A quick
+tunnel's host changes every run and the host IS the engine's DID: a new tunnel means re-mint,
+restart, re-register. Restart both dev servers after any `.dev.vars` edit.
+
+## Reference
+
+- `node_modules/@ixo/decision-oracle/docs/guide.md` — "Building an evaluation oracle": the same pipeline
+  as prose, with the concepts, the project anatomy, full handler examples per lane, local dev,
+  billing, deploy, getting hired, operating, and a symptom → cause → fix table.
+- `node_modules/@ixo/decision-oracle/docs/api.md` — the complete API reference (every export, option,
+  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.
+
+## Output contract
+
+The review output from step 2, the stock-vs-custom verdict and the handlers written (or stubbed,
+named), the `src/index.ts` config block, the `.dev.vars` / `wrangler.jsonc` lines to set (never
+committed, never printed), the `facts run --preview` decision, and — plainly — what the provider
+still owes: credits on the owner's subscription, the on-chain Evaluate grant (or the step-10
+self-hire), the deployment that replaces `localhost`, the `oracle init` re-run that re-points
+`#eval` at it, and any name still on a stub.

package/skills/create-rubric/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: create-rubric
+description: Use when someone needs a rubric (the evaluation rules a decision engine judges claims by) for an IXO protocol or claim collection — "create a rubric", "rules for my claims", "what should get approved / rejected", a new protocol needs its #rub, or an existing rubric fails to validate or bind (schema error, BIND_FIELD, RUBRIC_UNRESOLVED, an unusable manifest).
+---
+
+# Creating a rubric
+
+## Overview
+
+A rubric is one JSON-LD file: must-pass **gates**, scored **criteria** with thresholds,
+**human-review** tasks, settlement, and optional external/AI/duplicate/rate rules — bound to exactly
+ONE claim form (the protocol's `#vct`). The decision engine owns the format: its schema is what is
+legal, its binder is the only judge of whether a rubric fits a form, and the rubric's id is the
+sha256 of the file's raw bytes. `bunx decision-oracle rubric validate` is that engine, over HTTP —
+nothing here re-implements it.
+
+**Core principle: form first, ask — don't invent, validate with the engine.** A rubric that has not
+been parsed by the engine's schema AND bound against the real form is a guess, and in production a
+guess decides `unusable`.
+
+## When to use
+
+- "Create a rubric / rules / evaluation criteria for my protocol or collection"
+- A new protocol needs its `#rub`; an owner wants to change what gets approved
+- A rubric fails on the engine or an oracle: schema error, `BIND_FIELD`, `RUBRIC_UNRESOLVED`, an
+  unusable manifest
+
+Not for: the portal's rubric builder UI, or producing facts for a rubric (`write-facts`).
+
+## The pipeline — every step, in order
+
+1. **Get the form.** Ask whether the protocol exists on chain.
+   - Yes →
+     ```bash
+     bunx decision-oracle rubric fetch-form --protocol <protocol did> --out form.json \
+       [--rub rubric.json] [--network devnet|testnet|mainnet]
+     ```
+     writes the live form and prints the `claimSchema` block with the chain's `#vct` proof. `--rub`
+     also downloads the protocol's current rubric bytes, to edit rather than start blank — validate
+     them unchanged first.
+   - No → author the form from `templates/claim-form.example.json` (SurveyJS inside the
+     `ixo:entity#surveyTemplate` envelope; question `name`s are what rules reference — keep the
+     envelope, replace every question), have it anchored, then fetch it. Until then validate against
+     the local file and leave `claimSchema.proof` as `TO-BE-SET-AFTER-ANCHORING`; say so in the
+     hand-off.
+
+   Rules can only reference questions that are on the form. No question, no rule. If the author
+   names something the form has no question for, STOP and ask which they want: bind to an existing
+   question they confirm, or add the question and re-anchor the form first — never map a rule to a
+   similar-looking field on your own.
+
+2. **Interview.** Fill every slot in the contract below with the author's answer, or a default they
+   explicitly accepted. Use plain language (reject / affects the score / a person checks). Batch
+   related questions; skip what the form makes moot.
+
+3. **Draft `rubric.json`.** Read `reference/format-cheatsheet.md` first — only shapes it shows.
+   `constants` and `@const` refs do not exist: inline literals, or use `derived`.
+
+4. **Validate, bind, read the work order.**
+   ```bash
+   bunx decision-oracle rubric validate --rubric rubric.json --form form.json \
+     [--proof <the chain #vct proof>] [--json] [--engine-url <url>] [--network <n>]
+   ```
+   Exit 0 (valid and binds) before you stop — exit 2 is the engine calling it unusable and prints
+   its issues, exit 1 means the engine refused or is unreachable. The printed manifest is what the
+   author's oracle will have to produce: show it to them (ext sources, AI checks, size probes,
+   duplicate/rate parameters).
+
+5. **Hand off.** The EXACT validated bytes get anchored on the protocol as `#rub` (the
+   `publish-protocol` skill) — the id is their sha256, so re-formatting after validating changes it.
+   Print the id and the counts.
+
+## Interview contract — every slot is REQUIRED
+
+| Slot | Ask the author | Serialises to |
+| --- | --- | --- |
+| Form | protocol DID or form file; confirm question names + types | `claimSchema`, every `$ref` |
+| Must-pass | what disqualifies outright; per check: reject, or send to a person? | `gates[]` — `onFail`, `class` |
+| Score | what earns points and how (proportional / bands / yes-no / a person decides); importance 1–5 | `scoring.criteria[]`, `weight` |
+| Thresholds | approve at (0–100); partial floor; review floor — explain the ladder | `approveAt`, `partialFloor`, `reviewFloor` (bps) |
+| Critical | any criterion that alone rejects below a floor | `critical`, `min` |
+| Files | mandatory? allowed types? max MB? what must a PERSON confirm about them | `present` / `mediaTypeIn` / `maxSizeMB` gates; `ManualScore` + `ReviewTask` |
+| Review | who reviews (a Matrix room or one person's DID), SLA hours, on timeout | `review` |
+| Duplicates | what makes two claims "the same" (identity key); flag for review, or reject | `unique` (`by`, `thresholds`) |
+| Rate | max claims per submitter per day/week/month/year, or none | `frequency` (`max`, `per`) |
+| External / AI | another system to ask (endpoint + did:web) or plain-language checks a model should make | `sources[]` / `aiChecks[]` |
+| Settlement | full pay on approve; prorate a partial by what | `settlement` |
+
+Named defaults to OFFER (never assume silently): review 48 h → reject · `weighted_average` · file
+size cap 10 MB · allowed file types = the form question's `acceptedTypes` · unique thresholds
+9000/5000 (reject/review) · unique `by` = the whole claim body · no rate limit. Anything without a
+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.
+- 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.
+- Missing answers: `present` false, `empty` true, every other operator false. Optional-but-valid
+  needs `appliesWhen`.
+- Gates run in order; the first failure ends it. Gate `class` ∈ refuted / invalid_evidence /
+  out_of_authority (reject) or insufficient_evidence / requires_human_review (review).
+- `approveAt > partialFloor ≥ reviewFloor`; points are bps 0–10000; `weight` (1–5) only counts under
+  `weighted_average`.
+- Codes match `^[A-Z0-9]+-[0-9]+-[A-Z0-9-]+$` and are unique. Unknown keys anywhere = schema error.
+- Duplicate/rate rules are declared here but detected by the oracle; proration exists on partial
+  approvals only.
+- Everything a rubric declares under `sources` / `aiChecks` becomes work for whatever oracle is
+  hired: a name declared here is a fact someone has to produce. Don't declare one nobody can answer.
+
+## Output contract
+
+`rubric.json` (and `form.json` when authored) in the directory the user names — default the current
+one — and a one-screen summary: the rubric id, gates / criteria / review-task counts, the manifest's
+"your oracle must produce" list, the anchoring instruction (exact bytes), and any decision the user
+still owes (e.g. the proof).
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `claimSchema.protocol` / `proof` left as placeholders | `rubric fetch-form`; if the form isn't anchored yet, say the proof is owed |
+| Thresholds, weights, SLA, duplicate key invented | ask; offer the default by name |
+| `constants` / `@const` copied from old prose | they don't exist — literals or `derived` |
+| Parsed by eye, never validated | `rubric validate` parses AND binds; a bind failure is `unusable` in production |
+| A gate that "checks the photo is real" | `ManualScore` + `ReviewTask`, or an `aiChecks` entry an oracle runs |
+| "Pay proportionally" applied to approvals | proration is `settlement.onPartial.prorateBy`; approve pays in full — say so |
+| Pretty-printing the file after validating | the id changes; validate the bytes you anchor |