@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,125 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "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": [
+    "ixo",
+    "oracle",
+    "evaluation",
+    "claims",
+    "cloudflare-workers",
+    "hono",
+    "d1"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ixoworld/eval-oralce.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ixoworld/eval-oralce/issues"
+  },
+  "homepage": "https://github.com/ixoworld/eval-oralce#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./facts": {
+      "types": "./dist/facts/index.d.ts",
+      "default": "./dist/facts/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "decision-oracle": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "migrations",
+    "openapi/decision-api.yaml",
+    "skills",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "start": "wrangler dev",
+    "build": "bun ./scripts/build.ts",
+    "bundle-check": "wrangler deploy --dry-run --outdir .wrangler/dry-run",
+    "mock:api": "bunx @stoplight/prism-cli@5.16.0 mock openapi/decision-api.yaml -p 4010",
+    "openapi:generate": "bun openapi/generate.ts",
+    "email:preview": "bun scripts/email-preview.ts",
+    "cf-typegen": "wrangler types --env-interface Env --include-runtime=false",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:node": "vitest run --config vitest.node.config.ts",
+    "test:watch": "vitest",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "wrangler d1 migrations apply eval-oracle-devnet --local",
+    "db:migrate:remote": "wrangler d1 migrations apply eval-oracle-devnet --remote",
+    "db:studio": "drizzle-kit studio",
+    "check": "bun run typecheck && bun run test && bun run test:node",
+    "postinstall": "[ ! -d src ] || bun ./scripts/copy-wasm.ts"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@cloudflare/workers-types": "^5.20260910.1",
+    "@contentauth/toolkit": "0.13.14",
+    "@cosmjs/proto-signing": "^0.39.0",
+    "@cosmjs/stargate": "^0.39.0",
+    "@hono/zod-validator": "^0.8.0",
+    "@ixo/decision-oracle-client": "0.1.1",
+    "@ixo/impactxclient-sdk": "^3.0.1",
+    "@ixo/matrixclient-sdk": "^3.0.0",
+    "@ixo/ucan": "^2.1.0",
+    "@ixo/x402-ixo-pay": "0.6.0",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@scure/base": "^1.2.6",
+    "@scure/bip32": "1.7.0",
+    "@scure/bip39": "^2.4.0",
+    "@sentry/cloudflare": "^10.76.1",
+    "drizzle-orm": "^0.45.2",
+    "eciesjs": "^0.4.15",
+    "fflate": "^0.8.3",
+    "hono": "^4.12.30",
+    "jose": "^6.2.3",
+    "jpeg-js": "^0.4.4",
+    "long": "^5.3.2",
+    "multiformats": "^13.4.2",
+    "protobufjs": "7.6.5",
+    "upng-js": "^2.1.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.18.4",
+    "@sentry/cli": "^2",
+    "@types/node": "^26.1.1",
+    "ajv": "^8.20.0",
+    "drizzle-kit": "^0.31.10",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.146.0",
+    "yaml": "^2.9.0"
+  },
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.3.0"
+  }
+}

package/skills/README.md

@@ -0,0 +1,19 @@
+# Skills
+
+The Claude Code skills shipped with `@ixo/decision-oracle`. `decision-oracle init` copies this directory
+into a new project's `.claude/skills/`, and `decision-oracle skills sync` refreshes those copies from the
+installed package (leaving any skill of your own in that directory alone).
+
+| Skill | Drives |
+| --- | --- |
+| `create-oracle` | building an oracle from a protocol: init → identity → the work order → handlers → run → deploy → get hired |
+| `write-facts` | one manifest entry → one fact handler + its test: the facts API, stock vs custom, the never-fake-ok rule |
+| `create-rubric` | authoring a rubric for a claim form and validating it against the engine |
+| `publish-protocol` | anchoring a claim form and rubric on chain as a protocol entity |
+| `create-collection` | creating a claim collection an oracle can be hired against |
+| `decision-api-client` | testing a Decision API oracle from the customer side: devnet test credentials (source, keys, payment delegation), the SDK and CLI smoke, MCP from Claude Code, the docs agent test |
+| `decision-api-oracle` | turning on, deploying and verifying the Decision API lane — the shipment-delivery example (SwiftDrop Express) on devnet end to end: publish, identity, Cloudflare, deploy, engine registration (payable at once), operator, verify, emails |
+| `add-openhands-support` | making an oracle hireable from the Openhands app (asks, the Yoma youth world): the hire/scan adapter, the bridge's fact names, pricing, the picker's card fields, engine registration |
+
+`reference/engine-contract.md` (here, beside the skills) is the decision engine's contract —
+background for all eight, not an interface anyone codes against.

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

