@ixo/decision-oracle 0.0.0-stage → 0.2.0

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

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

package/skills/publish-protocol/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: publish-protocol
+description: Use when a use case needs to become an on-chain IXO protocol — anchoring a new claim form (#vct) and rubric (#rub) as a protocol entity, adopting a protocol that already has its form by anchoring or replacing its rubric alone, sourcing its Matrix room, resuming a half-finished publish, or debugging IXO_ROOM_NOT_FOUND / a missing #rub on chain.
+---
+
+# Publishing a protocol
+
+## Overview
+
+A **protocol** is an on-chain IXO entity (`entityType: protocol/verifiableClaim`) carrying two
+LinkedResources — the claim form (`#vct`, SurveyJS) and the rubric (`#rub`, the JSON-LD rulebook a
+decision engine judges claims by) — plus a Matrix room the claim bot needs before it will accept
+submissions against it. This skill composes two things:
+
+- **`create-rubric`** authors and validates the form + rubric pair. The decision engine owns the
+  rubric format; `bunx decision-oracle rubric validate` is that engine over HTTP.
+- **`bunx decision-oracle publish-protocol`** does the chain authoring: `MsgCreateEntity` → Matrix
+  upload → `MsgAddLinkedResource` (`#vct` + `#rub`) + `MsgAddService` → source the Matrix room.
+  Phases `entity` / `resources` / `room` (default `all`), resumable with `--entity <did> --phase <p>`.
+  Plus `rub`, which is a different job — see below.
+
+There are two jobs here, and picking the wrong one fails on chain:
+
+| You have | Run |
+| --- | --- |
+| Nothing yet — a form and a rubric to publish as a NEW protocol | `--phase all` (the pipeline below) |
+| A protocol that ALREADY carries its form (`#vct`), yours or someone else's | `--phase rub` |
+
+## 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.** Every write goes through a confirm gate that
+  prints the exact plan (network, signer, messages, fee) and exits 0 without signing unless `--yes`
+  is passed. Run WITHOUT `--yes` first, show the printed plan to the user, and only re-run WITH
+  `--yes` after they explicitly say to proceed. These commands spend real funds (gas).
+- **Signing is an AuthHub session, not a mnemonic.** `bunx decision-oracle login --network <n>` once —
+  it opens the login URL, waits for the callback, and saves a session under the user's home
+  directory. Every command after that reads it automatically. The session is also the Matrix
+  identity the `resources`/`room` phases use. Never ask anyone to paste a mnemonic or a session file
+  into a message.
+
+## When to use
+
+- "Publish a protocol / anchor a claim form and rubric on chain / get a protocol DID"
+- "Adopt this protocol" / "put my rubric on an existing protocol" / "publish a new version of the
+  rules" — the protocol already has its form, so only `#rub` changes: see `--phase rub` below
+- Resuming a publish that stopped partway (an entity DID exists, resources or room don't)
+- `IXO_ROOM_NOT_FOUND` from the claim bot, or Blocksync shows a protocol with no `#rub`
+
+## Pipeline
+
+1. **Author + validate FIRST — before any chain write.** With the `create-rubric` skill: author
+   `form.json` (from its `templates/claim-form.example.json`) and `rubric.json` per its interview,
+   leaving `claimSchema.protocol` / `proof` as `"TO-BE-SET-AFTER-ANCHORING"` — the `resources` phase
+   overwrites both with the real values once the form is uploaded. Then:
+
+   ```bash
+   bunx decision-oracle rubric validate --rubric rubric.json --form form.json
+   ```
+
+   Exit 0 is required before step 2 (a placeholder-proof warning is fine pre-anchoring); exit 2 is
+   the engine reporting bind issues. Never anchor around a validation failure. `publish-protocol`
+   runs the same validation itself before it writes anything — a second gate, for free.
+
+2. **Log in once, then publish.**
+
+   ```bash
+   bunx decision-oracle login --network devnet     # only if there is no session for this network yet
+   bunx decision-oracle publish-protocol --rubric rubric.json --form form.json \
+     [--network devnet] [--phase entity|resources|room|all] [--entity <protocol did>] \
+     [--engine-url <url>] [--yes]
+   ```
+
+   A dry run (no `--yes`) prints the plan for every phase that would run. Get the user's explicit OK,
+   then re-run identically with `--yes` appended. `reference/publishing.md` has what each phase signs
+   and uploads, and its failure modes.
+
+3. **Hand off.** From the final published block, report: the protocol DID, the `#vct` proof, the
+   `#rub` proof (= the rubric's id, its sha256), the room id, and the next command:
+
+   ```bash
+   bunx decision-oracle create-deed --protocol <protocol did> --title "<deed name>"
+   ```
+
+   The `create-collection` skill takes it from there, on the same session. A protocol is only the
+   SCHEMA: claims are hosted by a DEED (a domain entity whose `linkedClaim` names the protocol), and
+   the collection is created on the deed — never on the protocol, or the portal answers "No claim
+   protocols are linked to this entity". `create-collection`'s `reference/claims-stack.md` has the
+   model.
+
+## Adopting a protocol that already has its form — `--phase rub`
+
+Use this when the protocol EXISTS and carries a `#vct` already: IXO's own oracle-service-claim
+protocols, a protocol published by a partner, or simply a second version of your own rules. Do NOT
+reach for `--phase resources` — it re-anchors `#vct` too, and the chain refuses a linked-resource id
+that already exists (`duplicated resource id`), so the whole transaction fails.
+
+```bash
+bunx decision-oracle rubric fetch-form --protocol <protocol did> --out form.json   # the live #vct
+# author rubric.json against form.json with the create-rubric skill, then:
+bunx decision-oracle rubric validate --rubric rubric.json --form form.json
+bunx decision-oracle publish-protocol --phase rub --protocol <protocol did> \
+  --rubric rubric.json --form form.json [--network devnet] [--yes]
+```
+
+What it does, and nothing else: uploads the rubric to the IXO Vault (else the IPFS gateway), then signs ONE transaction —
+`MsgDeleteLinkedResource` + `MsgAddLinkedResource` when a `#rub` is already anchored, or just the
+add when there is none. `--form` is still required because the rubric is validated against the real
+form before anything is written; the rubric's `claimSchema` is repinned from the CHAIN's live `#vct`
+proof (copied verbatim — on a portal-published protocol it is a CID, not a sha256).
+
+Three things to expect:
+
+- **It is idempotent.** If the anchored `#rub` proof already equals the id these bytes hash to, it
+  prints `already anchored` and does nothing — no upload, no transaction, no fee.
+- **Only the protocol's owner can anchor.** If the session doesn't own it, the rubric is still
+  uploaded and the exact messages are printed, composed for the owner to broadcast. Send them those
+  lines; they sign them. (Same posture as `oracle init --phase backlink`.)
+- **The room is not this command's business.** A protocol that already has claims already has its
+  room; `--phase rub` never touches it.
+
+## Interview slots
+
+The interview belongs to `create-rubric` (step 1) — form, gates, thresholds, review, duplicates,
+settlement. This skill itself asks exactly two things: **which network** (devnet is the only implicit
+one), and **explicit go-ahead before any broadcast** (show the dry-run plan, then `--yes`).
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Anchoring bytes that were never validated | `rubric validate` first; a rubric that doesn't bind decides `unusable` in production |
+| Re-formatting `rubric.json` after validating | the id is the sha256 of the bytes — anchor exactly what was validated |
+| Filling in `claimSchema.protocol` / `proof` by hand before publishing | leave the placeholders; the `resources` phase patches the real values in |
+| Running `--yes` on the first invocation | dry-run, show the plan, then confirm — every phase signs real transactions |
+| Skipping the `room` phase | the claim bot answers `IXO_ROOM_NOT_FOUND` for every submission, though the entity looks complete |
+| Creating the collection on the protocol | collections live on a DEED (`create-deed` → `create-collection`) |
+| `--phase resources` on a protocol that already has a `#vct` | the chain refuses the duplicate id and the whole tx fails — use `--phase rub` |
+| Using an oracle's Matrix token instead of the session | the room's invites must come from the entity owner's own Matrix user |
+
+## Output contract
+
+The protocol DID, both proofs (`#vct` and `#rub` — the latter is the rubric's id), the room id, what
+each phase actually signed, and the exact `create-deed` command to run next. Plus anything still
+owed: a phase that failed, an un-invited bot, or a rubric change that would need re-anchoring.
+
+## Reference
+
+`reference/publishing.md` — phase-by-phase detail (what each signs and uploads), resuming a partial
+run, the Matrix identity rule, and the network endpoints.

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

@@ -0,0 +1,116 @@
+# Publishing a protocol — phase reference
+
+## Login (once per network)
+
+```bash
+bunx decision-oracle login --network devnet|testnet|mainnet
+```
+
+PKCE (S256) + `state` against the ixo AuthHub for that network. It prints the login URL (and tries
+to open it), then waits for EITHER a loopback callback on `http://localhost:8976/callback` OR a full
+callback URL pasted into the terminal — whichever arrives first. The session is saved under the
+user's home directory with mode 0600 and a warning printed: it is a bearer session signing key
+(derived — the AuthHub root key never leaves the hub), so treat it like a password. Every other
+command loads it automatically; there is no mnemonic anywhere in this flow.
+
+## Phases
+
+### `entity`
+
+Signs `MsgCreateEntity` (`entityType: protocol/verifiableClaim`), then extracts the new
+`did:ixo:entity:…` from the tx's events. If extraction fails the command exits non-zero even though
+the tx landed — the entity exists on chain but its DID has to be found by hand (a Blocksync `entity`
+query filtered by owner) before resuming. Skip this phase with `--entity <existing did>` to build
+resources/room onto an entity created some other way, or by a previous run.
+
+### `resources`
+
+Uploads `form.json` and a **patched** copy of `rubric.json` (its `claimSchema.protocol` / `proof` set
+to the new entity DID and the form's own proof) to the IXO Vault as two separate uploads — gated by
+one confirm, not a chain write so there is no fee line — then signs ONE tx with three messages:
+`MsgAddLinkedResource #vct`, `MsgAddLinkedResource #rub`, `MsgAddService #matrix`. Requires
+`--entity` when run standalone. The uploads are signed with the session's own Ed25519 key (a
+one-write UCAN) and anchored by their public `<vfs>/public/cid/<cid>` URL; if the Vault refuses, the
+CLI prints a `⚠` and stores them on the IXO IPFS gateway instead — nothing to configure.
+
+### `rub`
+
+The adopt-an-existing-protocol phase, and the one phase `--phase all` never runs. Target it with
+`--protocol <did>` (`--entity` works too — same flag, the other spelling):
+
+```bash
+bunx decision-oracle publish-protocol --phase rub --protocol <did> \
+  --rubric rubric.json --form form.json [--network devnet] [--yes]
+```
+
+1. Resolves the protocol on Blocksync and reads its `#vct` proof. No `#vct` ⇒ refused: that is a
+   `resources` publish, not an adoption.
+2. Checks the rubric's `claimSchema` against that protocol DID and that proof **verbatim** — for a
+   protocol published through the portal the proof is the template lane's CID, not a sha256 of
+   `form.json`, and the engine string-compares it. A file that ALREADY pins both is anchored byte
+   for byte as written, so its id is the `sha256(raw file bytes)` that `rubric validate` printed.
+   Otherwise it is repinned and re-serialized (`JSON.stringify(doc, null, 2)`), and the id is the
+   sha256 of THOSE bytes. Either way that sha256 is the rubric's id and the `#rub` proof.
+3. Already anchored under that exact id ⇒ prints `already anchored` and stops. Nothing uploaded,
+   nothing signed.
+4. Uploads the patched rubric to the IXO Vault, else the IXO IPFS gateway (own confirm gate, no
+   fee line).
+5. Signs ONE tx: `MsgDeleteLinkedResource` + `MsgAddLinkedResource` when a `#rub` exists, else the
+   add alone. It has to be one tx — `MsgAddLinkedResource` is refused for an id that already exists
+   (`duplicated resource id`), and splitting it across two would leave the protocol with no rubric
+   in between. The delete names the resource id EXACTLY as the chain stores it: the unexpanded
+   `{id}#rub` literal Blocksync reports, never a rebuilt `did:…#rub`.
+
+**Ownership.** The chain checks the signer against the DID's authentication relationship, so only
+the protocol's owner can anchor. When the session is not the owner the messages are composed for the
+owner, printed, and not broadcast — the upload has already happened, so all they have to do is sign
+the printed lines. Same behaviour as `oracle init --phase backlink`.
+
+`--form` stays required: it is what the engine's binder validates the rubric against before anything
+is written. Get it with `rubric fetch-form --protocol <did> --out form.json`, which downloads the
+live `#vct` bytes.
+
+### `room`
+
+Sources the entity's Matrix room and invites the claim bot. Without it the claim bot answers every
+submission with `IXO_ROOM_NOT_FOUND`, even though the entity and its resources are fully anchored.
+Joins and invites as the session's Matrix user and mints its UCAN from the session's own signing
+mnemonic — no Matrix-vault PIN, no separate room id or value pin.
+
+## Resuming a partial run
+
+Every phase after `entity` needs an entity DID. If a run stopped after `entity` (or you are building
+onto an entity made another way), pass `--entity <did>` and `--phase resources` (or `room`, or `all`
+— the `entity` phase is a no-op when `--entity` is given). There is no state file; the whole resume
+mechanism is that pair.
+
+`rub` is not part of that sequence and never runs under `all` — it is the adoption path, not a step
+of a publish.
+
+## Validation is not optional, and not re-implemented here
+
+`publish-protocol` re-validates on every invocation before touching the chain, independent of
+`--phase`, by asking the ENGINE to parse and bind the rubric against the form (the same call
+`bunx decision-oracle rubric validate` makes; `--engine-url` overrides which engine). A rubric that fails
+to bind is refused with the specific issues printed, never anchored. This package has no rubric
+schema or binder of its own — the engine owns the format, and this is that same gate run a second
+time.
+
+## Matrix identity — the session, and only the session
+
+`room` needs a Matrix access token (the uploads do not — they go to the Vault). AuthHub hands back a Matrix mnemonic (alongside
+the Matrix user id and homeserver), never a token; the CLI turns it into one exactly the way the
+portal does on sign-in. One login per run, minted only after a phase has passed its confirm gate — a
+dry run logs nobody in.
+
+**It has to be this user.** The rooms bot invites the UCAN issuer — the session DID's Matrix user —
+into the sourced room, and the claim-bot invite then sets power levels, so both must run as the
+entity OWNER's account. An oracle's own bot token is a different user: the join fails
+`M_FORBIDDEN You are not invited to this room` and leaves the room sourced but the claim bot
+uninvited.
+
+## Network endpoints
+
+`--network` (devnet by default) is the ONLY source of RPC / Blocksync / Matrix / AuthHub endpoints.
+The session's homeserver is asserted equal to the network's, so a session logged in against another
+network fails with a clear message rather than writing to the wrong chain.