@artblocks/abx-cli 0.1.0-alpha.32 → 0.1.0-alpha.34

package/skill/reference/diagnose.md

@@ -0,0 +1,165 @@
+# Diagnosis and recovery
+
+Use this reference when a command fails, a project is incomplete, metadata is wrong, a render is
+missing, storage is propagating, a remote rejects a request, or an agent is tempted to add retries.
+
+## Contents
+
+- [Diagnose one state transition at a time](#diagnose-one-state-transition-at-a-time)
+- [State-to-action table](#state-to-action-table)
+- [Nonces and serialized writes](#nonces-and-serialized-writes)
+- [Incomplete deployments](#incomplete-deployments)
+- [RPC and chain failures](#rpc-and-chain-failures)
+- [Metadata and resolution failures](#metadata-and-resolution-failures)
+- [Storage failures](#storage-failures)
+- [Render and effects failures](#render-and-effects-failures)
+- [Secret-safe reporting](#secret-safe-reporting)
+
+## Diagnose one state transition at a time
+
+1. Capture the command, exit code, typed error/status, active chain, target address, and signer lane.
+   Never capture secret values or complete credential-bearing URLs.
+2. Run `abx version` and `abx doctor`; correct binary/skill drift before interpreting behavior.
+3. Run the relevant read command (`state`, `tokens`, `tokenuri`, `contracturi`, `status`, `verify`,
+   `remote`, or `storage status`) to establish current state.
+4. Classify the result as nonterminal, terminal/configuration, terminal/on-chain, or integrity fault.
+5. Choose one documented transition. Re-read state after it. Stop when the state changes or a human
+   decision is required.
+
+Do not run the same failed write with random flags, switch representations silently, rotate providers
+without evidence, or wrap the CLI in an unbounded retry loop.
+
+## State-to-action table
+
+| Observation | Meaning | Next action |
+|---|---|---|
+| `indexing`, `queued`, `running`, `propagating` | nonterminal work | use the command's `--watch`/status and wait |
+| `401` from a remote | token absent/invalid | replace the configured credential, then probe once |
+| `403` from a remote | credential lacks scope | fix provider authorization; do not rotate blindly |
+| wrong chain id | endpoint/config mismatch | correct `ABX_CHAIN`/RPC; do not deploy another contract |
+| no code at address | wrong chain/address or incomplete deploy | verify explorer/chain and deploy state before retrying |
+| transaction reverted | on-chain rule rejected the exact call | inspect typed reason/tx; change intent or inputs, not nonce |
+| integrity/hash mismatch | served bytes differ from commitment | stop publication; restore committed bytes or explicitly repoint |
+| placeholder image | image surface not published/wired | choose renderer, public image base, or resolver/effects path |
+| storage accepted but gateway 404 | propagation may be pending | `storage status`; wait if propagating |
+| empty historical reconstruction | pruning/range-capped RPC may have answered `[]` | put a full-history endpoint first, then re-index |
+| skill version/name warning | agent membrane is stale or duplicated | run the exact project/global `abx skill install` commands shown |
+
+## Nonces and serialized writes
+
+ABX already owns nonce handling. A hot sender reads pending and latest counts once, uses the safe
+maximum, increments locally for the sequence, waits for newly deployed code before dependent calls,
+pins gas with bounded estimation, and reports a reverted receipt as an error.
+
+The operational rule is therefore simple: **one EOA, one write process at a time**. Two processes can
+start from the same nonce before either sees the other's pending transaction. If contention occurred:
+
+1. Stop additional writers.
+2. Read nonce coherence with `abx doctor` and check pending/mined transactions on the active chain.
+3. Wait for the pending transaction or resolve it using the wallet's standard replacement flow.
+4. Re-read project state; resume only the missing documented step.
+
+Do not add “nonce too low” retries, increment a guessed nonce, or send concurrent replacement
+transactions from the agent. Those layers fight the CLI's serializer and can duplicate value-bearing
+operations.
+
+## Incomplete deployments
+
+A failed multi-transaction code-project setup can leave a valid clone with missing setup legs. Use
+`deploy-code --resume <address>` only where the capability output says resume is supported. It reads
+the contract and sends only missing work; it is not a general “try deploy again” switch.
+
+Before resume:
+
+- verify the address, chain, contract family, owner, and original artifacts;
+- use the same normalized script/dependencies/schema/renderer plan;
+- read the resume dry run and confirm every proposed transaction;
+- ensure no second writer is operating the same EOA.
+
+EditionCode resume is not currently supported. Inspect state and stop for an explicit recovery or new
+deployment decision rather than applying the 721 recipe.
+
+## RPC and chain failures
+
+Use `abx doctor` rather than probing secret endpoints manually. Distinguish:
+
+- connectivity/rate limit: endpoint did not provide a usable response;
+- wrong network: endpoint chain id differs from `ABX_CHAIN`;
+- shallow history: recent reads work but old logs are unavailable;
+- range cap: large `eth_getLogs` queries fail or return misleading empty ranges;
+- read-gas cap: a large on-chain `tokenURI` call exceeds that endpoint's allowance;
+- stale distributed view: pending nonce or newly deployed code lags the endpoint's own head.
+
+Put the best archive endpoint first. Fallback transports can accept an empty successful answer from a
+pruned endpoint and never reach a healthy second endpoint. For large on-chain content, state whose RPC
+was measured; do not generalize creator reach to marketplace reach.
+
+If a write simulation or estimate reverts, preserve the exact representation the creator chose. Use a
+read-only call/CLI diagnostic to surface the contract reason. Never silently replace an on-chain reader
+with an off-chain URL merely to make the command pass.
+
+## Metadata and resolution failures
+
+Start from the contract, not a constructed URL:
+
+1. `abx state <addr>` — contract family, renderer, owner powers, schemas/locks.
+2. `abx tokenuri <addr> --token <id>` — actual on-chain URI and decoded metadata.
+3. `abx contracturi <addr>` — actual collection URI.
+4. `abx verify <addr> --json` — commitments, chain-completeness, placeholders, public bytes.
+
+Then follow the failing surface:
+
+- URI absent/wrong: inspect URI pointer/renderer and deploy configuration.
+- Metadata resolves but image fails: inspect image representation and public locator/gateway.
+- Animation fails: inspect generated document, dependencies, target token data, and hosting.
+- Traits missing: inspect decoded `attributes`, renderer/effects output, and publication—not only
+  program console traits.
+- Attachments absent: verify resolver artifacts enumeration; bare on-chain metadata cannot enumerate
+  arbitrary keys.
+
+Use `refresh` only after the current path is correct. Refreshing a broken URI makes a marketplace fetch
+the same broken document again.
+
+## Storage failures
+
+Run `abx storage show --check` with the intended backend overrides. For cloud, inspect both the private
+put endpoint and public read base by hostname only; never print credentials. For IPFS, separate pinning
+from gateway retrieval. For Arweave, use structured status to distinguish propagation from failure.
+
+Retry policy:
+
+- accepted/deduplicated upload: success; do not upload again;
+- propagating locator: wait using status backoff;
+- terminal authentication/configuration error: fix configuration before one new attempt;
+- integrity mismatch: stop and restore/republish the committed bytes;
+- transient provider failure: use the client's bounded retry or retry once after status evidence;
+- repeated unknown failure: stop and report the smallest redacted reproduction.
+
+Do not switch backend or public locator without telling the creator; that changes the custody plan.
+
+## Render and effects failures
+
+A still is derived state keyed by current inputs. Diagnose the graph in order:
+
+1. Token/id is minted and indexed.
+2. Live document loads for that real id.
+3. Dependencies and PostParams resolve.
+4. Effects runner is authenticated and receives the job.
+5. Render bytes are non-placeholder and uploaded to public storage.
+6. Resolver receives/publishes the locator and traits.
+7. Token metadata exposes them.
+
+Use `abx render --force` only when an existing render is known bad or stale; a plain render should
+idempotently skip an existing current artifact. A PostParam change produces a new inputs hash; verify
+the watcher or run the explicit one-shot path. Solidity image renderers have no effects job—diagnose
+their on-chain call instead.
+
+## Secret-safe reporting
+
+Include command name, CLI version, chain key, redacted host labels, contract address, transaction hash,
+exit code, typed status/error, and expected versus observed state. Exclude `.env`, keys, tokens, JWKs,
+wallet-session URLs, query strings, and raw provider responses containing request headers.
+
+If the same blocking state survives three evidence-based transitions, stop. Report what was proven,
+what was ruled out, and the exact external decision or state change required. Repetition is not
+progress.

package/skill/reference/hosting.md

@@ -1,182 +1,204 @@
-# Hosting infrastructure
+# Hosting, storage, and remote operation
 
-[← back to SKILL.md](../SKILL.md)
+Use this reference when a project needs public resolution, managed remote service, creator-operated
+resolver/effects, storage configuration, render publication, lifecycle monitoring, or migration.
 
-## Storage backends (byte custody)
+## Contents
 
-Storage is **stateless** — there's no config file. Choose a backend **per command** with flags (`--backend …`), or declare defaults in `.env` (`ABX_STORAGE_BACKEND`, `ABX_IPFS_GATEWAY`, `ABX_S3_BUCKET`, …); secrets stay in `.env`. Resolution is `flag → env → default`. Verify with `abx doctor`; `abx storage show` prints the resolved config with provenance.
+- [First decide whether a host exists](#first-decide-whether-a-host-exists)
+- [Choose managed or creator-operated resolution](#choose-managed-or-creator-operated-resolution)
+- [Choose storage independently](#choose-storage-independently)
+- [Operate resolver and effects services](#operate-resolver-and-effects-services)
+- [Use lifecycle states](#use-lifecycle-states)
+- [Migrate without losing canonicity](#migrate-without-losing-canonicity)
 
-| Backend | Guarantee | Choose (per command, or `.env`) | Secret in `.env` |
-|---|---|---|---|
-| **`fs`** (default) | Operator-held, local disk | — | — |
-| **`cloud`** | S3-compatible: AWS S3 / R2 / B2 / MinIO | `--backend cloud --endpoint <url> --bucket <b> --region <r>` (or `ABX_S3_ENDPOINT`/`ABX_S3_BUCKET`/`ABX_S3_REGION`) | `ABX_S3_ACCESS_KEY_ID`, `ABX_S3_SECRET_ACCESS_KEY` |
-| **`ipfs`** | Decentralized (CID) | kubo: `--backend ipfs --mode kubo --api-url http://127.0.0.1:5001 --gateway http://127.0.0.1:8080` · pinata: `--backend ipfs --mode pinata --gateway https://<you>.mypinata.cloud` | `PINATA_JWT` (pinata mode) |
-| **`arweave`** | Pay-once permanent | `--backend arweave` (Turbo default; or `ABX_STORAGE_BACKEND=arweave`) | the Turbo key (auto-managed) |
+## First decide whether a host exists
 
-All backends verify via the on-chain keccak commitment wherever the bytes live. **What a marketplace fetches is always an HTTPS gateway URL** → IPFS/Arweave custody needs a *public* gateway. The two public **floors**, used whenever a project states no preference, are:
+Do not ask “where should we host?” until the public surfaces require a host.
 
-| Scheme | Floor (used when the project sets nothing) |
-|---|---|
-| `ipfs` | `https://ipfs.io/ipfs/` |
-| `arweave` | `https://arweave.net/` |
+No ABX resolver is required when:
 
-Do not guess these and do not substitute the *upload* gateway for them — a project that uploaded through Pinata still **serves** from `ipfs.io` unless it said otherwise, and telling a creator otherwise gives them a URL their token does not use. A `127.0.0.1` gateway is preview-only (the CLI warns); the shared `gateway.pinata.cloud` is rate-limited — use a **dedicated** gateway for anything real, and set it with `--ipfs-gateway` (deploy) or `abx set-gateway` (after).
+- static bytes and metadata resolve on-chain;
+- on-chain JSON points at public Arweave/IPFS/cloud media;
+- Solidity field renderers compute every required metadata surface on-chain.
 
-**A resolver adds nothing marketplace-facing to a project that already resolves on-chain — say so before you set one up.** The docs below explain when a resolver *helps* (mutable metadata, code drops needing rendering, off-chain traits); the inverse is just as load-bearing and was missing. Check first: `abx state <addr>` printing `renderer on-chain (0x…)` means `tokenURI` answers from the chain, so wallets and marketplaces read **that** document and never touch a resolver. Registering with one is still worth doing for **indexing, the live view, and managed rendering** — but it will not change a single thing a collector sees, and a creator told to "put it on a hosted service so it shows up properly" needs to hear that plainly rather than be walked through a setup that changes nothing. (`abx add --remote` now says this too.) Conversely, a project whose renderer is **off-chain** genuinely depends on a resolver, and that is the case the rest of this page is about.
+A resolver is useful or required when:
 
-**Which gateway, and who can change it.** For a `keccak256`-custody field the resolver builds that URL from the backend's own gateway. For an `ipfs`/`arweave` field — what `--onchain-uri --backend ipfs|arweave` writes — the chain holds only the CID/txid, and the prefix comes from the collection's `abx_gateway_ipfs` / `abx_gateway_arweave` setting (public defaults when unset). Set it at deploy with `--ipfs-gateway` / `--arweave-gateway` (plain `--gateway` seeds the one matching your backend), and change it any time with **`abx set-gateway <addr> --ipfs <prefix> --arweave <prefix>`** — one tx, every token, no re-upload, and it works on fields that are already locked. `--gateway` remains the UPLOAD/probe gateway; these are the SERVING one, and they are the same value in almost every project.
+- metadata must remain operationally editable;
+- a JavaScript/build project needs a hosted live document;
+- marketplace stills/traits are produced by an effects runner;
+- attached artifacts must be enumerated and fetched;
+- large on-chain content needs an HTTP reader in front of endpoint-dependent `eth_call` execution;
+- a project needs indexed status/dashboard/API surfaces.
 
-**Code projects (directory mode) need a gateway that serves HTML.** A `deploy-code --code-dir` build's live view 302-redirects to `<gateway>/ipfs/<cid>/index.html` — and the **shared Pinata public gateway blocks HTML** (`ERR_ID:00023`, "HTML content cannot be served through the pinata public gateway"). So a code directory drop requires a **dedicated** Pinata gateway (paid) or **Arweave** (`https://arweave.net` serves HTML). Static image directories (`deploy-series`) are unaffected — only the executable HTML build hits this.
+Storage can be on-chain while resolution is hosted, or external while metadata resolution is
+on-chain. Keep those axes separate.
 
-**Durability is not the same across backends — educate the creator by name:**
-- **`arweave`** — pay once, permanent. Arweave's storage endowment funds retention for centuries (~200 years at current economics); the bytes resolve as long as the network and any gateway are up. Nothing to renew, nothing to re-pin. The strongest "never lapses" custody.
-- **`ipfs`** — **only as durable as the pin.** The token's `image` resolves through the creator's Pinata (or kubo) gateway; if the pin is dropped — account lapses, billing fails, node goes offline — the bytes can become unretrievable and the image breaks. IPFS is *content-addressed* (the CID proves integrity) but **not self-storing** (someone must keep hosting the bytes). Tell the creator plainly: with IPFS they've taken on an ongoing pinning responsibility. Mitigate by pinning to a durable service and not letting it lapse — or prefer `arweave` and be done.
-- **`cloud`/`fs`** — durable only while the creator maintains the bucket/disk; centralized, mutable.
-- **Backends are swappable** — the on-chain keccak is the anchor, so bytes are portable: re-upload to the new backend and re-point the `image` field (`abx set-field <addr> --field image …`), then `abx verify` confirms the served bytes still match the on-chain hash. For a hosted-resolver project, `abx migrate` re-pins node-custody images to a durable backend as part of the move (see [operating.md](operating.md)). Re-pointing is an owner-signed tx, so keep the owner wallet secure. Starting on `fs`/`ipfs` and moving to `arweave` later is fine; just don't let an interim backend lapse before the move.
+## Choose managed or creator-operated resolution
 
-### Arweave via Turbo — the easy permanent path (read before quoting setup)
+Both routes implement the same public resolver contract. The token holds a base URI; the operator
+reconstructs canonical state from chain and serves metadata/live/data surfaces.
 
-`arweave` defaults to the **Turbo** provider (ArDrive). For small content it needs **no setup and costs nothing** — no wallet dashboard, no JWT (don't send anyone to `app.arweave.org`). How it works:
+### Managed remote
 
-- **Identity is a lane (`--storage-signer`) — Turbo is multi-chain, so credits attach to whichever identity signs the upload.** Three choices, mirroring the tx signing lanes:
-  - **`arweave`** *(default)* — a CLI-managed Arweave key auto-generated at `.abx-self-host/arweave-key.json` the first time a command actually needs it — an upload, or a `storage balance` / `storage topup` (so a creator can fund the identity *before* uploading). Reads that never need a signer (`doctor`, `--dry-run`, `storage show`) do not create one. The address is printed with a back-it-up notice on creation. Reused across every upload/project; it signs *and* holds credits. Zero-config. Bring-your-own via `ARWEAVE_JWK` (inline) / `ABX_ARWEAVE_KEY_FILE` (path). **Back it up:** `abx storage backup-key --out <path>` (copies the file — the key is never printed to the terminal/log).
-  - **`--storage-signer eth`** — reuse the **`.env` EVM signing key** (`ABX_DEPLOYER_PK`) as the Turbo identity. Its ETH address holds the credits, so credits funded on that wallet's Turbo balance are spendable. Hot lane (key in `.env`).
-  - **`--storage-signer eth` + `--sign`** — the **browser wallet** signs each upload data-item via `personal_sign` (no gas, no funds move; the upload is paid from the wallet's Turbo credits), in the same sign session as the deploy tx. The key never leaves the wallet. *(New; the mechanism matches arbundles' `InjectedEthereumSigner` and is unit-tested at the CLI↔page contract, but the live MetaMask↔Turbo path wants a manual smoke test. If a live upload misbehaves, fall back to `--storage-signer eth` with a key, or fund the managed key.)*
-- **Under 100 KB → free**, permanent, zero setup. The CLI prints this from the file size (in `--dry-run` too).
-- **Over 100 KB → prepaid credits, one-time.** `abx storage balance` shows the funded address + credits; `abx storage topup --usd <n>` returns a Stripe checkout link. A **pre-upload balance guard** stops *before* the deploy if credits are short — printing the address + fund options — so a shortfall never fails mid-deploy after txs already landed. One-time payment, no recurring fee, nothing to re-pin (contrast `cloud`/`ipfs`). Credits are non-refundable.
-- **Credits attach to the IDENTITY, not "you".** With the default `arweave` lane, a top-up funds the CLI-managed Arweave address (derived from the key file) — a *different* identity from the ETH wallet used to sign deploys. So a fresh managed key shows **0 credits even if the creator "funded Turbo before"**: those old credits sit on whatever identity they funded. If they funded their **ETH wallet's** Turbo balance, reach it with `--storage-signer eth` (key) or `--storage-signer eth --sign` (browser). If they hold a funded **Arweave** key, import it via `ARWEAVE_JWK`/`ABX_ARWEAVE_KEY_FILE`.
-- **If the Stripe link fails**, fall back to Turbo's hosted top-up (`https://turbo-topup.com`) and fund the **exact address `abx storage topup` prints** (it accepts a recipient address, so credits still land on the intended identity). Not ideal, but it beats abandoning Arweave for IPFS on a link glitch.
+Use a named remote already configured in the environment rather than standing up duplicate
+infrastructure. Start with:
 
-#### When a Turbo upload fails — diagnose, don't guess
+```bash
+abx remote <name>
+```
 
-A failed upload is the #1 place an agent goes off the rails: it invents a cause and bails. Don't.
+`abx` is the built-in name for the first-party service at `services.abx.io`; it needs only
+`ABX_SERVICES_API_KEY`, not a remote URL variable. Read [services.md](services.md) for its verified
+signup, current access model, and provider-feedback path. Other providers use their configured name.
 
-- **Read the actual error and show the human verbatim.** The CLI prints Turbo's real message (incl. the raw response). **Never invent a cause** — "transient hiccup", "Turbo is down", "the browser path is new/flaky", "known issue per the docs" are hallucinations unless the error text says so. If you don't know, say "here's the exact error" and read it.
-- **"…has already been uploaded to this service!" is SUCCESS, not failure.** Turbo deduplicates identical bytes (same signer + bytes → same data-item id), so re-uploads (a retry, a redeploy, two identical images) return that sentence instead of JSON. The CLI treats it as the existing txid and continues. If you ever see it surface as an error, the toolkit is stale — don't work around it.
-- **Check BOTH balances before concluding "needs funding."** `abx storage balance --backend arweave` prints the managed key's balance **and** the deployer wallet's Turbo balance (Turbo exposes balance-by-address publicly — no key needed). The managed key showing 0 does NOT mean "top up": if the **wallet** has credits, use them (`--storage-signer eth`, or `+ --sign` for a browser wallet). The pre-upload funds guard does this check for you and recommends the wallet lane when it applies — checking only the managed key's 0 and pushing a top-up is the classic wrong turn.
-- **Don't reflexively push a $5 top-up or "switch to IPFS."** Both throw away what the creator chose (their funded wallet credits; permanence). Only top up if *neither* the managed key nor the wallet can cover the bytes — and **back up the managed key first** (`abx storage backup-key --out <path>`), since it will hold the credits you buy. Only suggest IPFS if they ask or Arweave is truly unavailable.
-- **A blind retry re-signs the same bytes → same dedup reply.** Retry only after you've identified and fixed the actual cause.
-- **Gateway swappable, integrity independent.** The on-chain keccak256 (or the CID itself) is the anchor; `arweave.net` is the default gateway (`--gateway` at upload, `abx set-gateway` for serving). A gateway issue is a re-point, never a lost asset.
-- **Provider swappable.** `--provider http-bundler --upload-url <bundler>` uses a dep-free token-authed endpoint you run (secret `ARWEAVE_UPLOAD_TOKEN`); funding then means "fund the wallet directly" (only Turbo tracks credits). Default to Turbo unless asked.
+This reports the service descriptor, supported chains, rendering policy, and authentication status.
+Do not infer provider capability from its hostname or marketing page.
 
-### Directory-base — image off-chain, JSON on-chain, no server (the medium/large static default)
+Interpret control-plane failures precisely:
 
-`abx deploy-series --onchain-uri --backend arweave` (or `ipfs`/`cloud`) puts the **image off-chain** while the **on-chain renderer** assembles the JSON — **no resolver to run**, the token self-resolves. How the CLI wires it:
+- `401` means the supplied token is missing, stale, or invalid; replace the credential.
+- `403` means the credential is recognized but lacks permission for this chain/project; fix provider
+  scope rather than rotating keys blindly.
+- a conformance failure means the service contract is incomplete or incompatible; do not register a
+  production launch until the failing assertion is understood.
 
-- **Uniform extension → O(1) directory.** Files are renamed to the token-id convention (`0.png`, `1.png`, …), uploaded as one IPFS directory pin (Pinata) / Arweave path manifest (Turbo), and a single collection-scope `image` field gets the **`url-template`** representation — `<gatewayBase>/{id}.png`. The renderer substitutes each id → one field renders the whole collection, any size. No per-token on-chain data.
-- **Mixed extensions → per-token `url`** fields (O(N)) — still no server. A uniform extension unlocks the single-template path; flag it if a folder is mixed.
-- **`cloud` (S3/R2/CDN)** works the same, but the signed-API host (`--endpoint`/`ABX_S3_ENDPOINT`, where uploads go) and the public read host (`--public-base`/`ABX_S3_PUBLIC_BASE`, also what `deploy-code --image-base` takes) are **different hosts by design** — one auth-only, one public (R2's own API endpoint is never public; its public URL is a separate `pub-<hash>.r2.dev` or custom domain you enable). **`abx storage show --check` proves the two agree** — a real PUT through the API + an unsigned GET through the public base (`abx doctor` runs the same probe). Files upload under a content-derived prefix → `<publicBase>/<prefix>/{id}.png`. **Caveat:** S3 is centralized, mutable, not content-addressed (no CID/txid root). Good if the creator already runs a bucket/CDN; IPFS/Arweave are the trustless/permanent options.
-- **Integrity** (IPFS/Arweave) comes from the content-addressed root (CID / manifest txid), not a per-token keccak. The gateway host is baked on-chain → moving gateways is a `set-field` (bytes stay put). Prefer a **dedicated** gateway.
-- **`url-template`** is a first-class representation ([spec](../../../../specs/protocol/onchain-metadata.md)); set by hand with `abx set-field <addr> --collection --field image --representation url-template --text "<gateway>/ipfs/<cid>/{id}.png"` then `abx set-renderer <addr>`.
+Register or operate a project using `--remote <name>` and monitor with `abx status --remote <name>`.
+If the provider advertises managed rendering, confirm it for the active chain/project. Otherwise the
+creator still owns the effects and storage path.
 
-## Managed providers — a resolver someone else runs (`--remote <name>`)
+Never invent a provider, signup flow, price, quota, or key source. If no configured provider exists,
+offer the fully supported creator-operated route.
 
-The other way to have a resolver: be a **customer** of a hosted provider instead of running a node — one base URL + one API key, no cloud account, no Dockerfile, nothing to keep alive. Same interface, same commands as self-hosting ([spec](../../../../specs/self-host-toolkit/remote-services.md)); a project moves between a provider and your own node with one re-point + re-register ([operating.md → Moving your hosting](operating.md#moving-your-hosting--two-cases-dont-conflate)).
+### Creator-operated resolver
 
-- **Named remotes.** Put the provider in `.env`: `ABX_REMOTE_<NAME>_URL=<base>` + `ABX_REMOTE_<NAME>_TOKEN=<api key>`. **`<NAME>` is YOUR label for the provider, not their legal name** — you pick it, you pass the same word to `--remote`. Normalization matches `ABX_RPC_URLS_<CHAIN>`: uppercase, runs of non-alphanumerics → `_`. So `--remote my-provider` reads `ABX_REMOTE_MY_PROVIDER_*`. For a multi-word brand, pick ONE short word and use it consistently — "Meridian Metadata" → `--remote meridian` + `ABX_REMOTE_MERIDIAN_URL`/`_TOKEN` (using `meridian metadata` would work too, as `ABX_REMOTE_MERIDIAN_METADATA_*`, but short is kinder to type). Then every remote command takes the name: `abx add <addr> --remote <name>`, ditto `index` / `forget` / `render` / `verify`, `abx migrate --from/--to <name>`, and owner-op nudges. Ad-hoc: `--remote <url> --remote-token <key>`. **Bare `--remote` stays the self-host default** (`ABX_PUBLIC_BASE_URL` + `ABX_REMOTE_SELF_TOKEN` — "self" is just another named remote) — nothing changes for a node you deployed. A named remote never falls back to `ABX_REMOTE_SELF_TOKEN` (or the resolver's own server-side `ABX_RESOLVER_ADMIN_TOKEN`), so neither secret can leak to a provider.
-- **Ask up front whether they serve YOUR domain.** Whatever base URL is baked on-chain is what a marketplace fetches. If that's a domain the creator controls (pointed at the provider), leaving later is a DNS change — no tx, no gas. If it's the provider's own hostname, leaving costs an **owner-signed `set-token-uri`/`set-contract-uri` tx**. Same exit either way, different price; worth knowing before you bake it, not after.
-- **Read the descriptor BEFORE registering — match the project to the provider.** `abx remote <name>` (or `curl <base>/.well-known/abx-service`, public, no key) prints what the service supports: **`chains`** must cover the project's chain (else registration is refused with `unsupported_chain`); **`render.attached`** means thumbnails/traits for code drops are rendered behind the provider — **skip `abx deploy-effects` entirely** (without it, renders are still yours: `abx render <addr> --remote <name>` or your own runner); **`auth.signupUrl`** is where a human gets a key.
-- **The API key is the human's step — a membrane ask, never a chat paste.** Say: *"This provider covers your chain and manages rendering. You'll need an API key from `<signupUrl>` — put it in `.env` as `ABX_REMOTE_<NAME>_TOKEN` (never paste it in chat) and I'll do the rest."* Then verify with `abx remote <name>`: it lists the projects visible to the key. **401** = the key is missing/wrong (check the var, rotate at the provider). **403** = the key is valid but not authorized for this contract/chain — provider-side scoping, not a typo; don't retry-loop, check the provider dashboard.
-- **The exit is guaranteed by the interface**, not by the provider's goodwill: registration is never load-bearing for resolution, and `abx migrate --from <provider> --to <anywhere>` reads only the provider's *public* endpoints — leaving is one config change plus (for a provider-hostname base) one on-chain re-point.
-- **Honesty:** no default provider is baked into the CLI, the SDK, or this skill, and the provider market is only starting to form. A creator with a provider key (or a named remote already in `.env`) should use it; otherwise **self-hosting (next section) is the fully-supported path today** and what the rest of this file assumes.
+Use `abx deploy-resolver --provider …` to generate hosting artifacts for the selected platform. The
+creator owns the cloud account, domain, secrets, monitoring, and upgrades. Review the generated
+configuration before deploying it; do not copy repository `.env` wholesale.
 
-## Self-hosted resolver — `abx deploy-resolver`
+The host needs read-only RPC access, storage access where applicable, and a stable public URL. Keep
+signing keys off the resolver. Use the project/state API and on-chain reconstruction instead of a
+private source-of-truth database.
 
-For the large/mutable default, when the creator runs the node themselves (the alternative to a managed provider above — same interface, they own the cloud account). `abx deploy-resolver --provider <fly|render|vps> --domain <meta.you.xyz>` scaffolds the artifact and prints the exact next steps, the DNS record, and the bake reminder. Providers: **fly.io** / **render** (Docker PaaS, custom domain) and a **VPS** (compose + Caddy auto-TLS). **Do not quote their plans or promise a free tier** — those move, and a stale claim in here becomes a stale claim to a creator; point at the provider's own pricing page and let them read it. The host is **read-only** — serves + accepts admin index-control, no signing key on it (writes are signed locally), so a compromised host can at worst serve wrong bytes (the keccak catches it). Prefer **a domain you control** (move = DNS, not a tx) — but without one the scaffold now bakes the **real platform hostname** (`<app>.fly.dev` / `<app>.onrender.com`) so the resolver works out of the box (add a custom domain later). It NO LONGER bakes a dead `<app>.example` placeholder, and the resolver **refuses to serve** an `.example`/placeholder base (or a localhost base in a hosted image, `ABX_HOSTED=1`) — a loud fail beats silently serving dead image/animation links. The one sub-decision is *which provider* (ask + recommend); you scaffold, the human owns the cloud account + domain.
+Prefer a creator-controlled domain in the on-chain base URI. Provider-specific hostnames work, but a
+custom domain makes migration a DNS operation rather than a contract operation. Tunnels and localhost
+are preview-only and must never be baked into a launch.
 
-**The artifact is fully self-contained.** `deploy-resolver` writes `deploy/<provider>/` with its OWN `Dockerfile` + `.dockerignore` + config (a production image installs the published CLI: `npm i -g --no-optional @artblocks/abx-cli`). **Run every next step from that dir.** You never supply, copy, or hand-edit a Dockerfile. **If a step seems to need a file from elsewhere (`../Dockerfile`, a `packages/` dir, the repo), STOP — that's a scaffold bug, not something to work around.** Report it; don't MacGyver it. (Local from-source/contributor dev sets `ABX_RESOLVER_SOURCE=1` → a build-from-source artifact instead, still self-contained; you don't set this.)
+After provisioning:
 
-**Never inline a secret into a command.** The generated steps **source from `.env`** (`set -a; . ../../.env; set +a` then `fly secrets set ABX_RPC_URLS="$ABX_RPC_URLS"`) — keep that shape. Never substitute a literal secret into command text; it must never appear in output or shell history.
+1. Run health/conformance checks.
+2. Register the contract with its deploy block when known.
+3. Wait for indexing readiness.
+4. Fetch contract and token metadata through the public URL.
+5. Verify byte commitments with `abx verify`.
+6. Mint only after required token-specific surfaces can become ready.
 
-`deploy-resolver` also **generates `ABX_REMOTE_SELF_TOKEN`** → your local `.env` (a secret — never printed, env-only; "self" is just the named remote for a node you run); the printed steps set that same value on the host under **its own** var name, `ABX_RESOLVER_ADMIN_TOKEN` (server-side config, unrelated to how any client authenticates). That token is what later lets `abx add <clone> --remote` tell the hosted node which contracts to index — the only new secret the hosted path adds, and it authorizes indexing control, not signing.
+## Choose storage independently
 
-**Gather the decisions in one pass.** The hosted path has a few small choices — provider, custom domain (or the provider-hostname tradeoff), app name, plus identity. Collect them together, then show the full plan; don't drip one question per turn. Once the human says "you run it," run the steps — don't flip between "here are commands" and "I'll do it."
+Storage is stateless configuration selected per command or through environment defaults. Inspect the
+resolved choice with:
 
-**Driving the deploy (fly/render/vps):** the human owns the cloud account. **Preflight the CLI FIRST — don't assume it's missing OR installed:** run `fly version` (is it there? `flyctl` and `fly` are the SAME binary — the modern alias is `fly`; don't tell them to install what they already have) and `fly auth whoami` (logged in?). Only send them to `fly auth login` — interactive, they do it — if `whoami` fails. Then run the generated steps for them. Deploys take minutes: run `fly deploy` and let it finish, don't background-and-poll. If it fails, read the actual error — a build that needs repo files means the artifact is wrong (above), not that you should copy things in.
+```bash
+abx storage show --check
+```
 
-## Render runner — `abx deploy-effects`
+| Backend | Good for | Operator responsibility |
+|---|---|---|
+| `fs` | local development | disk durability and no public reach by default |
+| `cloud` | mutable/fast public assets | bucket, auth endpoint, public read base/CDN, retention |
+| `ipfs` | content-addressed distribution | pinning and public gateway availability |
+| `arweave` | permanent external custody | upload identity/credits and propagation |
 
-A code project's marketplace still is rendered off-chain, so a **runner** (Playwright + Chromium — the resolver image stays browserless) must render each token's live view and hand the resolver the result. **A managed provider with `render.attached` in its descriptor does all of this for you — skip this section.** Self-hosting it: `abx deploy-effects --resolver-url <resolver>` scaffolds it for Fly (a self-contained `Dockerfile.effects` + `fly.toml` + vendored source), wired to the resolver and your storage home. **Decide where renders live up front** (`ABX_STORAGE_BACKEND`): **cloud (S3/R2 + a public base) · ipfs · arweave** — equal options, pick on cost/ops. **NOT** the default `fs` for a hosted setup, and this is now refused rather than warned: the runner HOLDS its render bytes and hands the resolver a URL, so a backend that can't name one has no lane (`abx deploy-effects` errors out, and the runner refuses to start). The runner **registers** each render with the resolver's control plane (`POST /v1/effect-artifacts`, gated by the same token — your local `ABX_REMOTE_SELF_TOKEN`, the resolver's own `ABX_RESOLVER_ADMIN_TOKEN` — index-control only, never signing), so it does NOT need to share the resolver's disk. What travels: a **locator** for the still (the resolver 302-redirects; it never proxies or fetches it), and the **content** for `traits` (≤64KB — traits stitch into the token JSON, so a pointer there could never work). It does not matter which scheme the URL uses: an `https://` gateway or bucket URL is a peer of `ipfs://`/`ar://`, since a lost render is a re-render. It only has to be fetchable by someone other than you — a loopback gateway or a presigned expiring URL is refused. Two topologies:
+Never silently fall back to `fs` when a selected backend is incomplete. Fix the missing configuration
+or change the plan explicitly.
 
-- **Locator bridge (default for a hosted drop):** runner on its own host + a public storage home; it registers locators, the resolver redirects. `deploy-effects` sets this up.
-- **Co-located:** runner beside the resolver sharing one backend/volume (no admin token needed — both read/write the same store). This is the escape hatch when there's no public storage home: `fs` is fine here.
+### Cloud
 
-One-shot without a service: **`abx render <addr> --remote <resolver>`** renders locally and registers with the hosted resolver — same requirement, so pass `--backend cloud|ipfs|arweave` (the default `fs` is refused before Chromium launches, naming the fix). Re-run any time: registration is idempotent and repairs a resolver that lost its rows without re-rendering. Optional immediacy: set `ABX_EFFECTS_URL` on the resolver so it pings the runner on re-index; the periodic sweep is the eventual floor regardless.
+Separate the authenticated S3/R2 API endpoint used for writes from the public HTTP base used by
+collectors. An R2 S3 endpoint is not a marketplace image URL. `--check` performs a real write/read
+round trip through the public base; require it to pass.
 
-## Local vs remote — two SEPARATE projection stores (read before deploying to a remote resolver)
+### IPFS
 
-A project is served only if it's in **the resolver's own** store. `abx deploy`/`abx add` (no `--remote`) index into **this machine's** store; a remote resolver — self-hosted or a managed provider — is a **different store** and doesn't learn about a contract just because you deployed it. A local deploy pointing its `tokenURI` at a remote resolver returns `{"error":"unknown project"}` for everyone — "works on my `serve`, broken for the world." **Bridge it:**
-- **Local resolver** (`abx serve` here): a local `deploy`/`add` already indexed it — done.
-- **Remote resolver** (baked URL is remote): after deploy run **`abx add <clone> --remote [name|url]`** to register + index it on the node (bare `--remote` defaults to `ABX_PUBLIC_BASE_URL` + `ABX_REMOTE_SELF_TOKEN`; a named remote uses its own `ABX_REMOTE_<NAME>_TOKEN`). Also **bridges** what the node can't derive: the durable `ipfs://`/`ar://` locator and off-chain traits. Post-deploy nudge (after a deferred mint) is **`abx index <clone> --remote`** (idempotent). Remove with **`abx forget <clone> --remote`**. Every remote command prints `REMOTE → <url>`.
+Pinning success and gateway retrieval are distinct. Use a durable pinning service and public gateway
+for launches. A local kubo node is suitable for development only. The on-chain field may hold the
+bare CID while a collection gateway preference chooses the serving prefix; `abx set-gateway` can
+change that prefix without changing the content.
 
-### Indexing status — `backfilling` is not a failure
+### Arweave
 
-A service may accept a registration and catch up **asynchronously** (a cold replay on a rate-limited RPC takes minutes). `abx add --remote` handles it: prints `registered — backfilling…`, polls, then prints the normal summary once the project is **`live`**. So a slow add is *slow*, not broken — don't re-run `add` to "retry" it (a re-POST never starts a second replay, but you'll just wait again). `--no-wait` returns immediately when you don't want to block.
+The accepted upload and a retrievable gateway object are separate lifecycle states. Use
+`abx storage status <locator> --json`; wait for `ready` instead of uploading duplicates during
+propagation. Upload deduplication is success, not an instruction to top up or switch backends.
 
-**Check anytime — same five words locally and remotely:** `abx status <address>` (this node) · `abx status <address> --remote <name> [--watch]` (a service) · `abx remote <name>` (roll-up: *"3 live, 1 backfilling, 1 failed (rpc_rate_limited)"*).
+Turbo credits attach to the signing identity. `abx storage balance` reports the managed identity and
+wallet-related lanes; choose the intended payer before funding. Back up the managed key using the
+dedicated command and never expose the JWK.
 
-**On a node YOU run**, two knobs shape this (both optional): `ABX_REGISTER_DEADLINE_MS` (default 8000) is how long a register may hold the HTTP request before answering "accepted, still catching up" and finishing in the background — the registration is durable either way, so this only decides who waits; and `ABX_STALE_LAG_BLOCKS` (default 5000) is how far behind chain head the watcher may fall before it reports its projects `stale`. A backfill interrupted by a restart is re-queued automatically on the next `abx serve` — you don't have to re-add it.
+### Publication bridge
 
-| status | what it means | what to do |
-| --- | --- | --- |
-| `queued` / `backfilling` | accepted, catching up (registration is already durable) | **wait** — poll, don't re-add |
-| `live` | caught up, tracking head | done |
-| `stale` | was live, now lagging — **still serving** old state | usually the service's RPC; investigate if it sticks |
-| `failed` | catch-up errored; retried with backoff | read the **class** (below); the registration survived |
+An effects runner stores rendered bytes, then publishes their locator to the resolver. The resolver
+usually redirects to that public object rather than proxying it. Therefore the storage backend must be
+reachable from both the runner and collectors. A local `fs` output from one machine is orphaned when
+the public resolver runs elsewhere.
 
-`failed` names a cause: **`rpc_rate_limited`/`rpc_unavailable`** = the *service's* RPC, not your key and not your address — it retries, so wait or tell the operator; **`not_abx_contract`** = wrong address/chain (or a provider that validates clones refusing a non-clone); **`internal`** = the operator's logs have it. Report the class verbatim to the user rather than guessing a cause.
+## Operate resolver and effects services
 
-**A `live` project with 0 events is a red flag, not a success** — a real ABX clone always emits a spine, so 0 events means the service scanned the wrong chain or its RPC didn't serve the logs (check `abx remote <name>` covers your chain, and that the deploy block was forwarded). The CLI warns instead of printing ✓ here.
+The resolver handles indexed state and public metadata/live/data routes. The effects service executes
+programs and publishes stills/traits. Deploy them separately so heavy browser work does not destabilize
+metadata reads.
 
-### Deploying to a hosted resolver — pre-warm flow (preferred)
+For an active JavaScript sale, run continuous effects. For a fixed supply or repair, a one-shot render
+may be sufficient. With an on-chain Solidity image renderer, no effects service is needed for the
+image; do not deploy infrastructure merely because the collection is a code contract.
 
-The deploy address is deterministic (`predict` = a pure function of factory + salt), so have the resolver watch the address *before* the token mints — metadata is live the instant a marketplace sees it, no cached blank:
-```bash
-abx predict                                     # 1. prints predicted address + reserved --salt (+ exact deploy cmd)
-abx add <predicted> --remote --from-block <now> # 2. resolver starts WATCHING that address (nothing there yet)
-ABX_PUBLIC_BASE_URL=https://meta.you.xyz abx deploy --image ./art.png --name "Aurora" --salt <salt>  # 3. deploy + MINT in one tx (same salt!)
-abx add <predicted> --remote                    # 4. one nudge → pulls the deploy events + bridges the image locator
-abx refresh <predicted>                         # 5. marketplaces (already resolvable → they cache the real thing)
-```
-Use the **exact `--salt` that `predict` printed** in step 3 (a plain `deploy` reserves a *different* salt → a different address than the resolver is watching). `--from-block <now>` = current block (`cast block-number`, or just `0` on a quiet testnet).
+Protect public effects endpoints with the generated token. An unauthenticated force-render endpoint
+can burn compute and storage. Keep resolver admin/effects credentials separate from wallet signing.
 
-Why pre-warm: minting *before* the resolver knows the contract lets a marketplace fetch in that window, cache a miss, and need a later refresh. Registering the predicted address first closes the window. (There's no background poller — the resolver indexes only what you tell it — so a single nudge after deploy is still needed; the win is *ordering*, not eliminating the nudge.)
+Verify the operational graph:
 
-**Simpler, if you don't mind the small window:** skip the pre-warm — `deploy` (mint at deploy) → `abx add <addr> --remote` → `abx refresh`. Fine for a quiet testnet; prefer pre-warm for anything real.
+1. Resolver can reconstruct chain state from its configured RPC.
+2. Effects can load the exact live document for a minted id.
+3. Effects storage produces a publicly retrievable locator.
+4. Resolver publishes or redirects to that locator.
+5. Token metadata exposes the resulting image/attributes.
+6. A PostParam change reaches the watcher and creates the next inputs-hash render.
 
-### Local off-chain serve flow (resolver on this machine)
+## Use lifecycle states
 
-```bash
-abx doctor                                     # 1. green light (incl. storage backend)
-export ABX_STORAGE_BACKEND=arweave                   # 2. pick custody (or pass --backend arweave per deploy); Turbo identity auto-managed (back up the key file)
-ABX_PUBLIC_BASE_URL=https://my.node abx deploy --image ./art.png --name "Aurora" --no-mint   # 3. custody → commit → deploy (no mint) → index
-abx serve                                       # 4. serve the resolver at the known address (blocks)
-abx mint <address>                              # 5. issue token #0 once metadata is live
-abx refresh <address>                           # 6. nudge marketplaces to index it
-```
-Drop `--no-mint` (steps 5–6 collapse) for the express path. Add `--sign` to step 3/5 for the wallet lane. Confirm integrity with `abx verify <address>` (re-hashes served bytes vs the on-chain commitment — no server needed; the `/verify` HTTP route is the same check while serving). `abx index <address>` re-reconstructs from chain; `abx status` lists projects + the active backend.
+Prefer status over retries. Typical nonterminal states include deployment accepted, indexing,
+storage propagating, render queued/running, and remote registration pending. Typical terminal faults
+include authentication/authorization failure, invalid contract/chain, interface mismatch, failed
+transaction, integrity mismatch, and unsupported configuration.
 
-## Token API (the resolver)
+Use:
 
-⚠ **Read this list; never infer a route from another one — and prefer not needing it at all.** The contract commits its own metadata URL on-chain, so **`abx tokenuri <addr>`** and **`abx contracturi <addr>`** (ERC-7572 collection metadata: reads `contractURI()`, follows it, decodes the JSON) answer "where does this resolve, and what does it say" without you assembling a URL. Guessing has a specific trap: **`/t/<chainId>/<address>` is NOT collection metadata** — collection metadata is `/c/<chainId>/<address>`. A miss now names which of three things happened, in a machine `code`: **400 `invalid_request`** (your path shape — the body names the right template and may carry `didYouMean`) · **404 `unknown_route`** (this node serves no such path; body lists what it does serve) · **404 `not_registered`** (path fine, this node doesn't index that contract → `abx add <addr> --remote`) · **400 `unsupported_chain`** (body carries the `chains` it serves) · **410 `burned`** (that token existed and was destroyed — permanent; stop asking, and drop it from any listing. An *edition* id with zero live copies is NOT this: it still serves, and can mint again). None of those mean the service is down — don't report an outage off a URL you built.
+```bash
+abx status [address] --watch
+abx status <address> --remote <name> --watch
+abx storage status <locator> --json
+abx verify <address> --json
+```
 
-Default `http://localhost:8787` (or `ABX_PUBLIC_BASE_URL`). Routes carry the **chainId** (the protocol path grammar) so one host can serve many chains:
-- `GET /` — read-only index of served contracts · `GET /t/<chainId>/<address>/0` — token metadata (ERC-721 `tokenURI` on a 1/1/Series/code project, ERC-1155 `uri` on an edition — auto-detected, same route) · `…/0/image` — the image
-- `GET /c/<chainId>/<address>` — ERC-7572 collection metadata · `GET /api/project/<address>` — full reconstructed state · `GET /d/<chainId>/<address>` — per-contract read-only dashboard (namespaced so one host serves many contracts). No public action buttons anywhere.
-- For IPFS/Arweave the served `image` is the **gateway HTTPS URL** (`https://<gateway>/ipfs/<cid>` / `<gateway>/<txid>`), the form wallets/marketplaces render (raw `ipfs://` doesn't). The on-chain commitment is the **keccak256** (backend-neutral anchor, survives a gateway migration); the CID/txid is just the locator. The locator lives in the **deployer's** local index, so a **remote** resolver emits the gateway URL only once it's bridged (`abx add <clone> --remote`), else `image` falls back to the resolver's own `/…/image` route.
-- `GET /.well-known/abx-service` — the **service descriptor** (public): what the node supports — `interfaces`, `chains`, `auth` (incl. `signupUrl` for humans), `render.attached` (managed rendering). Read it before registering with any remote service.
-- `POST /v1/projects` `{chainId, address, fromBlock?, factory?, description?, externalUrl?, attributes?, contentLocators?}` · `GET /v1/projects` (the projects visible to the token, each with `status`) · `DELETE /v1/projects/<chainId>/<address>` · `POST /v1/projects/<chainId>/<address>/reindex` · `GET /v1/projects/<chainId>/<address>/status` (`status` + `fromBlock`/`toBlock`/`headBlock` + `error.class`) — the **control plane** ([spec](../../../../specs/self-host-toolkit/remote-services.md)): register/forget which contracts the node indexes, bridge off-chain traits + locators; a remote `add`/`forget`. Bearer-gated (`Authorization: Bearer <token>`), 404 code `disabled` when no token is configured. Errors carry a machine `code` (`unauthorized` 401 · `forbidden` 403 · `unsupported_chain` · `not_registered`). Register answers **200** (caught up, with counts) or **202** (accepted, still catching up — poll status); the registration is durable either way. Indexing control only — never signing.
-- `GET /api/project/<address>/verify` — bearer-gated too (it triggers outbound fetches). Run from the CLI: `abx verify <addr>` / `abx index <addr> --remote`.
+Wait on nonterminal states using the command's watcher/backoff. Do not wrap the CLI in a second tight
+poller. Do not retry terminal 4xx responses or reverted transactions unchanged. Read
+[diagnose.md](diagnose.md) for the one-transition recovery model.
 
-`/api/project/<address>` key fields: `isCanonical` (factory-verified — note: `isCanonical`, **not** `canonical`), `owner`, `royalty`, `collectionFields[]`/`lockedCollectionFields[]`, `extensions[]`, `tokens[]` each `{minted, owner, tokenURI, fields[] ({field, representation, value}), lockedFields[]}`. The JSON also carries **`abx_provenance`** — per-field `source` + `status` (`on-chain` · `verified` · `mismatch` · `anchored` · `off-chain` · `n/a`), with an `anchor` for off-chain bytes that carry an on-chain hash (`off-chain` = plain operator value, benign; `anchored` = verifiable via `abx verify`). Confirm a deploy with **`abx verify <addr>`**, not curl.
+## Migrate without losing canonicity
 
-**`serve` heads-up:** the `pnpm`/`tsx` wrapper detaches, so a backgrounded `abx serve &` may report the wrapper process exiting while the server keeps running — check the **port** (curl it), not the process.
+Migration changes a public projection, not canonical on-chain history. Use `abx migrate` to copy and
+compare resolver state without cutting over prematurely.
 
-## Docker / droplet
+1. Resolve the source and destination descriptors and credentials.
+2. Confirm both support the active chain and contract type.
+3. Reconstruct/register the destination from chain using the deploy block.
+4. Copy only off-chain operator state and published artifact locators that are not derivable from chain.
+5. Verify contract metadata, representative token metadata, fields, attachments, renders, and byte
+   commitments on both sides.
+6. Cut over via DNS when using a stable creator domain, or change the on-chain URI pointer only after
+   parity is proven.
+7. Re-emit URI/refresh signals as required, then monitor the destination.
+8. Keep the old service until marketplace and collector paths have converged.
 
-The container is **emitted by `deploy-resolver --provider vps`** — it writes `deploy/vps/` with a `Dockerfile` + `docker-compose.yml` + `Caddyfile` + `setup.sh`, self-contained. Don't hand-write a Dockerfile or compose file. Run compose **from that dir**:
-```bash
-cd deploy/vps
-docker compose up -d --build                  # builds the emitted Dockerfile, serves on :8787
-```
-One small container (`node:24-slim`, SQLite projection on a volume — no DB service, no native modules). State persists in the `abx-data` volume. Set `ABX_RPC_URLS` / `ABX_PUBLIC_BASE_URL` / secrets via the `.env` the setup writes (sourced, never inlined); Caddy fronts it with automatic TLS. Sizing → [`specs/self-host-toolkit/deployment.md`](../../../../specs/self-host-toolkit/deployment.md).
+Never describe resolver migration as moving the NFT. Ownership, parameters, commitments, and canonical
+events remain on-chain; only the serving/indexing projection changes.