@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.40

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,138 +1,205 @@
-# 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. **The served `image` is the backend's gateway HTTPS URL** → IPFS/Arweave custody needs a *public* gateway (Arweave's `https://arweave.net` is the public default). 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.
+Do not ask “where should we host?” until the public surfaces require a host.
 
-**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.
+No ABX resolver is required when:
 
-**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.
+- 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.
 
-### Arweave via Turbo — the easy permanent path (read before quoting setup)
+A resolver is useful or required when:
 
-`arweave` defaults to the **Turbo** provider (ArDrive). For small art it needs **no setup and costs nothing** — no wallet dashboard, no JWT (don't send anyone to `app.arweave.org`). How it works:
+- 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.
 
-- **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` on first upload (address printed). 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** as the Turbo identity (`ABX_DEPLOYER_PK`/`SEPOLIA_FUNDED_PK`/`SEPOLIA_WALLET_PK`). 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.
+Storage can be on-chain while resolution is hosted, or external while metadata resolution is
+on-chain. Keep those axes separate.
 
-#### When a Turbo upload fails — diagnose, don't guess
+## Choose managed or creator-operated resolution
 
-A failed upload is the #1 place an agent goes off the rails: it invents a cause and bails. Don't.
+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.
 
-- **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 is the anchor; `arweave.net` is the default gateway (`--gateway` to override). 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.
+### Managed remote
 
-### Directory-base — image off-chain, JSON on-chain, no server (the medium/large static default)
+Use a named remote already configured in the environment rather than standing up duplicate
+infrastructure. Start with:
 
-`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:
-
-- **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 needs a **public read base** (`--public-base` / `ABX_S3_PUBLIC_BASE`, also what `deploy-code --image-base` takes), **distinct from the signed-API `--endpoint`/`ABX_S3_ENDPOINT`** — they are different hosts. ⚠ **R2:** `https://<acct>.r2.cloudflarestorage.com` is the *API endpoint* (auth-only, never public → 403 for marketplaces); the public read URL is a `https://pub-<hash>.r2.dev` you ENABLE in the dashboard, or a custom domain. AWS: a public-read bucket or a CloudFront domain. The full set: `ABX_S3_ENDPOINT`/`BUCKET`/`REGION`/`ACCESS_KEY_ID`/`SECRET_ACCESS_KEY` + `ABX_S3_PUBLIC_BASE` (`abx storage show` prints them). Files upload under a content-derived prefix → `<publicBase>/<prefix>/{id}.png`. **Caveat:** S3 is centralized, mutable, not content-addressed (no CID/txid root). Bake a domain/CDN you control. 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>`.
+```bash
+abx remote <name>
+```
 
-## Hosted resolver — `abx deploy-resolver`
+`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
+OAuth login, manual recovery path, current access model, and provider-feedback path. Other providers
+use their configured name.
 
-For the large/mutable default. `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, free tier, custom domain) and a **VPS** (compose + Caddy auto-TLS). 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.
+This reports the service descriptor, supported chains, rendering policy, and authentication status.
+Do not infer provider capability from its hostname or marketing page.
 
-**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.)
+Interpret control-plane failures precisely:
 
-**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.
+- `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.
 
-`deploy-resolver` also **generates `ABX_RESOLVER_ADMIN_TOKEN`** → your local `.env` (a secret — never printed, env-only); the printed steps set the **same** token on the host. 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.
+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.
 
-**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."
+Never invent a provider, auth flow, price, quota, or key source. If no configured provider exists,
+offer the fully supported creator-operated route.
 
-**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.
+### Creator-operated resolver
 
-## Render runner — `abx deploy-effects`
+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.
 
-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. `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`): **ipfs / arweave** (the runner uploads and publishes a durable `ipfs://`/`ar://` locator the resolver 302-redirects to) or **s3** — **NOT** the default `fs` for a hosted setup (a laptop-local store a hosted resolver can't read, so the placeholder never clears). The runner **publishes** each render to the resolver's admin control plane (`POST /admin/render-artifacts`, gated by the SAME `ABX_RESOLVER_ADMIN_TOKEN` — index-control only, never signing), so it does NOT need to share the resolver's disk. Two topologies:
+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.
 
-- **Locator bridge (default for a hosted drop):** runner on its own host + a public storage home; it publishes 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).
+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.
 
-One-shot without a service: **`abx render <addr> --remote <resolver>`** renders locally and publishes to the hosted resolver (re-run to restore a resolver that lost its volume — the publish is idempotent). 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.
+After provisioning:
 
-## Local vs remote — two SEPARATE projection stores (read before deploying to a hosted resolver)
+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.
 
-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 hosted resolver 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 hosted): after deploy run **`abx add <clone> --remote [url]`** to register + index it on the node (url defaults to `ABX_PUBLIC_BASE_URL`; needs `ABX_RESOLVER_ADMIN_TOKEN` matching the resolver). 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>`.
+## Choose storage independently
 
-### Deploying to a hosted resolver — pre-warm flow (preferred)
+Storage is stateless configuration selected per command or through environment defaults. Inspect the
+resolved choice with:
 
-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)
+abx storage show --check
 ```
-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).
 
-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.)
+| 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 |
 
-**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.
+Never silently fall back to `fs` when a selected backend is incomplete. Fix the missing configuration
+or change the plan explicitly.
 
-### Local off-chain serve flow (resolver on this machine)
+### Cloud
 
-```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.
+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.
+
+### IPFS
+
+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.
+
+### Arweave
+
+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.
+
+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.
+
+### Publication bridge
 
-## Token API (the resolver)
+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.
 
-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` — ERC-721 metadata · `…/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.
-- `POST /api/project/<address>/reindex` (full replay) · `GET /api/project/<address>/verify` — both **admin-only** (bearer `ABX_RESOLVER_ADMIN_TOKEN`), never exposed as public actions. Run from the CLI: `abx index <addr> --remote` / `abx verify <addr>`.
-- `POST /admin/projects` `{address, fromBlock?, factory?, description?, externalUrl?, attributes?, contentLocators?}` + `DELETE /admin/projects/<address>` — the **admin control plane** (register/forget which contracts the node indexes, bridge off-chain traits + locators; a remote `add`/`forget`). Bearer-gated, disabled when the var is unset. Indexing control only — never signing.
+## Operate resolver and effects services
 
-`/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.
+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.
 
-**`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.
+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.
 
-## Docker / droplet
+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.
+
+Verify the operational graph:
+
+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.
+
+## Use lifecycle states
+
+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.
+
+Use:
 
-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
+abx status [address] --watch
+abx status <address> --remote <name> --watch
+abx storage status <locator> --json
+abx verify <address> --json
 ```
-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).
+
+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.
+
+## Migrate without losing canonicity
+
+Migration changes a public projection, not canonical on-chain history. Use `abx migrate` to copy and
+compare resolver state without cutting over prematurely.
+
+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.
+
+Never describe resolver migration as moving the NFT. Ownership, parameters, commitments, and canonical
+events remain on-chain; only the serving/indexing projection changes.