@@ -0,0 +1,113 @@
+---
+name: add-openhands-support
+description: Use when an oracle built on @ixo/decision-oracle should be hireable from the Openhands Network app (asks, quests, the Yoma youth world) — "make my oracle work with Openhands", an oracle missing from the Openhands checker picker, a hire nudge that 404s, an ask whose claims are never judged, or FACT_MISSING on judgeN / withinRadiusN / openhandsSite names.
+---
+
+# Adding Openhands support to an oracle
+
+## Overview
+
+An Openhands ask is its OWN protocol: the app writes a rubric per ask from the poster's sentence
+(`bridge.ts toEngineRubric`), escrows the pay, grants a **meta-authorization** to the checker the
+poster picked, and nudges that checker's `#eval` endpoint. A plain `decision-oracle init` project can
+do none of the Openhands half: it has no hire/scan routes, cannot mint its own evaluate grant from
+a meta-grant, does not answer the bridge's fact names, and is filtered out of the picker. This
+skill adds that adapter. The engine still decides; nothing here judges.
+
+**Explain before acting.** Tell the provider what will happen — files copied into their project,
+a redeploy, an `oracle init` that signs chain transactions (card refresh), `engine register` —
+and wait for their OK. Dry-run every chain step first (`create-oracle` step 8's contract).
+
+## 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:
+
+| Path | What it is |
+| --- | --- |
+| `src/openhands/` | `routes.ts` (`POST /openhands/hire/:id`, `/openhands/scan/:id`, `GET /openhands/claims/:id/why`), `invitations.ts` (10-min backstop), `chain.ts` (meta-grant → `MsgCreateClaimAuthorization`), `act.ts` / `release.ts` (pooled payouts — the act seam's amount stands only where the collection's owner set `operatorAmounts: "allowed"`; Verify step 4), `spots.ts` |
+| `src/workflows/hire.ts` | `OpenhandsHire`: verify → mint → register → scan, one instance per collection |
+| `src/facts/` | the bridge's names: `withinRadius[2..5]`, `located`, `beforeAfter` (package stock), `notElsewhere[N]`, `notMarkedGenerated[N]`, `photoShape[N]`, `daylight`, `weather`, `notAlreadyMapped`, `cooldown`, `reMeasure[N]`, `openhandsSite`; `ai.judge[N]` is the stock judge |
+| `src/index.ts` | wraps `oracle.fetch` with `handleOpenhandsRoute`, routes cron `*/10` to the three passes, exports `OpenhandsHire` |
+| `src/env.ts`, `src/pricing.ts`, `migrations/`, `scripts/flatten-package-migrations.ts` (+ `scripts/lib/`) | `OH_DB`, `HIRE_WORKFLOW`, `WHY_RATE_LIMITER`, the check price |
+
+Outside the eval-oracle repo, get it with `git clone https://github.com/ixoworld/eval-oracle` and
+copy from `examples/street-check-oracle/`. The fact handlers are not street-specific: they are the
+bridge's generic vocabulary, and each ask's rubric picks which ones it asks for — copy them as
+they are. If the project already answers one of these names, keep ONE handler for it: a name
+answered twice throws at module evaluation (`defineFacts`).
+
+`wrangler.jsonc`: a second D1 `OH_DB` (`migrations_dir: "migrations"`), the `HIRE_WORKFLOW`
+workflow (`class_name: "OpenhandsHire"`), crons `["* * * * *", "*/5 * * * *", "0 * * * *", "*/10 * * * *"]`
+(the package's three tiers plus Openhands' ten-minute one), the
+`WHY_RATE_LIMITER` ratelimit — in EVERY env. Keep `supportedProtocols: []` (every ask is new).
+
+```bash
+wrangler d1 create <name>-oh-<env>       # paste the id into that env's OH_DB
+bun run db:migrate:remote                # must apply BOTH databases — copy the example's script
+bun run cf-typegen && bun run check
+```
+
+## Pricing — never leave it at 0
+
+`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.
+
+## 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
+`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
+is offered only for asks without written checks); and the oracle **registered with the engine**
+(`engine register`, below). `oracle init` writes `#orz`, `#eval` and the card — re-run it after any
+price change (`acard` drifts); it is idempotent against live state, so a re-run on an initialised
+oracle only replaces what drifted. `--openhands` adds the `check-openhands` service, priced in
+PAY at the oracle's per-review price (`/v1/info`'s `pricing.api`, else `--price-pay <n>`;
+1 PAY = 1 USD):
+
+```bash
+bunx decision-oracle oracle init --protocol <any ask's protocol, or the app's claim-form entity> \
+  --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.
+
+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
+Console) learns the oracle only at its first decision.
+
+## Verify (in order)
+
+1. `curl <host>/v1/info` → address, `pricing.evaluation` in the ask denom, `allowAiChecks: true`.
+2. The composer's checker step lists the oracle at its price.
+3. Post an ask picking it → `wrangler workflows instances describe <name>-hire-<env> <collectionId>`
+   shows verify, mint (a tx), register `active`, scan.
+4. Submit a claim → logs `evaluate.done` (`decided`) then `act.submitted`; the receipt page
+   `/r/<id>` shows the decision trace and the payout line naming the check fee. The pooled amount
+   the act seam picks stands only if the collection's owner set `operatorAmounts: "allowed"` —
+   `PATCH /v1/collections/:id/settings` with `{ "operatorAmounts": "allowed" }` (UCAN action
+   `collections/settings`), under the owner's
+   own UCAN. Otherwise the oracle pays the default leg and logs `act.amount-ignored-not-opted-in`.
+
+## Common mistakes
+
+| Symptom | Cause / fix |
+| --- | --- |
+| 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 |
+| `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` |
+| `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

