@artblocks/abx-cli 0.1.0-alpha.31 → 0.1.0-alpha.33

package/skill/reference/hosting.md

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

package/skill/reference/operate.md

@@ -0,0 +1,181 @@
+# 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
+```
+
+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. The resolver exposes the complete
+artifacts list and `/data/<key>` retrieval. 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.
+
+### 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.