@ixo/decision-oracle 0.2.21 → 0.2.22

package/README.md

@@ -7,7 +7,7 @@ for (a courier API says the parcel arrived, a model says the photo shows what it
 says this is not a duplicate), hands those facts to the IXO **decision engine**, and signs the
 verdict the engine returns on chain with your own key.
 
-This repository is the package that is all of that **except the facts**. You write a config object
+This package is all of that **except the facts**. You write a config object
 and a handful of async functions; `@ixo/decision-oracle` brings the claim pulling, the engine handshake,
 the D1 ledgers, human-review folds, the chain write, billing pauses, email and Matrix notices, the
 cron and the Workflows. It is for developers who want to run an oracle as a service, for teams
@@ -16,9 +16,8 @@ publishing a protocol and its rubric, and for anyone who needs a claim judged th
 **The rubric is the work order. The engine decides. You produce facts and sign.**
 
 > **Learn more**
-> · Step-by-step guide: [`packages/eval-oracle/docs/guide.md`](https://github.com/ixoworld/eval-oralce/blob/main/packages/eval-oracle/docs/guide.md)
-> · Full API reference: [`packages/eval-oracle/docs/api.md`](https://github.com/ixoworld/eval-oralce/blob/main/packages/eval-oracle/docs/api.md)
-> · The engine's wire contract: [`docs/ENGINE-CONTRACT.md`](https://github.com/ixoworld/eval-oralce/blob/main/docs/ENGINE-CONTRACT.md)
+> · Step-by-step guide: [docs.ixo.world — Decision oracle](https://docs.ixo.world/build-an-oracle/decision-oracle)
+> · Full API reference: [docs.ixo.world — Decision oracle API reference](https://docs.ixo.world/build-an-oracle/decision-oracle/api-reference)
 
 ---
 
@@ -360,7 +359,7 @@ whole surface. `out.issues` is empty iff the engine would accept this FactSet. T
   Pass `stock` in `fakeTools({ … })` (or `runFacts`'s `stock` option) when the handler under test
   wraps it.
 
-Full reference: [`packages/eval-oracle/docs/api.md`](https://github.com/ixoworld/eval-oralce/blob/main/packages/eval-oracle/docs/api.md).
+Full reference: [Decision oracle API reference](https://docs.ixo.world/build-an-oracle/decision-oracle/api-reference).
 
 ## CLI reference
 
@@ -467,7 +466,7 @@ under `--json` that dry run prints nothing on stdout.
 Agents reach the same lane through the hosted MCP server at `https://<oracle>/v1/mcp` —
 `claude mcp add --transport http ixo https://<oracle>/v1/mcp --header "Authorization: Bearer eo_live_…"`
 (plus `X-Payment-Delegation` for an `x402` source): `submit_claim`, `get_decision`, `list_protocols`,
-`verify_receipt`, under the key's own scopes and limits (`docs/api.md`, "Use with Claude Code and
+`verify_receipt`, under the key's own scopes and limits ([API reference](https://docs.ixo.world/build-an-oracle/decision-oracle/api-reference), "Use with Claude Code and
 other MCP clients").
 
 ### Protocol authoring (the commissioner's side)
@@ -493,7 +492,7 @@ Two places, and the split is the rule: **public config in `wrangler.jsonc` `vars
 | Var | What it is |
 | --- | --- |
 | `IXO_NETWORK` | `devnet` / `testnet` / `mainnet` — supplies every per-network URL below |
-| `ORACLE_HOSTNAME` | the host this oracle's `did:web` is served from; **must equal the Custom Domain in `routes`** |
+| `ORACLE_HOSTNAME` | the host this oracle's `did:web` is served from: your Custom Domain in `routes`, or, with no custom domain, the Worker's free `<worker>.<account>.workers.dev` host |
 | `ORACLE_ADDRESS`, `ORACLE_DID` | the public chain identity (asserted against `ORACLE_SECP_MNEMONIC` at first use — a mismatch fails loud) |
 | `ORACLE_MATRIX_USER_ID` | the oracle bot's MXID, `@did-ixo-<address>:<homeserver>` |
 | `ORACLE_ENTITY_DID` | the on-chain oracle ENTITY from `oracle init` — **required for a deployed oracle**: unset on a non-local `ORACLE_HOSTNAME`, `/health/ready` fails its `identity` check (local dev is exempt). Unset, the Matrix review card also falls back to `ORACLE_DID` and reviews work only from the portal page |
@@ -598,7 +597,7 @@ The bindings the template declares: **D1** (`DB` — the ledgers), **KV** (`CACH
 two **Workflows** (`CLAIM_WORKFLOW`, `REVIEW_WORKFLOW`), a **Durable Object** (`SEQUENCE_MANAGER`,
 the chain sequence keeper), two **rate limiters** (`API_RATE_LIMITER` per IP, `API_KEY_RATE_LIMITER`
 per API key for the Decision API lane), **email** (`EMAIL`), and three **cron** triggers (every minute, every five minutes, hourly — keep all three) — plus an
-optional **R2** bucket (`API_UPLOADS`, commented out: absent ⇒ the upload route answers 501), and an optional answer archive (`ANSWERS_ARCHIVE`, commented out: bound ⇒ every evaluated ask, answer and photo is kept in that private bucket, one `<askId>-<title>/` folder per ask, shaped by `defineOracle`'s `archive` hooks — [guide §12](https://github.com/ixoworld/eval-oralce/blob/main/packages/eval-oracle/docs/guide.md#12-operating-it)). Every binding and the whole `vars` block are redeclared per env — they inherit
+optional **R2** bucket (`API_UPLOADS`, commented out: absent ⇒ the upload route answers 501), and an optional answer archive (`ANSWERS_ARCHIVE`, commented out: bound ⇒ every evaluated ask, answer and photo is kept in that private bucket, one `<askId>-<title>/` folder per ask, shaped by `defineOracle`'s `archive` hooks — [guide, "Operating it"](https://docs.ixo.world/build-an-oracle/decision-oracle#12-operating-it)). Every binding and the whole `vars` block are redeclared per env — they inherit
 nothing from the top level.
 
 `db:migrate:remote` applies the migrations that ship **inside the package** (`migrations_dir`
@@ -607,9 +606,13 @@ per-environment step: for a named env, run `wrangler d1 migrations apply <name>-
 --env testnet`, likewise `--env production`. A Worker deployed against an unmigrated D1 fails on
 its first claim.
 
-**The Custom Domain in `routes` must equal `ORACLE_HOSTNAME`** for the env you deploy: callers
-verify you by fetching `https://<ORACLE_HOSTNAME>/.well-known/did.json`, and the engine binds its
-records to that did:web.
+**`ORACLE_HOSTNAME` must be the host the env is served from**: callers verify you by fetching
+`https://<ORACLE_HOSTNAME>/.well-known/did.json`, and the engine binds its records to that did:web.
+A custom domain is optional. Without one, delete that env's `routes` entry and set
+`ORACLE_HOSTNAME` to the Worker's free `<worker name>.<your account subdomain>.workers.dev` host
+(wrangler prints it on deploy; with no `routes`, wrangler serves `workers.dev` by default). With
+one, the Custom Domain in `routes` must equal `ORACLE_HOSTNAME`. Pick the host before `oracle
+init`: it IS the oracle's identity, so moving to a custom domain later means a new did:web.
 
 ### Declaring yourself on chain
 
@@ -726,9 +729,6 @@ the exception** — the hosted subscriptions API resolves the ENGINE's did:web t
 delegation, so that leg needs a public tunnel in front of the engine, with the tunnel host set as
 the engine's hostname everywhere and the CAR minted for that same audience.
 
-The full runbook, plus the two engine-conformance harnesses:
-[`packages/eval-oracle/dev/README.md`](https://github.com/ixoworld/eval-oralce/blob/main/packages/eval-oracle/dev/README.md).
-
 ## Repository layout
 
 ```text
@@ -784,6 +784,6 @@ symlinks are not packed). CI diffs them — change one, copy it to the other.
 
 ## Status
 
-Published on npm: `@ixo/decision-oracle` 0.2.21 and `@ixo/decision-oracle-client` 0.1.1.
+Published on npm: `@ixo/decision-oracle` 0.2.22 and `@ixo/decision-oracle-client` 0.1.1.
 
 Apache License 2.0: `LICENSE` at the repo root and in each package.

package/docs/api.md

@@ -1629,7 +1629,7 @@ once deployed. Every value is validated by Zod at isolate start, so a bad env fa
 | `EVAL_ENGINE_HOSTNAME` | vars | per network | The engine you ask for decisions. A host you **call** — its `did:web` is the invocation audience. Set it for a local engine or a tunnel |
 | `CLAIM_BOT_URL_OVERRIDE` | `.dev.vars` | derived | Local harnesses only — the bot URL is normally derived as `https://claim.bot.<homeserver domain>` |
 | `IXO_CLIENT_SEQUENCE_MIN_DELAY_MS` | vars | `1000` | Read by the sequence keeper off `env`: the minimum gap between two sequence allocations |
-| `ORACLE_HOSTNAME` | vars | **required** | *Your* canonical `did:web` host. Every inbound invocation's audience is pinned to this, never the request `Host`; it is also the issuer of every invocation you mint. It must equal the Custom Domain in `routes` for that env |
+| `ORACLE_HOSTNAME` | vars | **required** | *Your* canonical `did:web` host. Every inbound invocation's audience is pinned to this, never the request `Host`; it is also the issuer of every invocation you mint. It must equal the Custom Domain in `routes` for that env, or, with no `routes`, the env's `<worker>.<account>.workers.dev` host |
 | `ORACLE_DID` | vars | **required** | `did:ixo:<address>` — the runtime chain identity |
 | `ORACLE_ADDRESS` | vars | **required** | Must be the `ORACLE_SECP_MNEMONIC` wallet's address — asserted at first use, fails loud |
 | `ORACLE_MATRIX_USER_ID` | vars | **required** | The MXID derived from `ORACLE_DID` (cross-checked, never re-derived) |

package/docs/guide.md

@@ -103,9 +103,12 @@ asserted against the mnemonic before the first signature: a hand-typed one that
 never signs as someone else.
 
 Also set, in `wrangler.jsonc` `vars`: `IXO_NETWORK`, and `ORACLE_HOSTNAME` — the host your
-`did:web` is served from (`localhost:8787` while developing). **It must equal the Custom Domain in
-`routes` for any environment you deploy**, because callers resolve you by fetching
-`https://<host>/.well-known/did.json`. And in `.dev.vars`: `UNIQUE_HMAC_KEY`, any long random
+`did:web` is served from (`localhost:8787` while developing). **It must be the host each
+environment you deploy is served from**, because callers resolve you by fetching
+`https://<host>/.well-known/did.json`. A custom domain is optional: delete that env's `routes`
+entry and the Worker is served on its free `<worker name>.<account subdomain>.workers.dev` host —
+set `ORACLE_HOSTNAME` to that. With a custom domain, it must equal the Custom Domain in `routes`.
+Pick the host before `oracle init` (§10): it is the oracle's identity. And in `.dev.vars`: `UNIQUE_HMAC_KEY`, any long random
 string, if the rubric you serve declares a `unique` rule.
 
 Both of these keys are, at this point, only strings in your files. `decision-oracle oracle init` (§10)
@@ -983,8 +986,9 @@ Before shipping an environment, check all four:
 
 1. the **D1 and KV ids** in that env's block are real (named envs inherit nothing — every binding
    and the whole `vars` block is redeclared per env);
-2. the **Custom Domain** in `routes` equals that env's `ORACLE_HOSTNAME`, character for character —
-   callers resolve your `did:web` by fetching it;
+2. that env's `ORACLE_HOSTNAME` is, character for character, the host it is served from — the
+   **Custom Domain** in `routes`, or, with no `routes`, its `workers.dev` host — callers resolve
+   your `did:web` by fetching it;
 3. every **secret** is set with `wrangler secret put` for that env — including
    `ORACLE_MATRIX_ACCESS_TOKEN`, the one `oracle init` wrote into your local `.dev.vars`
    (`wrangler secret put ORACLE_MATRIX_ACCESS_TOKEN`, then paste it);
@@ -1529,7 +1533,7 @@ own retries, and a terminal failure clears it.
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `401` on any `/v1` call | The invocation's audience is not `did:web:<ORACLE_HOSTNAME>`, or `/.well-known/did.json` is not served from that host | Make `ORACLE_HOSTNAME`, the Custom Domain and the audience the same string. Check `SERVICE_ED25519_MNEMONIC` is set |
+| `401` on any `/v1` call | The invocation's audience is not `did:web:<ORACLE_HOSTNAME>`, or `/.well-known/did.json` is not served from that host | Make `ORACLE_HOSTNAME`, the served host (Custom Domain or `workers.dev`) and the audience the same string. Check `SERVICE_ED25519_MNEMONIC` is set |
 | `401` from the claim bot, the UCAN Store or the VFS claims lane (`claim.store-denied`), on an invocation minted as `did:ixo:…` | That DID has no IID document, or the `SERVICE_ED25519_MNEMONIC` key is not a verification method on it — the resolver has nothing to check the signature against | Re-run `oracle init --protocol <protocol did> --kit-url https://<your host> --yes`: every step already done says `skip`, so only the missing `iid` / `key` writes anything. (`--protocol` and `--kit-url` are always required, and `--only <step>` without `--yes` is still just a dry run) |
 | `bunx @ixo/decision-oracle@<version>` says `No version matching … found (but package exists)` right after a release | bun's cached copy of the package list is older than the release | `bun pm cache rm`, then run it again — or `BUN_INSTALL_CACHE_DIR=$(mktemp -d) bunx @ixo/decision-oracle@<version> …` |
 | A protocol shows as "Unnamed" in the portal, the console or the Openhands app | It has no `#pro` profile: `publish-protocol` writes one only with `--name` | `publish-protocol --phase profile --entity <protocol did> --rubric <file> --form <file> --name "<name>" [--description "<text>"] --yes` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "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": [
@@ -12,14 +12,7 @@
     "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",
+  "homepage": "https://docs.ixo.world/build-an-oracle/decision-oracle",
   "type": "module",
   "exports": {
     ".": {

package/skills/create-oracle/SKILL.md

@@ -97,8 +97,14 @@ it in an agent session, or the mnemonic lands in the transcript.
   `wrangler.jsonc` `vars` (top level and every env), not `.dev.vars`.
 
 `ORACLE_HOSTNAME` (the host the did:web is served from) is `localhost:8787` in `.dev.vars` for local
-dev ONLY. Each deployed env's host lives in that env's `wrangler.jsonc` `vars` and must equal its
-Custom Domain in `routes`; a per-env secrets file (`.dev.vars.<env>`) must NOT carry a localhost
+dev ONLY. Each deployed env's host lives in that env's `wrangler.jsonc` `vars` and must be the
+host that env is served from. **A custom domain is optional**: without one, delete that env's
+`routes` entry (with no `routes`, wrangler serves the Worker on `workers.dev`; `"workers_dev": true`
+says so explicitly) and set `ORACLE_HOSTNAME` to the free `<worker name>.<account subdomain>.workers.dev`
+host — the env's `name` (e.g. `<project>-devnet`) plus the account's workers.dev subdomain
+(dashboard → Workers & Pages; the first deploy prints the URL). With a custom domain,
+`ORACLE_HOSTNAME` must equal the Custom Domain in `routes`. Choose before `oracle init`: the host IS
+the did:web, so changing it later is a new identity. A per-env secrets file (`.dev.vars.<env>`) must NOT carry a localhost
 `ORACLE_HOSTNAME`, or `engine register --env-file .dev.vars.<env>` registers localhost. Also put
 `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
@@ -322,8 +328,9 @@ bun run deploy:devnet            # or deploy:testnet / deploy:production (`--env
 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
+Before deploying: the D1/KV ids for that env are real, that env's `ORACLE_HOSTNAME` is the host
+it will be served from (its Custom Domain in `routes`, or, with no `routes`, its `workers.dev`
+host), 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
@@ -389,7 +396,7 @@ the required fee (`pricing.byProtocol` for that collection's protocol, else the
 | 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` |
+| Hosts | the did:web host per env (it IS the identity): a custom domain, or the free `workers.dev` host | `ORACLE_HOSTNAME`, `routes` (none for `workers.dev`) |
 | Contact | the address that gets pause / review notices | `register --contact-email` |
 
 ## Safety rules
@@ -417,7 +424,7 @@ the required fee (`pricing.byProtocol` for that collection's protocol, else the
 | Guessing `EVALUATION_MIN_AMOUNT` | ask what the collection's on-chain evaluation payment is (or will be) — set too high and register 402s |
 | No `EVALUATION_DENOM` in the mainnet env | the worker refuses to start — set both vars in every env you deploy |
 | `allowAiChecks: false` while the work order declares AI checks | every `ai` fact freezes `error` and the rubric's `onError` decides — ask first |
-| `ORACLE_HOSTNAME` ≠ the deployed Custom Domain | callers resolve the did:web by fetching that host — they must be the same string |
+| `ORACLE_HOSTNAME` ≠ the host the env is served from (its Custom Domain, or its `workers.dev` host) | 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, the console and the Openhands app show a placeholder — ask the provider for a logo (URL or image file) and pass `--logo` |

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

@@ -46,7 +46,7 @@ is the package CLI.
 ### 0. Prerequisites
 
 ```bash
-bunx wrangler whoami                        # the Cloudflare account that owns your host's zone
+bunx wrangler whoami                        # the Cloudflare account the oracle deploys to
 bunx decision-oracle login --network devnet     # the OWNER's AuthHub session — once
 ```
 
@@ -55,7 +55,7 @@ bunx decision-oracle login --network devnet     # the OWNER's AuthHub session
   Put the session's OWN DID (`did:ixo:<address>` — `login` prints the address) in
   `ORACLE_ADMIN_DIDS` in every `vars` block of `wrangler.jsonc`. The example ships IXO's DID there —
   a copy of it must replace it with the owner's.
-- The account must hold the zone of the host, or the Custom Domain cannot attach. If `whoami` shows another account, stop and say so (**HUMAN**).
+- A custom domain is optional. Without one, delete each env's `routes` entry and set that env's `ORACLE_HOSTNAME` to the Worker's free `<worker name>.<account subdomain>.workers.dev` host (the first deploy prints it). With one, the account must hold the zone of the host, or the Custom Domain cannot attach — if `whoami` shows another account, stop and say so (**HUMAN**). Either way the host IS the did:web: pick it before `oracle init`.
 
 ### 1. The protocol (example: publish `protocol/`; a provider: their protocol's DID)
 
@@ -313,13 +313,13 @@ Decision Console shows the price and card eligibility read-only.
 
 | 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 |
+| 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 host the env is served from (its Custom Domain, or its `workers.dev` host), 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 facilitator finds no active plan for the oracle: it is not registered with the engine (step 6 — registered, it runs on Standard at once), or, for an IXO-run oracle, IXO has not activated its plan (**HUMAN**: ask IXO). A way to pay whose payee is unset (`EARNINGS_ADDRESS` for PAY / USDC on IXO, `EARNINGS_BASE_WALLET` for USDC on Base) is simply not offered |
-| Not listed in the console | not registered with the engine (step 6), or not payable (the row above); or the host is not a `*.ixo.earth` Custom Domain; or `CORS_ORIGINS` lacks `https://decision-console.devnet.ixo.earth` |
+| Not listed in the console | not registered with the engine (step 6), or not payable (the row above); or `https://<ORACLE_HOSTNAME>/.well-known/did.json` does not answer; 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 |

package/templates/project/README.md

@@ -143,8 +143,10 @@ under `/v1` requires a UCAN invocation addressed to `did:web:<ORACLE_HOSTNAME>`.
 bun run deploy:devnet         # or deploy:testnet / deploy:production
 ```
 
-The Custom Domain in `routes` must equal `ORACLE_HOSTNAME` — the did:web document is served from
-it, and that is how anyone verifies who you are.
+`ORACLE_HOSTNAME` must be the host the env is served from — the did:web document is served from
+it, and that is how anyone verifies who you are. A custom domain is optional: with no `routes`
+entry, the Worker is served on its free `<worker name>.<account subdomain>.workers.dev` host, and
+`ORACLE_HOSTNAME` is that host. With one, it must equal the Custom Domain in `routes`.
 
 `GET /v1/info` only answers a portal that already knows your host. For discovery that starts from
 the protocol, declare yourself on chain — an oracle entity, a `#eval` service pointing at your

package/templates/project/wrangler.jsonc

@@ -5,7 +5,9 @@
   "compatibility_date": "2026-07-07",
   "compatibility_flags": ["nodejs_compat"],
 
-  // The Custom Domain IS the did:web identity — it must equal ORACLE_HOSTNAME below.
+  // The host IS the did:web identity — ORACLE_HOSTNAME below must be the host the Worker is served
+  // from. A custom domain is optional: with no `routes`, the Worker is served on its free
+  // `<name>.<account subdomain>.workers.dev` host — set ORACLE_HOSTNAME to that.
   // "routes": [{ "pattern": "<your ORACLE_HOSTNAME>", "custom_domain": true }],
 
   // D1 is the oracle's database: the ledger tables the package owns. `migrations_dir` points INTO
@@ -156,7 +158,8 @@
 
     // THIS oracle's did:web host — the audience every inbound UCAN invocation must name, and the
     // issuer of every invocation this oracle mints. It must equal the Custom Domain in `routes`
-    // for the env you deploy: callers resolve you by fetching https://<host>/.well-known/did.json.
+    // (or, with no `routes`, the env's `workers.dev` host) for the env you deploy: callers resolve
+    // you by fetching https://<host>/.well-known/did.json.
     "ORACLE_HOSTNAME": "<REPLACE: the host your did:web is served from>",
 
     // This oracle's PUBLIC chain identifiers, printed together by `bunx decision-oracle derive`.
@@ -231,7 +234,8 @@
       // keeps the deployed name explicit and independent of the top-level one.
       "name": "{{name}}-devnet",
       // The Custom Domain IS the identity: it must equal ORACLE_HOSTNAME below. Declared here so
-      // the deploy attaches it (and its DNS record) instead of it being a dashboard step.
+      // the deploy attaches it (and its DNS record) instead of it being a dashboard step. Optional:
+      // delete `routes` to serve on the free workers.dev host, and set ORACLE_HOSTNAME to that.
       "routes": [{ "pattern": "<REPLACE: your devnet host>", "custom_domain": true }],
       "vars": {
         "ENVIRONMENT": "staging",
@@ -340,7 +344,8 @@
       // keeps the deployed name explicit and independent of the top-level one.
       "name": "{{name}}-testnet",
       // The Custom Domain IS the identity: it must equal ORACLE_HOSTNAME below. Declared here so
-      // the deploy attaches it (and its DNS record) instead of it being a dashboard step.
+      // the deploy attaches it (and its DNS record) instead of it being a dashboard step. Optional:
+      // delete `routes` to serve on the free workers.dev host, and set ORACLE_HOSTNAME to that.
       "routes": [{ "pattern": "<REPLACE: your testnet host>", "custom_domain": true }],
       "vars": {
         "ENVIRONMENT": "staging",