@@ -0,0 +1,199 @@
+---
+name: create-collection
+description: Use when a published protocol needs a live claim collection an oracle can be hired against — creating the deed that hosts the claims, the collection on it, its evaluation payment, funding its admin account, granting Evaluate/Submit authorizations, wiring the owner→oracle Matrix delegation, or debugging "No claim protocols are linked to this entity" / NO_EVALUATE_GRANT / "payment withdrawal failed" / an oracle that can't pull claims.
+---
+
+# Creating a collection
+
+## Overview
+
+The claims stack is THREE on-chain objects, created in a fixed order, each pointing at the previous
+one — `reference/claims-stack.md` is the full brief:
+
+```text
+protocol  (protocol/verifiableClaim — the claim SCHEMA: #vct + #rub; a template, owns nothing)
+  → deed  (a domain entity — hosts the claims; its linkedClaim names the protocol)
+    → collection  (MsgCreateCollection: entity = the DEED, protocol = the protocol; a numeric id)
+      → claims (submit / evaluate)
+```
+
+A **collection** is the live claims lane: payment legs (submission/approval/rejection/evaluation), a
+quota and time window, and the DEED's admin account that pays out on evaluation. A deed holds at
+most one collection per protocol; every command resolves it FROM the (`--entity`, `--protocol`) pair
+via Blocksync, so the pipeline is resumable with nothing but those two.
+
+**The mistake this skill exists to prevent:** passing the protocol DID where the deed belongs. The
+chain accepts `entity = protocol`, but the portal's collection block is given the ENTITY and lists
+only protocols found in its `linkedClaim` → claims-config doc → `entityClaims[].template.id` — a
+protocol entity has no `linkedClaim`, so it answers **"No claim protocols are linked to <did>"**.
+`create-collection` runs that same check before signing and refuses a deed that doesn't link the
+protocol.
+
+## Safety — read before running anything
+
+- **devnet is the only implicit network.** `--network` defaults to devnet; testnet/mainnet must be
+  named explicitly, never assumed.
+- **Every chain write is a real signed transaction.** The confirm gate prints the exact plan and
+  exits 0 without signing unless `--yes` is passed. Run WITHOUT `--yes` first, show the plan, and
+  only re-run WITH `--yes` after the user explicitly says to proceed.
+- **Signing is an AuthHub session, not a mnemonic** — `bunx decision-oracle login --network <n>` once
+  (the same session `publish-protocol` used). The session is also the Matrix identity: the deed's
+  room is joined and its bots invited as the session's own Matrix user, and the room-state write
+  carries the session's UCAN. Never ask anyone to paste a mnemonic or session file into a message.
+- **This spends real funds twice over**: gas on every signed tx, AND whatever `--eval-amount` /
+  `--fund` say actually moves — the evaluation payment is real income for a real oracle, and funding
+  is a real transfer out of the signer's balance.
+
+## When to use
+
+- "Create a collection for this protocol / hire an oracle to evaluate claims / grant Evaluate or Submit"
+- The portal's collection block says "No claim protocols are linked to this entity"
+- A collection exists but evaluations fail with `payment withdrawal failed`
+- An oracle reports `NO_EVALUATE_GRANT` / 403 trying to decide a claim against this collection
+- The oracle needs the owner→oracle Matrix delegation before it can pull claim bodies from the
+  Matrix claim bot (step 5)
+
+## Pipeline
+
+1. **Ask, don't assume, for every policy-relevant value:**
+   - protocol DID (already published, with a `#rub` — if not, hand off to `publish-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
+   - 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)
+   - quota and window in days if the defaults (100, 90) aren't right — state them explicitly rather
+     than silently applying them
+
+2. **Log in once** if there is no session for this network yet:
+   `bunx decision-oracle login --network devnet`.
+
+3. **The deed** — skip when the user already has a domain entity that links the protocol (step 4
+   checks this for real). Otherwise, dry run first:
+
+   ```bash
+   bunx decision-oracle create-deed --protocol <protocol did> --title "…" [--description "…"] \
+     [--type deed] [--network devnet] [--phase entity|room|claims|all] [--entity <did>] [--yes]
+   ```
+
+   Three phases: `entity` (`MsgCreateEntity`, `--type` default `deed`), `room` (source the deed's
+   Matrix room, invite the claim bot AND the state bot — `reference/claims-stack.md` says why both),
+   `claims` (the claims-config doc into room state at `claims/<cid>` with a public ACL, then one tx:
+   `MsgAddLinkedClaim {id}#claims` + `MsgAddService`). Resume with `--entity <did> --phase
+   room|claims|all`. It prints the exact step-4 command.
+
+4. **The collection**, dry run first:
+
+   ```bash
+   bunx decision-oracle create-collection --entity <deed did> --protocol <protocol did> \
+     --eval-amount <amount> [--eval-denom uixo] [--network devnet] [--fund <amount>] \
+     [--evaluate <oracle address>] [--submit <agent address>] [--quota 100] [--days 90] \
+     [--max-custom-amount 0uixo] [--phase collection|fund|grants|all] [--yes]
+   ```
+
+   `--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
+   claims carry coins, set it to at least the largest claim amount in that denom, or every
+   approval fails at MsgExec. `0` is right only when claims carry no coins (an intent claim sends
+   none). Anything above the claims' own amounts is room for the oracle to set its own — and that
+   stands only once the owner also opts in on the oracle (`PATCH /v1/collections/:id/settings`
+   `{ operatorAmounts: "allowed" }`; a later owner must opt in again).
+
+   Same discipline: show the dry-run plan for every phase that would run, get explicit OK, only then
+   re-run identically with `--yes`. `--phase collection` is a safe no-op when the deed already holds
+   a collection for this protocol.
+
+   **Gotcha:** the collection's admin account — the DEED's, not the signer's — pays EVERY evaluation,
+   rejects included, plus the approval payment on an ordinary approve (an intent claim's comes from
+   escrow) and the rejection payment on a reject, all on the same message. It starts at zero. An
+   unfunded admin makes `MsgEvaluateClaim` fail `payment withdrawal failed`. The oracle recognises that failure: the decision parks
+   `chainStatus: blocked` (no retries), the collection pauses `pausedReason: admin-unfunded`, and the
+   owner gets a Matrix notice in the review room plus an email to `contactEmail` naming the admin
+   account, the full amount the failed claim needs (evaluation + its verdict's payment, per denom)
+   and the balance. Top it up and the oracle resumes and re-delivers the parked decisions by itself
+   within a minute — nothing to re-run. Still: pass `--fund` here, sized by the number of
+   EVALUATIONS you expect plus the approval payouts the admin account pays.
+
+5. **Grants and the delegation are two different things.** `--evaluate` / `--submit` in step 4 grant
+   the on-chain `EvaluateClaimAuthorization` / `SubmitClaimAuthorization` (granter = the deed's
+   admin) — that is what stops `POST /v1/decisions` 403ing `NO_EVALUATE_GRANT`. The oracle STILL
+   cannot pull claim bodies from Matrix without an owner→oracle UCAN delegation:
+
+   ```bash
+   bunx decision-oracle delegation --for bot --audience did:ixo:<oracle address> \
+     --out delegation.car [--network devnet] [--days 30] [--yes]
+   ```
+
+   Same dry-run-then-confirm discipline, same session. The CAR is written to a file, never printed —
+   it is a bearer credential — and it expires on its own schedule (30 days by default), independent
+   of the grants' 365-day expiry.
+
+   The bot returns the claim's JSON re-ordered, so its bytes can't be CID-checked: a claim the oracle
+   read only from the Matrix claim bot goes to the engine as `claimContent` with no `document`, and
+   is decided like any other. For a payout protocol the oracle also looks past the bot to the IPFS
+   gateway and a Cellnode for the exact stored bytes.
+
+6. **Enroll the collection with the oracle.** An oracle watches nothing until the collection's owner
+   registers it. The portal makes that call for a real commissioner; as the same session, with the
+   step-5 CAR:
+
+   ```bash
+   bunx decision-oracle register --collection <id> --delegation delegation.car \
+     [--contact-email <addr>] [--kit <oracle url>]
+   bunx decision-oracle scan --collection <id>     # discover claims now instead of at the next tick
+   ```
+
+   A refusal names its gate: not the chain owner, no Evaluate grant for that oracle's
+   `ORACLE_ADDRESS` (step 4), or an evaluation payment below the oracle's own minimum. To put a claim
+   in without the portal (the SUBMITTER's side, as the same session — it holds the Submit grant):
+
+   ```bash
+   bunx decision-oracle submit-claim --collection <id> --answers answers.json \
+     [--file <fileQuestion>=<path> …] [--yes]
+   ```
+
+   (claim-bot media upload → save into the deed's room → `MsgExec(MsgSubmitClaim)`. The
+   passport-delivery example's `protocol/sample-claim.json` is a worked answers file.)
+
+7. **Report the run** — the output contract below.
+
+## Output contract
+
+Always end with this block, verbatim, filled in from this run:
+
+```text
+collection id : <id>
+deed DID      : <did>
+protocol DID  : <did>
+oracle granted: <evaluate address>
+
+bunx decision-oracle register --collection <id>      # if it isn't registered yet
+bunx decision-oracle scan --collection <id>
+```
+
+That grant is exactly what unlocks the oracle's persisted-decision leg; the printed commands are
+what makes the first real decision land. Say plainly what is still owed too: an unfunded admin
+account, a phase that was dry-run but never confirmed, or a delegation nobody has minted yet.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `--entity <protocol did>` | the entity is the DEED; the protocol goes in `--protocol` |
+| 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 |
+| 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 |
+
+## Reference
+
+- `reference/claims-stack.md` — protocol vs deed vs collection: what each is, the exact
+  `linkedClaim` / claims-config shapes the portal reads, the two bots, and the pre-flight checklist.
+- `reference/collection.md` — the messages in detail, resuming, the admin-funding gotcha in full,
+  and the delegation's identity.

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

@@ -0,0 +1,106 @@
+# Protocol vs deed vs collection — the IXO claims stack
+
+Three distinct on-chain objects, created in a fixed order, each pointing at the previous one. Never
+confuse them: passing a protocol DID where an entity DID is expected yields the portal's "No claim
+protocols are linked to <did>".
+
+## 1. Protocol — `entityType: protocol/verifiableClaim`
+
+WHAT: the claim *schema*. Defines what a claim looks like: the survey template (`{id}#vct`) and the
+rubric (`{id}#rub`) as LinkedResources. It is an entity, but a template, not a domain — it owns
+nothing and links to nothing. `linkedClaim: []` always.
+
+MADE BY: `bunx decision-oracle publish-protocol` (the `publish-protocol` skill).
+
+OUTPUT: the protocol DID. Only ever used as `--protocol` in steps 2 and 3 — NEVER as anything's
+`--entity`.
+
+## 2. Deed — a domain entity (`deed`, `project`, `dao`, …)
+
+WHAT: the thing that *hosts* claims. Owner of the collection's admin account; what users submit
+claims against; whose Matrix room the claims land in. Links to the protocol through `linkedClaim`.
+
+MADE BY: `bunx decision-oracle create-deed`, three phases:
+
+1. `entity` — `MsgCreateEntity` of `--type` (default `deed`), the same verification / controller /
+   relayer shape as a protocol. The DID is only known from the tx events, which is why the
+   `linkedClaim` cannot ride the create message (its doc is keyed on the room the DID names).
+2. `room` — the rooms bot sources the entity's room and the session's Matrix user joins; then BOTH
+   bots are invited (each invite also raises the bot's power level, so it must be done by a room
+   member with power — the session user):
+   - the **claim bot** — without it every submission is `IXO_ROOM_NOT_FOUND`;
+   - the **state bot** — without it nothing can read or write the room's state, and the state bot
+     answers `You do not have permission to edit state for 'claims'`.
+3. `claims` — the claims-config doc:
+   ```json
+   {
+     "@context": { "ixo": "https://w3id.org/ixo/vocab/v1", "web3": "https://ipfs.io/ipfs/",
+                   "id": "@id", "type": "@type", "@protected": true },
+     "id": "{id}#claims",
+     "type": "ixo:Claims",
+     "entityClaims": [{
+       "id": "claims",
+       "template": { "id": "<protocolDid>", "type": "verifiableClaim", "title": "…",
+                     "description": "…", "creator": "", "createdAt": "<ISO>" },
+       "isEncrypted": false,
+       "isHeadlineMetric": true
+     }]
+   }
+   ```
+   `template.id` MUST be the bare protocol DID. NEVER a creator-studio `ref:<node>:did#Name`
+   placeholder — it cannot be resolved from a ledgered entity and the portal's picker greys it out.
+   `proof` = CIDv1 / raw / sha256 of the doc's bytes. The doc goes into the deed's room state via the
+   state bot at **key `claims`, path `<cid>`**, then ACL `{ canAccess: ["*"], canEdit: [] }` —
+   exactly where the portal reads it (`queryState(roomId, "claims", proof)`, which is NOT where the
+   generic linked-resource resolver looks, so the key and path matter). Then ONE tx:
+   `MsgAddLinkedClaim`
+   ```
+   { id: "{id}#claims", type: "protocol/verifiableClaim", serviceEndpoint: "matrix:<cid>",
+     proof: "<cid>", encrypted: "false", right: "", description: "…" }
+   ```
+   plus `MsgAddService {id}#matrix`. The portal keys on the endpoint's scheme (`matrix`) only.
+
+TO ATTACH A PROTOCOL TO AN EXISTING ENTITY: `create-deed --entity <did> --phase claims` (add `room`
+first if its room has no state bot yet). Updating the doc alone is not enough if the entity has no
+`linkedClaim` entry.
+
+OUTPUT: the deed DID. This is the `--entity` argument everywhere below.
+
+## 3. Collection — `MsgCreateCollection`
+
+WHAT: an *instance* that accepts claims: "claims of protocol X, against entity Y, between these
+dates, up to this quota, with these payments". Not an entity, no DID — a numeric-string id.
+
+MADE BY: `bunx decision-oracle create-collection`:
+- `entity` = the DEED (never the protocol), `protocol` = the protocol
+- `endDate` is ALWAYS set (a nil end date panics the chain on submit); the command uses now − 1 day →
+  now + `--days`
+- payment legs are paid from the DEED's admin account (`entity.accounts[name=admin]`); the signer
+  must own the deed (or hold authz for it)
+- before signing, it runs the portal's own gate: the deed's `linkedClaim` is non-empty, each
+  `matrix:` one's doc is read from the room, and some `entityClaims[].template.id` equals the
+  protocol — else it fails loudly instead of minting a collection the portal cannot see.
+
+The portal's protocol picker is given the deed DID and lists only protocols found in THAT entity's
+`linkedClaim` → claims-config → `entityClaims[].template.id`. If the picker is empty, the deed is not
+linked to the protocol yet: fix step 2, don't retry step 3.
+
+## Order and dependency
+
+```text
+protocol --(template.id in the claims-config doc, referenced by linkedClaim)--> deed
+deed + protocol -----------------------------------------------------------> collection
+collection ----------------------------------------------------------------> claims
+```
+
+Checklist before creating a collection:
+- [ ] a protocol DID whose entityType is `protocol/verifiableClaim`, with a `#rub`
+- [ ] a deed DID whose entityType is a domain (`deed` / `project` / `dao`), NOT a protocol
+- [ ] the deed's `linkedClaim` is non-empty on Blocksync
+- [ ] the resolved claims-config doc has `entityClaims[].template.id == <protocol did>`
+- [ ] both bots in the deed's room (the claim bot's `/invited` endpoint answers `isInvited: true`;
+      the state bot has no such endpoint — trust `create-deed`'s `room` phase)
+- [ ] `endDate` is set
+
+Two rules here come from behaviour hit for real rather than from types: "always set an end date" (a
+chain panic) and "never a `ref:` placeholder" (the portal's own guard).