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

package/skill/reference/hosting.md

@@ -1,138 +1,231 @@
-# 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 |
+
+Never silently fall back to `fs` when a selected backend is incomplete. Fix the missing configuration
+or change the plan explicitly.
+
+### 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
+
+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.
-- `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.
+## 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.

package/skill/reference/operate.md

@@ -0,0 +1,220 @@
+# Operating an existing ABX project
+
+Use this reference for inspection, minting and sales, transfers, fields, gateways, URI pointers,
+royalties, supply, attachments, refreshes, ownership transfer, and locks.
+
+## Contents
+
+- [Read before writing](#read-before-writing)
+- [Mint and run primary sales](#mint-and-run-primary-sales)
+- [Transfer tokens and authority](#transfer-tokens-and-authority)
+- [Operate metadata and data](#operate-metadata-and-data)
+- [Manage economics and supply](#manage-economics-and-supply)
+- [Lock precisely](#lock-precisely)
+
+## Read before writing
+
+Never infer contract type or current authority from the original launch notes. Read the contract:
+
+```bash
+abx state <address>
+abx tokens <address> --json
+abx contracturi <address>
+abx tokenuri <address> --token <id>
+abx verify <address> --json
+abx artifacts <address> --token <id> --json
+```
+
+`abx artifacts` reads a token's `artifacts` manifest directly, without fetching and parsing the whole
+served document — entries plus every registered effect row (current and stale, labeled against the
+token's active `inputsHash`). Report which surface answered: this node's local projection, or (with
+`--remote <name|url>`) the hosted resolver that actually owns a hosted project's real artifact set.
+Neither "not registered here" nor "not registered on that remote" is an error — both return a stable
+`{surface, registered, available, reason, entries, effects}` shape. Nothing it reports is onchain data
+itself; every entry is a resolver-published projection.
+
+Use `abx status` or its remote form for projection/render lifecycle. Record active chain, detected
+family, owner/admin, supply and pause state, minter/payee, royalty/cap, URI renderer/pointers, code
+dependencies, schemas/hooks, and lock state.
+
+Before every write, run its help and dry-run form when available. Confirm sender, target, value,
+token/id/amount, and permanence. Let the CLI validate contract type; do not send raw ABI calls to make
+an operation fit the wrong family.
+
+## Mint and run primary sales
+
+`abx mint` follows the detected family:
+
+- A 1/1 issues its single token.
+- A Series mints the next id in order; `--count` can mint multiple sequential ids.
+- An edition requires `--token-id` except where the contract has only the single 1/1-edition id, and
+  uses `--amount` for copies. `--count` is not an edition synonym.
+
+Confirm the recipient. Minting may trigger a transfer hook; a hook that vetoes mint will revert the
+whole transaction.
+
+### Shared fixed-price minter
+
+Use the shared minter commands for ordinary ETH primary sales:
+
+1. `abx minter configure <token> …` sets price and allocation. Editions require a token id and use a
+   per-id sale configuration.
+2. `abx set-minter <token> --minter <address>` authorizes the minter.
+3. `abx set-primary-payee <token> --payee <address>` declares payout.
+4. `abx unpause <token>` opens minting when the family supports the pause gate.
+5. `abx minter show <token> …` verifies the public sale state.
+6. `abx minter buy <token> …` is the public purchase path; editions use quantity and token id.
+
+Do not call a sale live until price units, allocation, payee, minter address, pause state, and a
+representative purchase are verified. `abx mint-page` scaffolds a client for the shared minter; it does
+not configure the on-chain sale for you.
+
+Use a custom minter for auctions, allowlists, raffles, free claims, ERC-20 pricing, or other issuance
+rules. The custom contract calls the canonical token's mint authority; the token itself remains a
+factory clone. Read [capabilities.md](capabilities.md).
+
+## Transfer tokens and authority
+
+`abx transfer` moves token ownership/copies, not contract administration.
+
+- A 721 transfer names token id and destination.
+- An edition transfer names token id, amount, destination, and source holder because an id can have
+  multiple holders.
+- Creator-token validation or a transfer hook may reject the move. Diagnose the actual revert; do not
+  bypass or clear an enforcement mechanism without the owner's explicit intent.
+
+`abx set-admin --to <address>` transfers contract authority. Treat it as a high-risk, potentially
+irrecoverable handoff:
+
+1. Verify the recipient is correct for the active chain.
+2. Inventory unfinished operations and unlocked surfaces.
+3. State which powers move and which external controllers remain separate.
+4. Receive exact human confirmation.
+5. Execute once, then read state from chain to prove the new owner.
+
+Never interpret a token transfer as a sale listing. ABX has no secondary order book; a marketplace or
+manual transfer handles secondary exchange.
+
+## Operate metadata and data
+
+### URI pointers and renderers
+
+Use `set-token-uri`, `set-contract-uri`, and `set-renderer` only after reading the current configuration
+and verifying the destination. Switching `set-renderer --off` can place an HTTP resolver in front of
+content that remains stored on-chain. Switching to the canonical renderer makes configured on-chain
+fields self-resolving when the contract supports them.
+
+Never hand-build a resolver path. Read `tokenURI`/`contractURI`, decode it, and follow what the
+contract actually returns. A correct-looking URL constructed from memory is not evidence.
+
+### Fields
+
+`abx set-field` writes one metadata field representation at token or collection scope. Representations
+include inline data, reader/chunk pointers, hashes, public locators, and renderer pointers as supported
+by the contract. Collection-scope values act as shared defaults; token-scope values override them.
+
+Use reserved fields such as description, attributes, creator, license, display notes, and links
+according to command help. Verify the resulting provenance in decoded metadata. On-chain-wins means a
+new on-chain value can intentionally supersede a resolver projection.
+
+### Gateways
+
+`abx set-gateway` changes the serving prefix for IPFS/Arweave locator representations without moving
+the content. Verify a representative locator through the new gateway before changing it. A gateway
+repoint is not a re-upload and does not change the committed CID/transaction id.
+
+### Attachments versus parameters
+
+`abx attach <addr> <key> <locator>` records a named artifact. It prints the CANONICAL fetch URL for
+every key (`{base}/{chainId}/{address}[/<id>]/data/<key>`) directly — never hand-build that route.
+It also distinguishes the on-chain field write from off-chain SERVING: an on-chain write can succeed
+while nothing can serve it. With no resolver base baked in at all, it warns there is no serving path
+whatsoever. With one baked in, it probes whether a resolver actually answers for this token right
+now (before the write, since the key itself doesn't exist yet) and warns if not — "the on-chain
+document carries reserved fields only" is a real gap creators hit; the write landing is not proof
+anything can serve it. Bare on-chain metadata cannot enumerate arbitrary field keys, so consumers
+need a resolver to discover all attachments even when each locator is durable and hash-anchored.
+
+PostParams are different: the parameter store enumerates schemas and values on-chain. Read schemas
+with `state` and values with `tokens --json`. Parameters do not require a resolver merely to be
+canonical or enumerable.
+
+### Replacing an unlocked script
+
+`abx replace-script <addr> --script <file>` ships a fix to a code project's on-chain program any
+time before `abx lock-script`. It refuses outright — never warns and proceeds — on a locked script
+or a target that isn't SeriesCode/EditionCode. It diffs by content against what's on-chain (an index
+that already matches is never re-sent), folds every write and remove into ONE atomic transaction (so
+a revert can never leave a half-applied script), and reads the completed script back to verify exact
+reassembly before reporting success. Prefer this over hand-encoding `setScriptChunk` calls.
+
+### Refresh and URI events
+
+`abx refresh` asks external marketplaces to fetch metadata again; it does not fix the metadata or
+mutate canonical state. First prove that the current URI resolves and returns the intended document.
+For editions, `ping-uri` re-emits native URI events for selected ids after a repoint. Use the smallest
+id set needed and verify the new path before signalling indexers.
+
+## Manage economics and supply
+
+Use `set-royalty` to change receiver/rate within the collection's permanent royalty ceiling. Use
+`set-royalty-cap` only to lower that ceiling. State the old and new values and confirm the irreversible
+loss of future headroom.
+
+Series supply caps and edition per-id caps are monotonic downward. Read current minted supply before
+lowering a cap; never propose a value below already minted supply. For editions, name the id and
+distinguish its per-id cap from aggregate collection supply.
+
+Pause/unpause controls the supported mint gate, not transfers or every external minter behavior.
+Read state after changing it.
+
+Primary payee declares sale proceeds; royalty receiver handles secondary royalty reporting. Keep them
+separate. Changing one does not update the other.
+
+## Lock precisely
+
+Lock last, after production-path verification. Every lock freezes a different surface:
+
+| Lock | Freezes | Does not necessarily freeze |
+|---|---|---|
+| `lock-field` | one token/collection field representation | other fields, URI pointer, program, params |
+| `lock-uri` | URI configuration/pointer at selected scope | program/dependencies/params/hooks |
+| `lock-script` | code-project script chunks | dependencies, metadata, params, external renderer code |
+| `lock-dependencies` | dependency list and registry pointer | bytes returned later by a live registry entry |
+| `lock-param-hooks` | configure/transfer/augment addresses | behavior behind an upgradeable address |
+| governed schema/value lock | writes governed by that schema/key | unrelated or ungoverned params; some inherited defaults |
+| ownership transfer | future owner-only authority at this contract | powers held by external minters/hooks/providers |
+
+For a code project, metadata locks alone do not freeze the program. A strong freeze normally requires
+script, dependency, relevant field/URI, hook, and governed-parameter decisions, plus immutable external
+renderer/hook/dependency deployments.
+
+Important qualifications:
+
+- An ungoverned parameter remains writable despite metadata locks.
+- A schema-welded token value is stronger than a collection default inherited by many tokens; the
+  recovery path may still allow a poisoned collection default to be cleared.
+- A registry dependency may return different bytes behind a frozen reference.
+- A locked pointer to an upgradeable proxy fixes the address, not its behavior.
+- A transfer-hook address represents a standing ability to veto mints/transfers. Freezing an empty
+  hook set is the proof that this power cannot later be added.
+
+Use `abx verify` and direct state reads to enumerate what remains mutable. Describe the guarantee as
+specific stored values and addresses that can no longer change; do not promise immutable output unless
+every live input and external implementation has actually been bounded.
+
+`abx state <address> --json` reports every lock above in one `locks` object — token/contract URI,
+script, dependencies, param hooks, and the standard `METADATA_FIELD` set — each as `true` (frozen),
+`false` (open), or `null` (unread; never report an unread lock as off). A project's own custom field
+keys are real and independently lockable but are not enumerable from a bare head read; say so rather
+than implying the field scan is exhaustive. Every lock is independent: never infer one lock's state
+from another's.
+
+`abx verify --json` separates two verdicts that must not be conflated: `ok`/`contentIntegrity` is
+content-integrity ONLY (a hash mismatch, or none to check) and is the only field the exit code
+reflects; `availability` is a sibling verdict for render/serve readiness (`available` / `partial` /
+`unavailable` / `unknown`) that a missing render or an un-refetched `ipfs`/`arweave`/`url` locator
+moves, while `ok` stays unaffected by design. Report both, never collapse one into the other.
+`abx verify` also flags whether the project's stored `tokenURIRenderer`/generator pointers are the
+CURRENT canonical singletons — a `false` here means an older-but-working deployment (or a fully
+custom one), never "broken".