@artblocks/abx-cli 0.1.0-alpha.9 → 0.1.0

package/skill/reference/hosting.md

@@ -1,149 +1,238 @@
-# 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:
+```bash
+abx remote <name>
+```
 
-- **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>`.
+`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.
 
-## Managed providers — a resolver someone else runs (`--remote <name>`)
+This reports the service descriptor, supported chains, rendering policy, authentication status, and
+any interface-specific origins. A remote names a provider catalog, not necessarily one process; an
+advertised account, wallet, or hosting interface may use a different HTTPS origin from its resolver.
+Do not infer provider capability from its hostname or marketing page.
 
-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)).
+Interpret control-plane failures precisely:
 
-- **Named remotes.** Put the provider in `.env`: `ABX_REMOTE_<NAME>_URL=<base>` + `ABX_REMOTE_<NAME>_TOKEN=<api key>` (same name normalization as `ABX_RPC_URLS_<CHAIN>` — `my-provider` → `MY_PROVIDER`). 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_RESOLVER_ADMIN_TOKEN`) — nothing changes for a node you deployed. A named remote never falls back to `ABX_RESOLVER_ADMIN_TOKEN`, so your node-admin secret can't leak to a provider.
-- **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.
+- `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.
 
-## Self-hosted resolver — `abx deploy-resolver`
+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.
 
-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, 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.
+Never invent a provider, auth flow, price, quota, or key source. If no configured provider exists,
+offer the fully supported creator-operated route.
 
-**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.)
+### Creator-operated resolver
 
-**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.
+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.
 
-`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.
+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.
 
-**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."
+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.
 
-**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.
+Never lock URI configuration to a provider-owned domain. The pointer can be changed before
+`lock-uri`, but never after it. Lock only a creator-controlled domain whose production route has
+been verified. ABX Services does not currently support custom-domain routing, so an `abx.io` URI
+must remain unlocked; the CLI refuses that lock.
 
-## Render runner — `abx deploy-effects`
+After provisioning:
 
-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`): **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 control plane (`POST /v1/effect-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:
+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.
 
-- **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).
+## Choose storage independently
 
-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.
+Storage is stateless configuration selected per command or through environment defaults. Inspect the
+resolved choice with:
 
-## Local vs remote — two SEPARATE projection stores (read before deploying to a remote resolver)
+```bash
+abx storage show --check
+```
 
-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_RESOLVER_ADMIN_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>`.
+| 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 |
 
-### Deploying to a hosted resolver — pre-warm flow (preferred)
+Never silently fall back to `fs` when a selected backend is incomplete. Fix the missing configuration
+or change the plan explicitly.
 
-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).
+### Cloud
+
+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
+
+`--backend arweave` (the default `turbo` provider) needs the optional
+`@artblocks/abx-storage-arweave` package installed alongside the CLI — it is not part of the
+default install, deliberately, so a default `abx` install stays free of Turbo's browser
+wallet-connector dependency tree. If it is missing, the CLI names the exact install command
+(`npm install @artblocks/abx-storage-arweave`) rather than failing unhelpfully; run that command
+once, then retry. `--provider http-bundler` needs neither this package nor any of its dependencies.
+
+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
 
-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.)
+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.
 
-**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.
+## Operate resolver and effects services
 
-### Local off-chain serve flow (resolver on this machine)
+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.
+
+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.
+
+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.
+
+### SQLite maintenance for a long-running node
+
+The self-hosted store is one SQLite file. `abx serve` already reclaims freed pages automatically in
+small bounded passes between chain-watch ticks — never inline with a request, so it never adds
+latency to a metadata read. Nothing to schedule for that half.
+
+The other half is explicit and never automatic: a store created before this maintenance shipped
+needs a one-time conversion.
 
 ```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
+abx vacuum                          # status: auto_vacuum mode, page count, freelist size
+abx vacuum convert                  # one-time full VACUUM — only when abx vacuum says the store needs it
+abx vacuum incremental [--pages n]  # one bounded reclaim pass on demand (not running abx serve? use this)
 ```
-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.
 
-## Token API (the resolver)
+Run `abx vacuum convert` deliberately, not on a schedule: it rewrites the entire file and can briefly
+need up to ~2x its on-disk size. Check `abx vacuum` first; if it already reports `auto_vacuum:
+incremental`, there is nothing to convert.
 
-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.
-- `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) · `DELETE /v1/projects/<chainId>/<address>` · `POST /v1/projects/<chainId>/<address>/reindex` · `GET /v1/projects/<chainId>/<address>/status` — 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`). 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`.
+## Use lifecycle states
 
-`/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.
+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.
 
-**`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.
+Use:
 
-## Docker / droplet
-
-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.