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

package/skill/SKILL.md

@@ -1,29 +1,98 @@
 ---
 name: abx-self-host
-description: Launch and operate a self-hosted ABX NFT end to end with the ABX CLI (`abx`) on testnet — a 1/1 (`abx deploy`), a multi-token Series from a folder of media (`abx deploy-series`), or a generative/code drop (`abx deploy-code`). Covers on-chain vs off-chain metadata, storage custody (local disk, S3/R2, IPFS, Arweave), deploy + mint (now or pre-warmed at a predicted address), rendered thumbnails and on-chain traits for code art, primary sales via the shared fixed-price minter, and owner ops (transfer, refresh, re-point URIs, royalties, lock fields, pause/unpause, supply cap, delegate minting). Use when the user wants to self-host an ABX project, take an image to an NFT on testnet, deploy a collection from a folder of images, launch generative/code art, mint or run a primary sale, refresh a listing, operate a project they launched, choose a storage backend, or stand up hosting they own.
-compatibility: Drives the abx CLI (@artblocks/abx-cli). Co-versioned with it — install/refresh with `abx skill install` so this skill matches the CLI's `abx version`. Requires Node 22.5+.
+description: Launch and operate a self-hosted ABX NFT end to end with the ABX CLI (`abx`) on testnet — a 1/1 (`abx deploy`), a multi-token Series from a folder of media (`abx deploy-series`), or a generative/code drop (`abx deploy-code`). Covers on-chain vs off-chain metadata, storage custody (local disk, S3/R2, IPFS, Arweave), deploy + mint (now or pre-warmed at a predicted address), rendered thumbnails and on-chain traits for code projects, collector-configurable on-chain parameters (PostParams — typed, auth-gated, settable by creator/token-owner/address), primary sales via the shared fixed-price minter, owner ops (transfer, refresh, re-point URIs, royalties, pause/unpause, supply cap, delegate minting, and the one-way locks: fields, URI config, script, dependencies, param hooks), and optionally listing a deployed collection in the ABX App Store (`abx submit-app`, never folded into deploy). Use when the user wants to self-host an ABX project, take an image to an NFT on testnet, deploy a collection from a folder of images, launch generative/code projects (art, collectibles, game assets, or anything else), add collector-settable parameters/traits, mint or run a primary sale, refresh a listing, lock down what a project stores or freeze its param hooks, operate a project they launched, list an ABX app in the App Store, choose a storage backend, stand up hosting they own, or point a project at a hosted/managed metadata provider with an API key.
+compatibility: Drives the abx CLI (@artblocks/abx-cli). Co-versioned with it — install/refresh with `abx skill install` so this skill matches the CLI's `abx version`. Requires Node 22.13+.
 metadata:
-  version: "0.1.0-alpha.3"
+  version: "0.1.0-alpha.31"
 ---
 
 # ABX Self-Host Toolkit (`abx`)
 
+> **Before you look around this project: never `cat`/`grep` `.env`, and never print a credential.**
+> RPC URLs, `PINATA_JWT`, S3 secrets and provider keys all live there, and reading it spills every one
+> into the transcript — irreversible. Ask the tool instead: `abx doctor` and `abx remote` report each
+> credential as set / unset / rejected without ever printing one. (This is repeated in Read first
+> because agents orient by listing and reading files *before* they reach a bullet list.)
+
 L3 agentic surface: image → live self-hosted NFT the creator owns — a **1/1** (`abx deploy`) or a multi-token **Series** from a folder (`abx deploy-series`, see [Series](#series-multi-token-drops)) — and operate it after, with no central service in the loop. Wraps `@artblocks/abx-sdk`.
 
 **You drive this for a creator.** Do the mechanical work yourself; surface only genuine decisions, each a simple choice + a recommendation. If *you* hold the signing wallet (an agent releasing its own work), you *are* the human — pick defaults, run the hot lane.
 
 ## Read first (every session)
 
-- **YOU run the `abx` commands — never tell the creator to run one.** You have a shell; use it. Run `doctor`, `ls`, `--dry-run`, `tokenuri`, `state`, `refresh`, `balance`, etc. yourself and read the output — don't paste a command and wait for them to run it or copy back results. The creator's *only* hands-on step is approving in their **browser wallet** (`--sign`) or giving you a value you asked for (their address, a name). Even "next steps" after a deploy: **run the read-only ones** (`tokenuri` to prove it resolves) and **offer to run** the actions (`refresh`, `unpause`, `mint`) — don't hand over a list of commands to run. Exceptions: a genuinely interactive/again-in-their-env command (an OS login, `gcloud auth`), and the **in-chain Solidity lane's Foundry step** (`forge build/test/deploy` a renderer — `abx` never compiles/deploys Solidity; see [Code projects](#code-projects-generative--code-based-drops)) — then run it if you have the tool, else hand it over.
-- **Skill ⇄ CLI version must match.** This skill is co-versioned with the `abx` CLI. Run `abx version` and compare it to this file's frontmatter `metadata.version` (top of SKILL.md). If they differ, this skill is stale for the installed CLI — run `abx skill install` to resync, then reload the skill before continuing. (`abx` also prints a drift nudge on its own when it notices.)
-- **`abx doctor` first, always** — full preflight (Node, pnpm, RPC, signing key, storage). Fix any ✗ before deploying ([Setup](#setup--environment)). A missing public-base-url is not a "set up IPFS" signal: for tiny art go on-chain, for larger art pick an off-chain backend — see [Quick start](#quick-start).
-- **Never collect secrets in chat.** Keys, `PINATA_JWT`, S3 secrets → the project's `.env`. The Arweave/Turbo key is a CLI-managed file (`.abx-self-host/arweave-key.json`) — never paste it. Name the var/file; never take the value.
-- **Testnet only today** — every launch is on a testnet: **Base Sepolia by default** (`ABX_CHAIN` unset), with **Sepolia** also shipped (`ABX_CHAIN=sepolia`). Say "testnet"; don't imply mainnet. **Testnet IS the preview + e2e environment**: it runs the *real* wiring (renderers, generator, on-chain tokenURI assembly), so a creator should deploy there, inspect the actual result (`abx tokenuri` / the live view / `abx verify`), confirm it looks right, and only *then* go to mainnet — no separate local "preview" is as faithful as the real testnet drop, and a testnet deploy is ~free + ~minutes. **One cross-chain gotcha: on-chain library deps (`--dep p5@…`) resolve to on-chain bytes only where an Art Blocks dependency registry exists — that's Sepolia, NOT Base Sepolia.** A no-dependency script (vanilla JS/GLSL) goes fully on-chain on either; a drop that needs a registry-hosted library on-chain must target `ABX_CHAIN=sepolia` (or run the resolver lane).
-- **Scope today = ERC-721 on testnet.** The shipped token standard is **ERC-721** (a 1/1, or a **Series** for many tokens), on Base Sepolia (default) or Sepolia via `ABX_CHAIN`. There is **no `--chain` flag (pick the chain with `ABX_CHAIN`) and no `--erc1155`/`--standard` flag** — don't invent one; mainnet + ERC-1155 are roadmap, not something you flip here. Map the ask to what ships: **"an edition of N" / "N copies"** → an ERC-721 **Series** (`abx deploy-series`, N tokens; for a priced sale of one piece, a 1-token Series). If a creator needs a true ERC-1155 shared-supply edition or an unsupported chain, say plainly it's not in the toolkit today rather than fabricating a recipe.
-- **Two gates decide everything: (1) demo or real? (2) who signs?** Settle both first.
+- **YOU run the `abx` commands — never tell the creator to run one.** You have a shell. The creator's
+  only hands-on steps: approving in their **browser wallet** (`--sign`), giving you a value you asked
+  for, and **looking at the work in `abx preview`** (you run it; the URL is theirs). Post-deploy, run the
+  read-only next steps and *offer* the actions. Exceptions: an interactive command in their environment
+  (an OS login), and the Solidity lane's Foundry step — `abx` never compiles or deploys Solidity.
+- **Version drift — `abx doctor`'s "Version & provenance" block catches it: binary source (npx is a ✗ — it can silently keep serving a stale cached copy), npm currency, and skill↔CLI match, each with its own fix command.** Run it before any deploy and act on a ✗ yourself (`abx skill install` / `npm i -g @artblocks/abx-cli@latest`) — never just relay the notice: a stale CLI can hold canonical addresses that have since moved, so it deploys against dead singletons.
+- **`abx doctor` first, always** — full preflight (Node, pnpm, RPC, signing key, storage). Fix any ✗ before deploying ([Setup](#setup--environment)). A missing public-base-url is not a "set up IPFS" signal: for tiny content go on-chain, for larger content pick an off-chain backend — see [Quick start](#quick-start).
+- **Never collect secrets in chat, and never `cat`/`grep` `.env`.** Keys, `PINATA_JWT`, S3 secrets, provider API keys → the project's `.env`. The Arweave/Turbo key is a CLI-managed file (`.abx-self-host/arweave-key.json`) — never paste it. Name the var/file; never take the value. **To see what's configured, ask the tool, not the file:** `abx doctor` and `abx remote` report each credential as set/unset without ever printing one. Reading `.env` spills every secret in it into the transcript — irreversible, and a plain `abx doctor` tells you the same thing.
+- **Never quote a third party's price or free tier.** Hosting plans, pinning plans and gateway tiers change without telling us, and a creator makes a real decision on the number you say. Name the provider and send them to its own pricing page; if you must compare, compare *shapes* — pay-once vs. monthly, "lapses if you stop paying" vs. "nothing to renew" — which is the part that stays true. The one figure that is ours to state is Turbo's **under 100 KB free** tier, because the CLI enforces it and prints it.
+- **Testnet only today** — **Base Sepolia by default**, **Sepolia** via `ABX_CHAIN=sepolia`. Say
+  "testnet"; never imply mainnet. Testnet **is** the preview environment: it runs the real wiring, so a
+  creator should deploy there, inspect the actual result, and only then consider mainnet. One
+  cross-chain gotcha: **on-chain library deps (`--dep p5@…`) need the Art Blocks dependency registry,
+  which exists on Sepolia and NOT Base Sepolia** — a no-dependency script goes on-chain on either.
+- **Scope = two standards.** **ERC-721** (a 1/1, a Series, or a code drop — each token unique) and
+  **ERC-1155 editions** (copies of one work), reached with **`--copies <n|open>`** on those same three
+  deploy commands. There is **no `--chain` flag** (use `ABX_CHAIN`) and **no `--erc1155`/`--standard`
+  flag** — don't invent one. Map the ask to the flag, never the standard name: "N copies" / "an open
+  edition" → `--copies`; "N unique pieces" → a plain Series. If a creator needs an unsupported chain,
+  say plainly it isn't in the toolkit rather than fabricating a recipe.
+- **Is the work finished yet?** If the creator is still *making* the piece, you're in **[Phase 0](#phase-0--make-the-work-first-skip-every-gate-below-until-its-good)** — iterate on the work and keep every deploy question off the table until they say ship. The gates below apply to launching something that already exists.
+- **Unfilled placeholders are not a brief.** If their prompt still contains `⟨your idea⟩`, `⟨your idea here⟩`, or any unfilled template, STOP. Ask what they actually want to make. Do **not** treat the placeholder as a creative brief, and do **not** run `abx demo` or send a transaction unless they explicitly asked for a demo.
+- **STOP if you are about to write or deploy a contract yourself.** Everything here is a clone of an
+  ownerless **trust anchor**, and `isAbxClone` against it is the ONLY signal marketplaces and the App
+  Store allowlist against. A contract you write — or `--bootstrap-factory` on a public chain — can never
+  gain it: **canonicity is decided by which contract deployed it and cannot be added afterwards.** So if
+  the ask seems to need something the deploy commands don't do, do NOT build around it. Say: *"I can do
+  that, but your collection won't be a canonical ABX contract — marketplaces won't recognise it, and the
+  only way back is redeploying and moving holders. Want that, or shall we find a way inside the
+  toolkit?"* Then wait. Building your own contracts is a legitimate creator choice; making it **for**
+  them silently is not. (`abx state <addr>` prints `canonical` first.)
+- **Burn is opt-in per collection.** Pass `--burnable` at deploy (default off) to let a **holder or
+  their approved operator** burn their own token (`burn(...)`); without it, a minted token can never be
+  destroyed by anyone (including the owner). There is no owner burn bypass either way. This is the seam
+  for burn-to-combine / breeding / redemption — build the mechanic in a contract that holds the tokens
+  and burns them. `burnable()` reads the setting; it is fixed at deploy. **On a burnable capped
+  edition** the per-id cap is a *live* ceiling — a burn frees a slot the creator/minter can re-mint, so
+  "N copies" means "at most N at once", not "N ever" (a burnable `--copies 1` edition can be re-minted
+  after a burn). The 721 lanes' cap is "N ever". Non-burnable editions have no such gap. **On a 721,
+  a burn is permanent and public:** the id never returns, `tokenURI` reverts from then on, a conforming
+  resolver answers `410` for it, and `nextTokenId() − totalSupply()` is the collection's burn count.
+- **A royalty rate is a promise only once the cap matches it.** The ceiling (`--royalty-cap`, default
+  10%) is reduce-only, but any gap above the live rate is royalty the owner can add later without
+  asking anyone — and no listing page shows that gap. If the creator means "5%, forever", say so out
+  loud and offer `abx set-royalty-cap <addr> --cap 500`. `abx state` prints rate and ceiling together.
+- **What this toolkit does NOT do** — check here before inventing a way:
+  no secondary listings · no mainnet · fixed-price sales only (auctions and
+  allowlists would be different *minters*, not flags) · no post-deploy script replace · and `abx` never
+  compiles or deploys a token contract (`scaffold-renderer` writes a renderer, not a collection). If the
+  ask needs one of these, say so plainly instead of building around it.
+- **A custom mechanic almost never needs a custom token — reach for the extension points FIRST.** A
+  collection can point at **your own minter** (`abx set-minter`), and a code project can arm **param
+  hooks** (`abx set-param-hooks`); one contract can be both, and the token stays a factory clone the
+  buyer can verify. Escrow/vault, soulbind-once, a monotonic ratchet, equip-and-validate, burn-to-combine
+  — every mechanic built on this toolkit so far is *a controller plus one or two hooks*, and agents
+  still reach for "write a token contract" first. Named patterns, working Solidity, and the
+  `abx predict` recipe that breaks the controller/schema chicken-and-egg:
+  https://abx.docs.artblocks.io/using-abx/guides/custom-mechanics/ — read it before designing one.
+  Two caveats: neither point is scaffolded (real engineering), and a **`--transfer` hook is a VETO, not
+  a trigger** — it can refuse a transfer but never *cause* one, and a reverting hook stops transfers
+  **and mints** for every token. It *does* see burns (`to == 0x0`) on a `--burnable` collection, which is
+  how burn-to-combine and redemption settle.
+- **Two gates decide everything: (1) demo or real? (2) who signs?** Settle both first — *once there's something to launch*.
 - **Confirm the full config before any on-chain write** ([readout](#confirm-before-sending)); wait for go-ahead. Never invent a field silently (name/symbol from filename, an auto description) — show it, flag it `inferred`.
+- **Never hand-build a service URL — ask the chain.** `abx tokenuri <addr> --fetch` and
+  `abx contracturi <addr>` follow the URL the contract itself commits and print what is actually served.
+  **A 404 on a URL you constructed is evidence about your URL, never about the service.** Don't infer a
+  path from a similar one (`/t/<chain>/<addr>/<id>` minus the id is not collection metadata — that's
+  `/c/<chain>/<addr>`). Before calling a service broken, reproduce with a CLI command: a real miss returns
+  `invalid_request` · `unknown_route` · `not_registered` · `410 burned` (that token was destroyed —
+  permanent, never retry), none of which mean "down".
 - **Safe to explore:** `abx <cmd> --help` and `abx deploy --dry-run` never send. You never run a real write just to learn flags.
-- **`deploy` returns; `demo`/`serve` block** (they serve) — background them or warn.
+- **`deploy` returns; `demo`/`serve`/`preview` block** (they serve) — background them or warn. Background `abx preview` and relay its URL, then keep working while the creator looks; `--shoot` is the one preview mode that exits on its own.
 
 ## Which command — what are you launching?
 
@@ -31,21 +100,64 @@ Route by the **content** first, then apply the gates below. The three paths diff
 
 | You have | Command | `tokenURI` resolves | Thumbnail (marketplace still) |
 |---|---|---|---|
-| **one image** (a 1/1) | `abx deploy` | on-chain (tiny art) or off-chain — **no server possible** | the image itself |
+| **one image** (a 1/1) | `abx deploy` | on-chain (tiny content) or off-chain — **no server possible** | the image itself |
 | **a folder of images** | `abx deploy-series` | same — on-chain or off-chain, **no server possible** | each image itself |
 | **a program** (generative / code) | `abx deploy-code` | **a resolver you run** (live seed + PostParam injection) — OR `--onchain-uri` (tokenURI on-chain; the canonical generator computes the live view) | **rendered off-chain** by the effect runner, else a placeholder |
 
-**The dividing line is static art vs a running program.** Static art is self-resolving (the file *is* the thumbnail, nothing to keep running); **a code project's thumbnail is *rendered* off-chain, so it ALWAYS needs a public home you provide (`--image-base` bucket, or a resolver) — settle that infra fork with the creator FIRST** (details in [Code projects](#code-projects-generative--code-based-drops)). Nail the project type before the gates.
+**Any row also takes `--copies <n|open>`** — it makes that work/collection an ERC-1155 **edition** (copies, not unique tokens; `open` = an uncapped open edition, the flagship edition product). Drop it for a unique token, exactly as today. Edition owner ops (mint copies, per-id supply cap, per-id sales) → [operating.md](reference/operating.md#edition-owner-ops).
+
+**Custody on an edition is now symmetric with the 721 side** — on-chain bytes, off-chain-image-with-on-chain-JSON, inline SVG, or a resolver all work with `--copies`, and `deploy-code --copies` takes on-chain `--dep`s. Two limits remain: **`--onchain-image` can't be signed offline** (refused on `--unsigned` everywhere — each chunk tx feeds the next; use hot or `--sign`), and **`deploy-code --copies` is `--script`-only** (no `--code-dir`, no field renderers). Full matrix, including the O(1) folder trick for a raster edition with no server: [decisions.md → `--copies` custody](reference/decisions.md#--copies-erc-1155-editions--custody-is-not-orthogonal-to-the-shape).
+
+> **`--onchain-uri` puts the JSON on-chain — the IMAGE follows one of three routes, and the creator
+> is choosing between them whether they know it or not.** An **SVG** is inlined (bytes on-chain,
+> fully self-contained). A **raster** with `--backend arweave|ipfs|cloud` is uploaded and its URL is
+> baked into the on-chain JSON — no server, permanence is the backend's. A **raster on `fs`** has no
+> public URL to bake, so the renderer holds only a hash and `tokenURI` serves a **placeholder**; the
+> CLI warns before the spend. For the bytes themselves on-chain regardless of format, use
+> `--onchain-image --compress fastlz` (**keep it under ~40 KB/token — that's a READ-gas ceiling, not a
+> cost one; see [Quick start](#quick-start)**). Say which one you're giving them: "no server" and
+> "on-chain" are not the same promise.
+
+**The dividing line is static content vs a running program.** Static content is self-resolving (the file *is* the thumbnail, nothing to keep running); **a code project's thumbnail is *rendered* off-chain, so it ALWAYS needs a public home you provide (`--image-base` bucket, or a resolver) — settle that infra fork with the creator FIRST** (details in [Code projects](#code-projects-generative--code-based-drops)). Nail the project type before the gates.
+
+**Want collector-settable state (a palette a holder picks, a governed dial, an open/communal input)? That's PostParams — a `deploy-code` capability, and the reason to reach for it isn't only "generative."** Any piece that needs typed, on-chain, auth-gated parameters (settable by the creator, the token owner — delegate.xyz honored — or a named address/contract) is a code project: declare them with `--schema key:Type:Auth`, set them later with `abx configure-param`, and every declared key and every set value reads **straight off the contract** — no resolver, no indexer, no metadata JSON in the middle (`abx state` for the schemas, `abx tokens` for the values). They work on the JS lane *and* the in-chain Solidity renderer lane. Full catalog: [Code projects → PostParam schema](reference/code-projects.md#postparam-schema--the-type--auth-catalog).
+
+> **⚠ On an edition (`--copies`), a holder-writable param is SHARED — say this before the creator commits.** Params belong to the **id**, so one value serves every holder of it and the **last writer wins**; `TokenOwner` means *any* holder. A "name your copy" schema renames the work for all 1,000. Per-collector state needs **one id per copy** (a 721 Series, or `--copies 1` ids); communal state is what shared params are *good* at. A holder-writable `String`/`Bytes` key also has **no on-chain size cap**, so one holder can bloat that id's `tokenURI` past what RPCs serve, for everyone, permanently if a `lock=` then bites — `deploy-code --copies` warns, relay it. Why it is deliberate, and the full shape → [code-projects.md → shared params](reference/code-projects.md#postparam-schema--the-type--auth-catalog).
+
+**Planning a priced primary sale? Decide 1/1 vs Series (or edition) BEFORE deploying — it's irreversible.** The shared fixed-price minter sells a **Series** (mint-on-purchase); a plain `abx deploy` **1/1 has no minter/pause/payee**, so its only post-mint move is `abx transfer` (settle an off-chain sale). To run a native fixed-price sale of even a *single* piece, deploy it as a **1-token Series** (`abx deploy-series --count 1`) — or, if copies of that one piece are fine, as an **edition** (`abx deploy --copies <n|open>`), which ships the full sale stack (minter/pause/payee) on its own, no Series wrapper needed. abx has **no secondary-listing feature** — reselling a held token means an external marketplace or a manual `transfer`. Full detail: [operating.md → Selling](reference/operating.md#selling--the-shared-fixed-price-minter).
+
+## Phase 0 — make the work first (skip every gate below until it's good)
+
+**If the creator is still making the piece, you are in the studio, not in a deploy. Stay there until they
+say ship.**
+
+- **Handed a finished file** (`sketch.js`, a build dir, an image folder) → skip to
+  [Gate 1](#gate-1--demo-or-real-launch).
+- **Brought an idea, a reference, a vibe, "let's make one together"** → Phase 0.
 
-**Planning a priced primary sale? Decide 1/1 vs Series BEFORE deploying — it's irreversible.** The shared fixed-price minter sells a **Series** (mint-on-purchase); a plain `abx deploy` **1/1 has no minter/pause/payee**, so its only post-mint move is `abx transfer` (settle an off-chain sale). To run a native fixed-price sale of even a *single* piece, deploy it as a **1-token Series** (`abx deploy-series --count 1`), not a 1/1. abx has **no secondary-listing feature** — reselling a held token means an external marketplace or a manual `transfer`. Full detail: [operating.md → Selling](reference/operating.md#selling--the-shared-fixed-price-minter).
+**OFF the table until they ship** — don't ask, don't "just quickly confirm", don't pre-emptively lay out
+tradeoffs: hosting/lane, thumbnails, traits, storage, names, symbols, royalties, gas, minting.
+
+**The loop** (depth → [code-projects.md → Studio loop](reference/code-projects.md#studio-loop--iterate-on-the-work-before-you-deploy-anything)):
+
+1. **Write against the real runtime contract from the first draft** — `abx.tokenData.seed` for
+   randomness, `abx.traits({…})` for features. Never `Math.random()` "for now"; retrofitting is a rewrite.
+2. **`abx preview --script art.js`, hand them the URL.** Same document the generator serves. This is the
+   one place you hand over a link instead of running it for them.
+3. **Edit, tell them to refresh.** The program is re-read from disk per render — no restart, no watcher.
+   `--shoot <dir>` gives you frames to check your own work.
+4. **Take feedback, go again.** Several rounds is the point, not scope creep.
+
+**Exit only on an explicit ship signal** ("let's deploy this", "I'm happy with it"). Then `abx inspect
+<script>` and open the deploy decisions.
 
 ## Gate 1 — demo or real launch?
 
 | | **Demo** (`abx demo`) | **Real launch** (`abx deploy` → operate) |
 |---|---|---|
 | Art | generative-from-address | the creator's `--image` |
-| Storage | `fs` (throwaway) | a permanence decision |
-| Host URL | `localhost:8787` | a public URL baked on-chain (off-chain custody only) |
+| Storage | none — the SVG is inlined **on-chain** | a permanence decision |
+| Host URL | none — nothing is hosted, nothing to bake | a public URL baked on-chain (off-chain custody only) |
 | Key | any funded testnet key (the active `ABX_CHAIN`) | the wallet that should **own** it |
 | Decisions | none — just run it | the framework below |
 
@@ -61,41 +173,56 @@ Every write builds an unsigned tx; pick the lane by stakes:
 | **Wallet** | `--sign` | human's own wallet (MetaMask/Ledger) | real value · key shouldn't touch `.env` |
 | **Cold** | `--unsigned` | multisig / offline signer | a Safe / advanced setup |
 
-- **Lane detection:** you hold the key + low stakes → hot. Human owns the valuable wallet → wallet. Multisig → cold. Beyond throwaway testnet, lead with `--sign`.
-- **Missing key is a fork, not a blocker.** If you'd pick hot but `.env` has no key, offer both: add a funded key, or `--sign` in a browser wallet.
-- **On the wallet lane, ALWAYS ask "which wallet will you connect?" and pass `--for <addr>` — don't offer a "just connect whatever" path.** The connecting wallet becomes owner + mint recipient + royalty receiver, so `--for` pins it and makes the sign page + CLI refuse a mismatched wallet (a real session skipped this and let a random connected wallet own the collection). All three deploy commands **warn on `--sign` without `--for`** (*"whichever wallet connects becomes owner + royalty receiver + mint recipient — pass --for to PIN it"*); treat that as a prompt to get the address, not to proceed.
-- **`--for` is a DEPLOY concern, not an owner-op one.** It pins who *becomes* the owner at deploy. Post-launch owner ops (`set-royalty`, `transfer`, `minter configure`, `set-minter`, `pause`, …) already sign as the contract's **current on-chain owner** — the wallet lane targets that automatically — so `--for` isn't needed there (passing it is harmless but ignored). Just connect the owner wallet.
-
-**⚠ `--sign` BLOCKS until the human signs — ALWAYS background it with `--sign-url-file`, NEVER foreground.** Foreground hangs your whole turn (you can't read the URL or talk to the human) and looks frozen. The #1 way agents break the wallet lane. The flow:
-
-1. Background-run `--sign --sign-url-file <path>` (e.g. `/tmp/abx-sign-url`).
-2. Read the URL from that file (fallback: grep output for `ABX_SIGN_URL=`) **every time — never assume the port**. Each op gets a fresh server; if the friendly port (8799) is still busy it auto-falls back to a different one, so the file is the source of truth. Server binds in ~1–2s; poll a couple times.
-3. Relay: "Open `<url>`, connect your wallet, approve." Don't auto-open (node may be remote). Multi-tx → tell them it's N approvals in one session.
-4. Human approves; only the signed tx hash returns.
-5. Let the background command finish (it signs + confirms + re-indexes), then report. Don't kill it.
-
-**⚠ Run wallet-lane ops ONE AT A TIME — never start the next `--sign` op until the previous background command has finished (step 5).** Each op is its own process serving its own page; overlapping them means the human can land on the *previous* action's page, which (having already completed) shows "done" instantly — that "done" is the last op, not the new one. If a session is genuinely stuck (human never signs), the next op will open a *fresh, different* URL — so relay the new URL from the file and tell them to open that one, not the old tab.
-
-- **Sign page is operation-aware** — shows decoded intent ("Transfer #0 → 0x…"), gates on network + signing wallet + the tx, and the CLI refuses a mismatched signer server-side too.
-- **Multi-tx signs in ONE session** (hot + wallet only). `--onchain-image` stages bytes before the deploy that references them; the human connects once and walks `Transaction 1 of N`. Cold can't (staging is interactive) — `--unsigned --onchain-image` errors; use `--send`/`--sign`.
-- **Keep tx count low and say it up front.** A configured token deploys in one tx; `--onchain-image` adds staging tx(s); several owner edits collapse into one atomic `multicall`.
-- **Off-chain storage uploads are NOT wallet approvals — never count them as signatures.** An IPFS upload (Pinata `PINATA_JWT`) or a managed-key Arweave upload happens *before* signing with **no wallet prompt**; only **on-chain staging + the deploy** are approvals. So an off-chain IPFS/Arweave deploy is **one** wallet approval (the deploy). Say it that way — *"1 approval (the deploy); your N images upload to IPFS first, no signature"* — don't fold uploads into the MetaMask count (the classic "2 txs, approve both" mistake). *Exception:* `--storage-signer eth --sign` makes each upload a `personal_sign` in the same session (no gas) — then, and only then, they're approvals too.
+- **Pick it:** you hold the key + low stakes → hot. Human owns the valuable wallet → wallet. Multisig →
+  cold. Beyond throwaway testnet, lead with `--sign`.
+- **A missing key is a fork, not a blocker** — offer both: add a funded key, or `--sign` in a browser.
+- **On the wallet lane ALWAYS ask "which wallet will you connect?" and pass `--for <addr>`.** One connect
+  assigns **all three roles at once** — owner, royalty receiver, mint recipient — so never offer "connect
+  whatever". When you ask, say what you're asking for: **`--for` takes their PUBLIC address (`0x…`), the
+  one they'd paste to receive a transfer — never a private key or seed phrase.** A creator nervous about
+  crypto hears "give me your address" as "give me your keys" unless you say otherwise.
+- **The sign page connects an INJECTED browser wallet only** (`window.ethereum`) — no WalletConnect, no QR.
+  A hardware wallet works through a browser extension that exposes it (MetaMask with a Ledger attached,
+  say), not by scanning a code. Say that before they go looking for a QR.
+- **`--for` is a DEPLOY concern only.** Owner ops already sign as the current on-chain owner; passing it
+  there is harmless but ignored.
+- **One EOA, serialize every send** — two processes sharing a key pick the same nonce and one dies
+  `replacement transaction underpriced`.
+
+**⚠ `--sign` BLOCKS until the human signs — ALWAYS background it with `--sign-url-file`, NEVER
+foreground** (a foreground run hangs your whole turn):
+
+1. Background `--sign --sign-url-file <path>`.
+2. Read the URL **from that file every time — never assume the port** (each op gets a fresh server).
+3. Relay: "Open `<url>`, connect your wallet, approve." Don't auto-open. Multi-tx → say it's N approvals.
+4. Let the background command finish — it signs, confirms and re-indexes. Don't kill it.
+
+**⚠ Wallet-lane ops run ONE AT A TIME** — never start the next `--sign` op until the previous background
+command has finished.
+
+- **The sign page is operation-aware** — decoded intent, gated on network + signing wallet + the tx; the
+  CLI refuses a mismatched signer.
+- **Multi-tx signs in ONE session** (hot + wallet only): the human connects once and walks the sequence.
+- **Keep tx count low and say it up front** — every preview prints `approvals N wallet approval(s)`, the
+  exact signature count.
 
 ## Quick start
 
 **Custody is the master call; resolve it before signing/identity.** The rule, by size:
 
-| Art size | Default | Why |
+| Content size | Default | Why |
 |---|---|---|
-| **Tiny** (≲ 24 KB/file, ≲ 256 KB total) | fully **on-chain** (`--onchain-image --compress fastlz`) | no host, renders forever, cheaper *at this size* |
-| **Bigger / photographic** (most PNG/JPEG) | image **off-chain**, JSON on-chain (`--onchain-uri --backend arweave`) | on-chain is ~200 gas/byte → far more expensive here; Arweave is pay-once permanent |
+| **Small** (≲ 40 KB/file) | fully **on-chain** (`--onchain-image --compress fastlz`) | no host, renders forever, cheaper *at this size* |
+| **Bigger / photographic** (most PNG/JPEG) | image **off-chain**, JSON on-chain (`--onchain-uri --backend arweave`) | on-chain is ~200 gas/byte to write, and the READ is what bites (below); Arweave is pay-once permanent |
 
-On-chain's edge past tiny is self-resolution/permanence, **never cost** — don't call it "cheaper" above the thresholds. The CLI warns when an on-chain image exceeds them.
+On-chain's edge past small is self-resolution/permanence, **never cost** — don't call it "cheaper" above the threshold.
 
-**When the user names off-chain custody for tiny art ("deploy it as an IPFS NFT"), lead with the on-chain recommendation in your *first* reply** — don't bury it, and don't collect resolver-URL details for a path you're about to advise against. "For a 2.4 KB SVG I'd go fully on-chain — no server, renders forever, cheaper. Want that, or IPFS?" Then let them choose (you surface the better default; you don't override the request). Defaulting to "IPFS" for tiny art is what lands it at a broken localhost URI.
+**The real ceiling is READ gas, not storage cost — and 40 KB is the number, not 256 KB.** `tokenURI` reassembles the whole document per call at **~360–405k gas per KB** (quote the range, never one flat rate). So **per token**: **≲40 KB reads fine** (~15M gas) · **40–100 KB warns** (needs a high-gas RPC) · **>100 KB is refused** — a margin below geth's 50M `eth_call` default, because hosted providers cap lower and marketplaces would see a **revert**, not the work. `--compress fastlz` makes it cheaper to *write*, not to *read*. The override `--allow-unreadable-onchain` is a deliberate creator choice ("almost nothing will display your work") — get an explicit yes, never use it to clear a warning; the usual answer is `--backend arweave` instead. Being per token, a 300-piece collection of 5 KB SVGs is fine. Measured table → [decisions.md → The READ ceiling](reference/decisions.md#the-read-ceiling--the-number-that-actually-decides-can-this-go-on-chain).
 
-Tiny-art path:
-1. **Confirm identity** (name, symbol, `--description`, royalty, owner) via the [readout](#confirm-before-sending).
+**When the user names off-chain custody for tiny content ("deploy it as an IPFS NFT"), lead with the on-chain recommendation in your *first* reply** — don't bury it, and don't collect resolver-URL details for a path you're about to advise against. "For a 2.4 KB SVG I'd go fully on-chain — no server, renders forever, cheaper. Want that, or IPFS?" Then let them choose (you surface the better default; you don't override the request). Defaulting to "IPFS" for tiny content is what lands it at a broken localhost URI.
+
+Tiny-content path:
+1. **Confirm identity** (name, symbol, `--description`, royalty, **royalty cap** (permanent, reduce-only), **burnable** (permanent), owner) via the [readout](#confirm-before-sending).
 2. **Deploy + mint in one go:**
    ```bash
    abx deploy --image art.svg --name "…" --symbol … --description "…" --onchain-image --compress fastlz [--sign --for 0x…]
@@ -116,28 +243,56 @@ abx deploy-series --dir <media-dir> --name "…" --symbol … [--onchain-uri --b
 ```bash
 abx deploy-series --dir ./photos --name "My Series" --symbol MS --onchain-uri --backend arweave --mint-all --sign
 ```
-Files natural-sort into **tokens `0…N-1`** (`--count N` uses the first N); a token's metadata is its token id. `--dry-run` and the [readout](#confirm-before-sending) work identically (token count + mint plan). **Content placement is per token — the same custody call as a 1/1 (see [Decisions](#decisions-real-launch)).** The one Series-specific win: a **same-extension folder** uploads as ONE directory/manifest → a single collection `url-template` (O(1) on-chain, any size); mixed extensions fall back to per-token `url` fields (still no server). `cloud` needs `--public-base`. **Per-token traits: `--attributes <file.json>`** — a JSON **array** indexed by token id, or an **object** keyed by filename / token id (each value an attributes array or a `{name:value}` map). **Lane-aware, exactly like the 1/1's traits**: off-chain operator metadata by default (resolver-served, editable later via `abx add <addr> --attributes`), inlined **on-chain** when the token resolves on-chain (`--onchain-uri`) or you pass `--traits-onchain` — small/medium collections; a huge series sets on-chain traits post-deploy via `set-field` under a gas budget. *(For **generative** traits computed from a seed, that's a code project — `abx.traits()` / `--attributes-renderer` — not a static Series.)*
+Files natural-sort into **tokens `0…N-1`** (`--count N` uses the first N); a token's metadata is its token id. **Content placement is per token — the same custody call as a 1/1** (see [Decisions](#decisions-real-launch)). The one Series-specific win: a **same-extension folder** uploads as ONE directory → a single collection-scope image field (O(1) on-chain, any size); mixed extensions fall back to per-token fields (still no server). **Per-token traits: `--attributes <file.json>`**, lane-aware exactly like a 1/1's — off-chain by default, inlined on-chain under `--onchain-uri`/`--traits-onchain`. Accepted shapes, and the huge-series `set-field` route → [operating.md → Series-only owner ops](reference/operating.md#series-only-owner-ops). *(Traits computed from a seed are a code project, not a static Series.)*
 
 ## Code projects (generative / code-based drops)
 
-A **program is the content** (`abx deploy-code` → a `SeriesCode`): output is a function of live on-chain state (`tokenData`: coordinates + `seed` + PostParams), injected at view time. Everything from a [Series](#series-multi-token-drops) applies (mint order, lanes, identity, supply cap, minter, pause). This section is the **decision tree**; the operating depth — what to keep running, the resume loop, verify steps, render ops, lane internals, the arweave delay, selling — lives in **[reference/code-projects.md](reference/code-projects.md)**.
-
-**Infra fork FIRST (before any lane talk): a code project's thumbnail is *rendered* off-chain, so it ALWAYS needs a PUBLIC home you provide — there is NO zero-infrastructure code drop, and "fully on-chain" does NOT mean "nothing to run."** Settle the shape with the creator up front:
-- **Off-chain resolver** (`--public-base-url` + an effects runner, ~a few $/mo) — **the default for a drop you'll sell.** Auto-renders every mint + param change, serves traits with no Solidity, and stays **maneuverable** (metadata/serving evolve with no on-chain surgery) while marketplaces fetch a **small** `tokenURI`.
-- **Fully on-chain** (`--onchain-uri --image-base <a bucket you own>`) — maximal durability, no always-on service. Trade-offs: the whole ~200KB+ doc rides each `tokenURI` (some marketplace/indexer reads choke), **manual** stills (`abx render`), on-chain traits need a deployed renderer, later changes are on-chain re-points. Choose it deliberately when permanence outweighs maneuverability. *(The one zero-infra-AND-on-chain exception: the in-chain **Solidity** lane below.)*
-
-**Writing the program yourself (the creator brought an *idea*, not a file)? There's ONE runtime contract — get it right or the drop is silently broken** (seed never injects → every token identical; traits empty). The program reads state via **`abx.tokenData`** (a flat object: `.seed`, and each `--schema` key flat, e.g. `.palette`) and reports traits via **`abx.traits({…})`** — never an invented global (`window.tokenData`, `window.tokenTraits`) and never "defensively across variants." `abx.traits()` is the ONLY thing captured into `attributes`, on the resolver lane too. Verify with `abx inspect` (its **PostParams** + **Traits** lines reflect what the program actually reads/reports — if they're empty but you intended a param/traits, you read it the wrong way), THEN pick a lane. Full contract: [reference/code-projects.md → Authoring the program](reference/code-projects.md#authoring-the-program--the-abxjs-runtime-contract-get-this-right-first).
-
-**Run `abx inspect <script>` before proposing any lane, then adopt the recommended lane it prints — don't hand-assemble a different flag set.** (Exception: the in-chain **Solidity-render** lane below has no JS script to inspect — go straight to it. `abx inspect` only analyzes a JS file.) A code project has surfaces that each must land *somewhere public* — the fatal mistake (seen in real sessions) is picking *“fully on-chain, no server!”* and only discovering, one at a time after deploy, that it carries no thumbnail, no traits, and dropped a PostParam. **These are all DEPLOY-TIME decisions — an on-chain field with no pointer CANNOT be backfilled** (least of all to localhost). `abx inspect` and `deploy-code --dry-run` print a **Surfaces block** grading each one; **every ⚠ there is a marketplace-facing hole you must close before deploy — trust it over your own read.** Resolve all of them into ONE coherent lane with the creator BEFORE you collect identity or show a config:
+A **program is the content** (`abx deploy-code`): output is a function of live on-chain state
+(`tokenData`: coordinates + `seed` + PostParams), injected at view time. Everything from a
+[Series](#series-multi-token-drops) applies. This section is the **decision tree**; operating depth —
+what to keep running, the resume loop, verify steps, render ops, lane internals, selling — lives in
+**[reference/code-projects.md](reference/code-projects.md)**.
+
+**The mint `seed` is pseudorandom, NOT lottery-grade — say so before a creator prices scarcity off it.** Every mint draws it from the canonical `AbxSeedSource` (block values + token id). It replays afterwards (that is what makes the output verifiable) but is **not secret beforehand**: a contract minting in the same tx can compute the seed it would get and revert unless it likes it. Fine when the seed diversifies the work and the distribution *is* the product; **not** fine for a raffle or any drop where one rare outcome is worth materially more than mint price — that needs the creator's own `IAbxSeedSource` (commit-reveal/VRF), a first-class swap at both ends (`deploy-code --seed-source 0x…`, `abx set-seed-source`). Who picks differs by lane, and a `seed` schema lets an authorized party choose the value outright → [code-projects.md → Seeds](reference/code-projects.md#seeds--pseudorandom-not-lottery-grade).
+
+**Infra fork FIRST, before any lane talk: a code project's thumbnail is *rendered* off-chain, so it
+ALWAYS needs a PUBLIC home you provide.** There is NO zero-infrastructure code drop, and "fully
+on-chain" does NOT mean "nothing to run". Two shapes — an **off-chain resolver** (`--public-base-url`,
+the default for a drop you'll sell: auto-renders every mint and param change, stays maneuverable; a
+managed provider with `render.attached` covers both halves with one key), or **fully on-chain**
+(`--onchain-uri --image-base <a bucket you own>`: maximal durability, no always-on service, but stills
+are manual, on-chain traits need a deployed renderer, and the whole document rides each `tokenURI` at
+~360–405k gas/KB — `deploy-code --dry-run` prints the figure, relay it). Settle this with the creator
+first. *(The one zero-infra-AND-on-chain exception is the in-chain Solidity lane below.)*
+
+**Writing the program yourself? There is ONE runtime contract — get it right or the drop is silently
+broken** (seed never injects → every token identical; traits empty). The program reads state via
+**`abx.tokenData`** (flat: `.seed`, and each `--schema` key) and reports traits via **`abx.traits({…})`**
+— never an invented global, never "defensively across variants". `abx.traits()` is the ONLY thing
+captured into `attributes`, on the resolver lane too. Verify with `abx inspect` before picking a lane:
+its PostParams and Traits lines reflect what the program *actually* reads and reports. Full contract →
+[code-projects.md → Authoring the program](reference/code-projects.md#authoring-the-program--the-abxjs-runtime-contract-get-this-right-first).
+
+**Run `abx inspect <script>` before proposing any lane, and adopt the lane it recommends.** A code
+project has surfaces that must each land somewhere public, and the fatal mistake is picking "fully
+on-chain, no server!" then discovering one at a time, after deploy, that it carries no thumbnail, no
+traits, and dropped a PostParam. **Settle these BEFORE you deploy.** They are not impossible to
+change afterwards — the honest cost is an owner-signed **re-point tx** (`set-field image <public url>`)
+plus a re-render, on a collection that has been showing a placeholder in the meantime. `abx inspect` and `deploy-code --dry-run` print a **Surfaces block** grading
+each one; **every ⚠ there is a marketplace-facing hole to close before deploy — trust it over your own
+read.** Resolve them into ONE coherent lane before collecting identity or showing a config:
 
 | Surface | On-chain | Off-chain |
 |---|---|---|
 | **tokenURI + animation** | `--onchain-uri` — *if* script + every dep fit one `tokenURI` eth_call (`abx inspect` estimates) | a resolver (`--public-base-url`) |
-| **thumbnail (`image`)** | ❌ never computed on-chain — needs a public destination: `--image-base <S3/R2/CDN you own>`. **No destination ⇒ placeholder FOREVER + orphaned render, not backfillable. Never localhost.** | a resolver's `/image` |
+| **thumbnail (`image`)** | ❌ never computed on-chain — needs a public destination: `--image-base <S3/R2/CDN you own>`. **No destination ⇒ placeholder + an orphaned render until you re-point (`set-field image` + re-render, owner-signed). Never localhost.** | a resolver's `/image` |
 | **traits (`attributes`)** | a Solidity `--attributes-renderer 0x…` you **DEPLOY** (fork `SeedTraitsRenderer`) — **not a free flag or guessable address** (`deploy-code` refuses a codeless one; "ports to Solidity" ≠ "deployed") | a resolver stitches the JS `abx.traits()` |
 | **PostParams** | declare EVERY key the script reads: `--schema key:Type:Auth` (a palette collectors set = `palette:HexColor:TokenOwner`) — else silently dropped at render | — |
 
-**The resolver is the pivot: choosing *no resolver* forecloses the off-chain column for thumbnail + traits.** (On `--onchain-uri`, an unauthenticated Etherscan "Read Contract" can hit its gas cap on the big doc and look like a revert — expected; verify with `abx tokenuri`, never `abx index --full` to "fix" it. Diagnosis depth → [reference/troubleshooting.md](reference/troubleshooting.md).)
+**The resolver is the pivot: choosing *no resolver* forecloses the off-chain column for thumbnail and
+traits.** (On `--onchain-uri`, an unauthenticated Etherscan "Read Contract" can hit its gas cap on a big
+document and look like a revert — expected; verify with `abx tokenuri`, never `abx index --full` to
+"fix" it. → [troubleshooting.md](reference/troubleshooting.md).)
 
 **Pick your code lane** (all `abx deploy-code`):
 
@@ -147,61 +302,58 @@ A **program is the content** (`abx deploy-code` → a `SeriesCode`): output is a
 | Script + a library on-chain (e.g. `p5@1.0.0`, **Sepolia only** — needs the AB dependency registry, absent on Base Sepolia) | `--script f.js --onchain-uri --dep p5@1.0.0` | **fully on-chain** — *iff the dep report says “ON-CHAIN bytes available”* |
 | Script + a CDN-only library, or very large params | `--script f.js --public-base-url https://…` | **resolver lane** — you host a resolver; live metadata |
 | A pre-built app (webpack/vite output) | `--code-dir build/` (+ `--onchain-uri` or `--public-base-url`) | **no server to run**, gateway-served → **never** chain-complete (8KB param budget) |
-| A **Solidity renderer** (SVG on-chain, from seed+params) | `--image-renderer 0x<svg> [--attributes-renderer 0x<traits>] --onchain-uri` (**no `--script`**) | **truly in-chain** — image + traits computed on-chain, tokenURI on-chain, **zero infra** |
-
-**⭐ In-chain Solidity lane — recommend on-chain `tokenURI` without hesitation.** The artwork is a Solidity `IAbxFieldRenderer` returning an SVG from seed+params (not a JS program), wired `--image-renderer 0x… [--attributes-renderer 0x…] --onchain-uri` with **no `--script`/`--code-dir`**: image AND traits computed on-chain, `tokenURI` assembled on-chain — **genuinely nothing to run** (a small SVG, so the large-`tokenURI` caveat doesn't apply). **NOT no-code, though**: the renderer is a contract the creator compiles + deploys with Foundry. **`abx scaffold-renderer <dir>`** writes a ready-to-build project (worked renderer + coherent traits + the interfaces with invariants + never-revert tests + deploy script); they `forge test`, deploy, and hand the address to `--image-renderer 0x…` (which verifies code-at-address, never compiles/deploys Solidity). Not comfortable with Solidity? Steer to the resolver or (tiny static SVG) `--onchain-image`. Depth → [reference/code-projects.md](reference/code-projects.md#in-chain-solidity-svg--the-zero-dependency-lane) · interface/invariants → https://abx.docs.artblocks.io/protocol/renderers/.
+| A **Solidity renderer** (SVG on-chain, from seed+params) | `--image-renderer 0x<svg> [--attributes-renderer 0x<traits>] --onchain-uri` (no `--script`) | **truly in-chain** — image + traits computed on-chain, tokenURI on-chain, **zero infra**; no `animation_url` (no program) |
+| **A JS program AND on-chain thumbnail/traits** — the both-worlds shape | `--script f.js --image-renderer 0x<svg> --attributes-renderer 0x<traits> --onchain-uri` | **every surface in-chain, zero infra** — `animation_url` assembles from the script chunks, `image`+`attributes` computed by Solidity. **Nothing to render or host.** |
+
+**`--script` and `--image-renderer` are NOT an either-or** — passing both is the strongest shape
+available and the most-missed: the program drives `animation_url` on-chain while Solidity renderers
+supply `image` and `attributes`, so an interactive generative piece gets a real thumbnail and real
+traits with **no resolver, no runner, no bucket**.
+
+**⭐ The in-chain Solidity lane — recommend on-chain `tokenURI` without hesitation.** The work is a
+Solidity `IAbxFieldRenderer` returning an SVG from seed+params, wired with no `--script`: image and
+traits computed on-chain, **genuinely nothing to run**. **Not no-code, though** — the renderer is a
+contract the creator compiles and deploys with Foundry (`abx scaffold-renderer <dir>` writes a
+ready-to-build project; `abx` never compiles or deploys Solidity). Not comfortable with Solidity? Steer
+to the resolver, or `--onchain-image` for a tiny static SVG. Depth →
+[code-projects.md](reference/code-projects.md#in-chain-solidity-svg--the-zero-dependency-lane).
 
 ## Decisions (real launch)
 
-Master call is **custody × mutability**:
-
-| | **Mutable** (name/desc/traits may change) | **Immutable** (never changes) |
-|---|---|---|
-| **Tiny static** (≲ 24 KB/file, ≲ 256 KB total) | **on-chain renderer** — `--onchain-image --compress fastlz`. No host, mutable via `set-field`, permanent. | on-chain renderer + `lock-field` + `lock-uri` once it resolves. |
-| **Bigger / dynamic** (most PNG/JPEG) | **image off-chain, JSON on-chain, no server** — `--onchain-uri --backend arweave` (or `ipfs`). Renderer assembles JSON pointing at the bytes; many files → one `url-template` (O(1)). For metadata you edit often, a **hosted resolver** instead (`abx deploy-resolver`, [hosting.md](reference/hosting.md)). Not fully on-chain (~200 gas/byte). | image off-chain (Arweave = permanent) + on-chain renderer + `lock-field`/`lock-uri`. Or a frozen `ipfs://` override + `lock-uri`. |
-
-**Four patterns, by where bytes live × how `tokenURI` resolves:**
-1. **Fully on-chain** (`--onchain-image`) — bytes + JSON on-chain. Tiny art only.
-2. **Image off-chain, JSON on-chain, no server** (`--onchain-uri --backend arweave|ipfs|cloud`) — the sweet spot for static art. Arweave/IPFS (permanent, content-addressed) or your S3/CDN (`--backend cloud --public-base <url>`; centralized, mutable). Many files → one `url-template`.
-3. **Hosted resolver** (`--public-base-url` + `abx deploy-resolver`) — for mutable/dynamic metadata; you run a node.
-4. **Inline SVG on-chain** — self-contained vector art inlined into `tokenURI`. For a **1/1** that's `abx deploy … --onchain-uri`; for a **Series** of tiny SVGs use `abx deploy-series … --onchain-image --compress fastlz` (bare `--onchain-uri` on a folder does NOT inline the images — it's the image-custody flag `--onchain-image` that puts SVG bytes on-chain per token).
-
-**Picking IPFS (or Arweave) does NOT mean running a server.** The `--onchain-uri --backend ipfs|arweave` path (pattern 2) bakes the image's public **gateway** URL into on-chain JSON — a pinning service's read endpoint (a *dedicated* Pinata gateway for IPFS), not a resolver you host. So when a creator chooses IPFS, **default to this no-server path** — image on IPFS, JSON on-chain, nothing to keep running (just keep the pin alive). You only need a **hosted resolver** (pattern 3) if they want *freely editable* metadata. Never present IPFS as blocked on "a public URL" or "a server always online": the gateway belongs to the pinning service and the JSON lives on-chain. (The one real input IPFS needs is `PINATA_JWT` in `.env` for pinning — that's an API upload, not a host.)
-
-**No-server tradeoff (patterns 1, 2, 4):** with the on-chain renderer only the *image* is off-chain — any **description / traits / animation_url live on-chain** (gas to write, permanent, lockable), vs a hosted resolver where they're free to edit. Cheap (a shared value is **one collection-scope field**, not one per token — the renderer falls back token→collection), but the creator should choose "no server" knowing their text metadata is on-chain.
-
-Get decisions 1–2 right before deploy (image commitment + resolver URL are written then; re-pointable, but):
+**Custody is the master call** — size decides it ([Quick start](#quick-start) has the rule and the READ
+ceiling; do not restate the numbers, they live there). Four patterns, by where bytes live × how
+`tokenURI` resolves — name the one you're proposing, then configure it from
+[decisions.md](reference/decisions.md):
 
-**1. Storage permanence** — where bytes live. Not irreversible: bytes are content-addressed by their on-chain keccak, so start on one backend and move later (`abx verify` confirms the hash). Don't let it block a first deploy.
-- `arweave` = pay-once permanent, no recurring fee. `cloud` (S3/R2) = durable, you maintain it. `ipfs` = decentralized, you pin it. `fs` = zero-config start, dies with the disk → move before it matters.
-- **`arweave` is nearly as easy as `fs` for small art** — Turbo default: **under 100 KB free, no setup** (a managed `.abx-self-host/arweave-key.json` minted on first upload; back it up with `abx storage backup-key`). Choose per command with `--backend` (stateless, no config file); a backend missing its secret falls back to `fs`.
-- **Who pays is a lane (`--storage-signer`)** — Turbo credits attach to an identity (managed key · `.env` key · browser wallet). **Before any top-up, check BOTH balances** (`abx storage balance --backend arweave` shows the managed key AND the wallet — spend the wallet's credits if present). On an upload error surface it verbatim — `…already been uploaded…` is *success* (dedup); don't reflexively top-up or switch to IPFS. Full lanes + failure playbook → [hosting.md](reference/hosting.md#arweave-via-turbo--the-easy-permanent-path-read-before-quoting-setup).
+1. **Fully on-chain** (`--onchain-image`) — bytes *and* JSON on-chain. Small content only.
+2. **Image off-chain, JSON on-chain, no server** (`--onchain-uri --backend arweave|ipfs|cloud`) — the
+   sweet spot for static content.
+3. **Remote resolver** (`--public-base-url` + a node) — mutable/dynamic metadata; self-hosted or managed.
+4. **Inline SVG on-chain** — self-contained vector. 1/1 → `--onchain-uri`; a Series of SVGs →
+   `--onchain-image --compress fastlz`.
 
-**2. Public host URL** — where the resolver runs (**off-chain custody only**). Baked into `tokenURI` at deploy, so the CLI **refuses an off-chain deploy without a public URL** (`ABX_PUBLIC_BASE_URL` or `--public-base-url https://…`) and **never bakes localhost** (that token resolves for no one). No exceptions.
-- **First ask whether you need a host at all** — tiny art is cheaper and more durable on-chain (no host). For bigger art, Arweave (no host to run) beats a resolver unless you need mutability or serve many files.
-- **Tunnels (ngrok/cloudflared) are preview-only — never bake one on-chain** (dies on sleep, rotates on restart). A real launch puts the resolver on a host you control under your own domain (move = a DNS re-point).
+The second axis is **mutability**: any pattern stays editable until you freeze it, so ship unlocked,
+confirm it resolves, then lock (see *Store ≠ lock* below).
 
-**3. Identity** — `--name`, `--symbol`, `--royalty-bps` (default 500 = 5%), `--description "…"`, `--external-url <url>` (both served in the metadata — set them or the description is boilerplate). Owner + royalty receiver = the deploying wallet. These default to off-chain operator metadata (editable via `abx add <addr> --description "…"`). For a description that should outlast any node, add `--description-onchain` (or later `abx set-field <addr> --field description --text "…"`) → on-chain, freezable via `lock-field`; the resolver prefers the on-chain value. This is the per-field on-chain model — any field on-chain or off, one active `representation` (inline · reader · keccak256 · arweave · ipfs · url). Background: [metadata model](https://abx.docs.artblocks.io/protocol/metadata/).
-- **Credit + license** — deploy flags `--artist "…"` · `--license "…"` (also `--display-notes`, `--artist-links`) bake authorship + rights ON-CHAIN in the deploy tx (all three deploy commands); or set/change them later with `abx set-field <addr> --collection --field artist|license --text "…"`. Reserved collection fields served in `contractURI`, on any type (1/1 · Series · code). Detail: [operating.md → Authorship + rights](reference/operating.md#authorship--rights-credit--license).
-- **Propose a real name/symbol and confirm — never silently bake a generic folder-name guess.** A folder called `series`/`images`/`photos` infers junk ("Series" / "SRS"), and the CLI *refuses* demo defaults without `--name`/`--symbol` precisely because on-chain identity is effectively permanent. Suggest a specific title + a short ticker-style symbol drawn from the actual work, and get an explicit yes before deploying. Inference is a suggestion to confirm, not a default to ship — if the folder name is generic, say so and ask rather than proposing it.
+**IPFS/Arweave is NOT a server.** Pattern 2 commits the bare CID/txid on-chain and the renderer joins it
+to the collection's gateway prefix at read time — nothing to keep running, and the gateway is a one-tx
+repoint (`abx set-gateway`), not a value welded into the field. Only pattern 3 needs a resolver. Never
+tell a creator IPFS is blocked on "a public URL" or "a server always online".
 
-**4. Image placement** — `--image <path>` (png · jpg · gif · svg · webp). The on-chain keccak256 (`image` field) anchors integrity; size is bounded by the backend, not the chain.
-- *Off-chain:* the served `image` is the backend's **gateway HTTPS URL** (`https://<gateway>/ipfs/<cid>`), not raw `ipfs://` (wallets/marketplaces can't render that). So off-chain needs a pinning service + a **public** gateway — with Pinata use a **dedicated** gateway (`--gateway https://<you>.mypinata.cloud`); a local kubo gateway is preview-only. The keccak stays the anchor → move gateways without a tx.
-- *Fully on-chain:* `abx set-field <addr> --field image --file <path> [--compress fastlz]` splits into SSTORE2 chunks behind the shared reader; or bake it in with `abx deploy --image <path> --onchain-image [--compress fastlz]`.
+**The six decisions** — storage permanence · public host URL · identity · image placement · on-chain
+vs off-chain resolution · when to mint. Full detail, tradeoffs and failure modes:
+**[decisions.md](reference/decisions.md)**. The four that can go permanently wrong, in brief:
 
-**Inline vs reader — default to the reader for real artwork.** `--onchain-uri` alone inlines the SVG (1 tx, ~700 gas/byte); `--onchain-image --compress fastlz` stages via SSTORE2 + a small `reader` pointer (~200 gas/byte, +1 tx) — **cheaper above ~0.5 KB** and widening with size. So: tiny (<~0.5 KB, a one-line SVG/short text) → `--onchain-uri` inline; real artwork (a few KB+) → `--onchain-image --compress fastlz`. **Never `--compress gzip` for an on-chain-rendered token** — gzip decodes off-chain only, breaking `--onchain-uri`; use fastlz (it decodes *in* the reader).
-
-**5. On-chain vs off-chain resolution** — by default `tokenURI`/`contractURI` point at your resolver. `--onchain-uri` = JSON assembled *on-chain* by the shared `AbxMetadataRenderer`, self-resolving forever — so it pairs with on-chain content, cost-effective only for tiny art (thresholds above).
-- **Fully on-chain = no server.** Don't stand one up; never cite a localhost URL. **Prove it with `abx tokenuri <addr>`** (reads `tokenURI(0)` over RPC, no `serve`). `abx serve` is only for off-chain-resolving tokens.
-- **The off-chain `tokenURI` is a base, not a per-token URL** — the contract stores a base and derives `{base}/{chainId}/{address}/{tokenId}`. Set via `--public-base-url` or `set-token-uri --uri <base>` later.
-- **Don't default to a frozen `ipfs://` tokenURI** — every edit then = re-pin + on-chain re-point, and the event spine stops driving the token (exiting the spec). Right only for true immutability, then lock it (`set-token-uri --override ipfs://<cid>` then `lock-uri`).
-- **Store ≠ lock; lock last.** On-chain ≠ frozen. Deploy unlocked, confirm it resolves in production, *then* freeze. Two locks: `lock-field <addr> --field <name>` (a value) + `lock-uri <addr>` (how it resolves). Both = provably immutable. A deliberate follow-up, not the first deploy.
-
-**6. When to mint** → [Deploy strategy](#deploy-strategy--when-to-mint).
+- **Never bake localhost** into an off-chain deploy — that token resolves for no one. The CLI refuses it; don't try to talk it round.
+- **Propose a real name/symbol and get an explicit yes** — on-chain identity is effectively permanent, and a generic folder name infers junk. The CLI refuses a real send that would bake its own placeholder (a `--dry-run` only warns — that is not permission).
+- **Store ≠ lock; lock last.** Deploy unlocked, confirm it resolves in production, *then* freeze (`lock-field` / `lock-uri`; a code drop also needs `lock-script` + `lock-dependencies`). A deliberate follow-up, never the first deploy.
+- **Say "locked metadata", never "immutable work".** Locks freeze what the contract *stores* — and every one freezes a **pointer or a value, never behavior** (a locked renderer can still be a proxy that is upgraded later). An **ungoverned PostParam has no lock at all**; a schema'd one can be welded. The lock a **buyer** actually asks about is `lock-param-hooks`, because a `--transfer` hook is a **veto** over whether they can ever sell. A live-adapting token is a fine thing to build — just never sell a frozen one as frozen unless it is. Rules, exceptions, and what to check before any permanence claim → [decisions.md → Locks](reference/decisions.md#locks--what-actually-freezes-and-what-a-buyer-is-really-asking).
+- **Tunnels (ngrok/cloudflared) are preview-only** — never bake one on-chain.
 
 ## Confirm before sending
 
-Run `abx deploy --dry-run` for real values, present **this exact shape** — one row per on-chain value — then wait for go-ahead. **Mirror the dry-run's values; don't compose your own.**
+`abx deploy --dry-run` for real values (pin the salt it prints with a second `--dry-run --salt …`).
+**No key in `.env`? `--dry-run` still needs a deployer — pass `--for 0x<the creator's wallet>`.**
 
 ```
 Deploy config — confirm before I send (everything below is written on-chain):
@@ -223,17 +375,23 @@ Deploy config — confirm before I send (everything below is written on-chain):
 ```
 
 Rules:
-- **The readout is a contract: what's shown is *exactly* what deploys.** Every value = a flag you pass. Not going on-chain → the row says `none`, never an invented placeholder.
-- **Every line must be *verified*, never aspirational — a value that depends on an external contract that must already exist** (`--attributes-renderer`, `--minter`, a `0x…` `--dep`, a gateway) **may appear as committed only once the dry-run confirms it resolves.** Never bake in a guessed/placeholder address; if it's unverified, show it `⚠ requires <X> — not yet deployed/verified` or leave the surface out. (The real-session trap: presenting "Traits computed on-chain via `--attributes-renderer 0x…`" off a *guessed* address — `deploy-code` now refuses an address with no code, so trust the dry-run over the assumption.)
-- **Flag every inferred/defaulted value** with `⚠` + where it came from (name/symbol from filename, royalty default, owner = signing key).
-- **The description is the one people forget** — never deploy an auto-written or empty description quietly. State what's written and whether it's on-chain (`--description-onchain`) or off. For a real piece, ask for the creator's words.
-- **Traits are the creator's** (the OpenSea `attributes` array) — ask (`--traits "Background=Blue"` or `--attributes file.json`); never invent traits, never put protocol facts there. Off-chain by default; `--traits-onchain` to commit them.
-- **Show real values** — the real name, description, address + pinned salt, chunk/tx count from the dry-run.
-- Adapt rows to the config (off-chain shows storage backend + host URL instead of the renderer; `--no-mint` shows a deferred mint) — but always one row per written value, always the ⚠ flags, always an explicit confirm.
+- **The readout is a contract: what's shown is *exactly* what deploys.** Every value is a flag you pass;
+  anything not going on-chain says so.
+- **Every line is verified, never aspirational.** A value depending on a contract that must already exist
+  (`--attributes-renderer`, a minter) is only claimed once checked.
+- **Flag every inferred or defaulted value** with `⚠` and where it came from.
+- **The description is the one people forget** — never deploy an auto-written or empty one quietly.
+- **Traits are the creator's** — ask; never invent them.
+- **Show real values**: real name, description, address + pinned salt, chunk/tx counts from the dry run.
+- Adapt rows to the config (off-chain shows backend + host URL instead of the renderer; `--no-mint` shows
+  a deferred mint) — but always show what is written on-chain.
 
 ## Deploy strategy — when to mint
 
-The deploy address is **deterministic** — a pure function of `(factory, salt)`, knowable before signing (`abx predict`). So you can warm the resolver at that exact address first → the moment a marketplace sees the mint it fetches live metadata, not a cached blank. Minting is optional at deploy (`--no-mint`); there's a one-shot `abx mint`.
+The deploy address is **deterministic** — a pure function of `(factory, salt)`, knowable before signing
+(`abx predict`). So you can warm a resolver at that exact address first, and the moment a marketplace
+sees the mint it fetches live metadata rather than a cached blank. Minting at deploy is optional
+(`--no-mint`); `abx mint` is the one-shot.
 
 | Path | When | Flow |
 |---|---|---|
@@ -241,68 +399,110 @@ The deploy address is **deterministic** — a pure function of `(factory, salt)`
 | **Careful** *(real launch, off-chain resolver)* | metadata live the instant it's listable | `deploy --no-mint` → `serve` (warm) → verify → `mint` → `refresh` |
 | **Primary sale** | token issued at point of sale | `deploy --no-mint` → settle off-chain → `mint --to <buyer>` → `refresh` |
 
-- **Fully on-chain ⇒ mint at deploy; do NOT add `--no-mint`.** The careful path warms an *off-chain resolver*; a fully on-chain token has none (the renderer resolves the instant the contract exists). Deferring buys nothing and adds a tx. Defer an on-chain mint only for a genuine primary sale.
-- **`abx predict [--salt 0x..] [--for 0x..]`** pre-computes the address. No `--salt` → reserves a fresh, front-run-proof salt to the deployer; pass `--salt` for a vanity/known address. The salt's leading 20 bytes are an access guard: zero ⇒ anyone may deploy; non-zero ⇒ only that signer.
-- **The address depends on the salt — preview one, you MUST pin it.** Without `--salt`, every invocation (incl. `--dry-run`) reserves a *fresh* salt → a plain `deploy` lands at a different address than the dry-run showed. `--dry-run` prints the exact `--salt …` it used; pass that same salt to the real deploy. Never quote a previewed address without pinning its salt.
-- **`abx refresh <addr>`** asks marketplaces to re-index. We emit **ERC-4906** on URI changes so 4906-aware marketplaces self-refresh; `refresh` is the fallback (+ genesis mint). With `OPENSEA_API_KEY` it calls OpenSea directly; else it prints the links to click.
-- **There is no "add it to a marketplace" step — don't offer one.** Marketplaces discover the collection from chain (the mint + ERC-4906); `abx refresh` is the only nudge. Suggesting a manual listing implies work that doesn't exist.
-- A `--no-mint` deploy reconstructs + serves normally (dashboard shows #0 "not yet minted"; metadata/image already resolve).
-- **Etherscan source is already verified** — your deploys are EIP-1167 clones Etherscan auto-recognizes as proxies of the verified implementation.
+- **Fully on-chain ⇒ mint at deploy; do NOT add `--no-mint`.** The careful path warms an *off-chain
+  resolver*; a fully on-chain token has none — the renderer resolves the instant the contract exists, so
+  deferring buys nothing and costs a tx. Defer an on-chain mint only for a genuine primary sale.
+- **There is no "add it to a marketplace" step — don't offer one.** Marketplaces discover the collection
+  from chain (the mint, plus ERC-4906 on either lane); `abx refresh` — and `abx ping-uri` on an edition —
+  is the only nudge. The App Store is a separate opt-in, never folded into deploy.
 
-## What a token carries — files beyond the image (the data plane)
+`abx predict` and salt guards, the `--dry-run`-without-`--salt` rule, ERC-4906 vs the edition's native
+`URI` event, and why Etherscan already shows verified source →
+[operating.md → Deploy strategy](reference/operating.md#deploy-strategy--the-mechanics).
 
-A token is **not "just a picture."** It anchors **named, typed files** ("artifacts"), and the served metadata JSON carries an **`artifacts`** list — the *complete* set of the token's files, each `{key, mimeType, uri}`. The `image` / `animation_url` are just reserved members of that same set; alongside them a token can carry a hi-res master, a certificate, source files, a README — any number of named files. (Background: [data plane](https://abx.docs.artblocks.io/protocol/data-plane/).)
+## List in the ABX App Store (optional)
 
-```json
-"artifacts": [
-  { "key": "image",   "mimeType": "image/svg+xml", "uri": "…/image" },
-  { "key": "print",   "mimeType": "image/tiff",    "uri": "ipfs://Qm…/master.tiff" },
-  { "key": "readme",  "mimeType": "text/markdown; charset=utf-8", "uri": "ar://…/README.md" }
-]
-```
+**Not part of deploy, ever.** After the collection is live, ask once: *want this listed in the ABX App
+Store?* If no, stop. If yes it is a second, explicit opt-in — minting a token in the store registry —
+and **not** marketplace discovery. Draft the store copy *with* the creator (`--name`/`--summary`/
+`--description` describe what someone can **do**, not the NFT's metadata — never silently reuse the
+deploy's). You run `abx submit-app`, `--dry-run` first. The wallet must **own the collection** at mint.
+Full command, the multi-tx write, and the humans-use-`/submit` alternative →
+[operating.md → App Store](reference/operating.md#listing-in-the-abx-app-store--abx-submit-app).
 
-- **Attach a file:** `abx attach <addr> <key> <ipfs://… | ar://… | https://…>` — `<key>` is any name you choose (`print`, `certificate`, `stems`, `readme`) and becomes the manifest entry's key. The representation is **auto-detected** from the URI scheme; the `mimeType` is declared from the file **extension** (`…/master.tiff` → `image/tiff`), so point the URI at the file itself. Tiny bytes with no external host can go **on-chain** with `--file <path>`. Token scope by default; `--collection` for a collection-wide file. Any signing lane; `--dry-run` previews. It's one file per call, run **after deploy**.
-- **Don't have a URL yet? Upload first.** `attach` takes a locator you already host. `abx storage upload <path> --backend arweave|ipfs` uploads one file and prints a locator that **keeps the filename** (so the declared type survives) plus the ready-to-run `attach` line (Arweave = pay-once permanent; the same backends `deploy` uses; `--dry-run` to preview without uploading). Full flow: `abx storage upload master.tiff --backend arweave` → copy the printed locator → `abx attach <addr> print <that-locator>`.
-- **`artifacts` is COMPUTED, never a field you set.** The resolver/renderer assembles the list from your fields — setting a field literally named `artifacts` is refused. You attach one file per key; the manifest builds itself.
-- **The complete listing is a resolver surface.** A resolver serves the full `artifacts` list at `/t/<chainId>/<addr>/<id>`, and `/data/<key>` fetches each file. The bare on-chain `tokenURI` enumerates **reserved fields only** (there's no on-chain enumeration of arbitrary keys) — so a project that must surface extra files to consumers today runs a resolver (attached files are still stored on-chain + keccak-anchored regardless).
-- **Effect outputs are artifacts too.** A code project's effect runner publishes `render/image`, `render/traits`, and any extra declared output (e.g. a hi-res `render/print`) into the same manifest automatically, at the current settled state — files appear as tokens are minted and params change (see [code-projects](reference/code-projects.md)).
-- **Not the same as a Series.** `deploy-series` makes **N separate tokens, one file each**. The data plane is how **one** token holds several named files. Depth (representations, verify, reserved keys, on-chain-vs-resolver) → [operating.md](reference/operating.md#attaching-files--the-data-plane).
-- **Set expectations honestly (say it up front).** No mainstream marketplace (OpenSea/Blur) shows a "files" tab **today** — they render `image`/`animation_url` only. Attached files are a durable, cryptographically-anchored part of the token *now*, read by **data-plane-aware tools and any resolver**; broad marketplace display is future adoption. So a creator verifies an attach by **curling their resolver's listing**, not by refreshing OpenSea (which won't show it).
+## What a token carries — files beyond the image (the data plane)
+
+A token is **not "just a picture."** It anchors **named, typed files**, and the served JSON carries an
+**`artifacts`** list — the *complete* set, each `{key, mimeType, uri}`. `image`/`animation_url` are
+reserved members of that same set; alongside them a token can carry a hi-res master, a certificate,
+source files, a README.
+
+- **Attach:** `abx attach <addr> <key> <ipfs://… | ar://… | https://…>` — `<key>` is any name you pick.
+  Representation is auto-detected from the scheme; `mimeType` comes from the file **extension**, so
+  point the URI at the file itself. Tiny bytes with no host can go on-chain with `--file`. One file per
+  call, after deploy.
+- **No URL yet?** `abx storage upload <path> --backend arweave|ipfs` prints the locator `attach` wants
+  (and the ready-to-run `attach` line). Hand `attach` the `ipfs://`/`ar://` form, never a gateway URL —
+  an `https://` locator is stored as an opaque `url` with the host welded in.
+- **`artifacts` is COMPUTED, never a field you set** — the manifest builds itself from your fields.
+- **Say the honest limit up front:** no mainstream marketplace shows a files tab **today**. Verify an
+  attach with `abx tokenuri <addr> --fetch`, not by refreshing OpenSea.
+
+Resolver-vs-on-chain reach, effect outputs, reserved keys, and the params exception →
+[operating.md → Attaching files](reference/operating.md#attaching-files--the-data-plane).
 
 ## After launch — tell the creator (durability + owner care)
 
-Once it's live, cover these in plain language; don't wait to be asked.
+Cover these in plain language once it's live; don't wait to be asked.
 
-- **Durability depends on the backend.** Arweave = **pay once, kept for centuries** (a storage endowment funds ~200 years; resolves as long as the network + any gateway are up) — nothing to renew. IPFS/Pinata = **the creator must keep it pinned** — the image serves through their gateway, and if pinning lapses the bytes can disappear. `cloud`/`fs` = they maintain them. Say which one this drop uses and what it implies. For a real drop, lead toward Arweave (or start elsewhere and re-host later — bytes are keccak-anchored, so re-upload to the new backend + re-point with `set-field`, verified by `abx verify`).
-- **Moving backend/gateway later is an owner-signed on-chain edit.** The on-chain keccak anchors the bytes so they're portable, but re-pointing (`set-field`/`migrate`) is a tx from the **owner** wallet — so that wallet must stay secure and reachable.
-- **Owner-wallet hygiene (suggest as follow-ons).** The owner wallet controls mint, royalties, URIs, and ownership itself. Recommend: a hardware/dedicated wallet over a throwaway hot key; for anything valuable, hand ownership to a multisig (`abx set-admin <addr> --to <safe>`); and **back up `.abx-self-host/arweave-key.json`** — it holds any prepaid Turbo credits, lose it and they're stranded.
+- **Durability is the backend's, and they differ.** Arweave = pay once, kept for centuries, nothing to
+  renew. IPFS = **only as durable as the pin** — if pinning lapses the bytes can go. `cloud`/`fs` = they
+  maintain it. Say which one this drop uses and what it implies.
+- **Gateway ≠ backend, and the sizes differ.** A slow or dead gateway for ipfs/arweave content is **one
+  tx** (`abx set-gateway`), no re-upload, and it works on locked fields. Changing the **backend** is a
+  real migration: re-upload, then re-point. Both are owner-signed.
+- **Owner-wallet hygiene** (offer as follow-ons): the owner wallet controls mint, royalties, URIs and
+  ownership itself — recommend a hardware/dedicated wallet over a hot key, a multisig
+  (`abx set-admin`) for anything valuable, and backing up `.abx-self-host/arweave-key.json` if Arweave
+  credits live there.
 
 ## Setup + environment
 
-`abx` is installed and on your PATH; it needs **Node ≥ 22.5** at runtime (the projection store uses built-in SQLite). Start with `abx doctor` (preflight: signing key/wallet, RPC, canonical factory, storage).
+`abx` needs **Node ≥ 22.5**. Resolve the binary **local first, then global** — `./node_modules/.bin/abx`
+(preferred; invoke as `npx abx …`), else a global `abx`, else install **`@artblocks/abx-cli`** (never
+`@artblocks/abx-sdk`, which ships no binary). **Never probe with a bare `npx abx`** — that name on npm is
+an unrelated squatted package, and `--no-install` does not make it safe. Ask before installing globally;
+keep one invocation for the whole session. In the abx source repo: `pnpm abx <cmd>`.
 
-`.env` (in the creator's project dir) = **secrets only**:
-- **Signing:** a key (`SEPOLIA_FUNDED_PK` / `ABX_DEPLOYER_PK` / `SEPOLIA_WALLET_PK`) is needed ONLY for hot/unattended signing. If the creator owns a wallet, prefer **`--sign`** — no key in `.env`. `doctor`'s missing-key ✗ is **not fatal** on the `--sign` path.
-- `ABX_RPC_URLS`, `ABX_PUBLIC_BASE_URL` (hosted-resolver custody only), optional `OPENSEA_API_KEY`, optional `ABX_RESOLVER_ADMIN_TOKEN` (`deploy-resolver` generates it), plus any backend secret.
+`.env` is **secrets only** — `ABX_DEPLOYER_PK` (hot lane only; prefer `--sign` and no key at all),
+`ABX_RPC_URLS`, `ABX_PUBLIC_BASE_URL`, backend secrets, and the one client credential grammar
+`ABX_REMOTE_<NAME>_URL` + `ABX_REMOTE_<NAME>_TOKEN` (a node you run is the name `self`).
 
-<sub>Working from the abx **source repo** (contributor)? `pnpm install`, then `pnpm abx <cmd>` or `pnpm sandbox`. Every command below is identical.</sub>
+Install matrix, the npx-cache trap in full, every env var, RPC range caps and pruned log history →
+[reference/setup.md](reference/setup.md).
 
-**Indexing reads the event log via `eth_getLogs` from the contract's deploy block** — the CLI records it at deploy and forwards it to a resolver on `add` (discovering it on-chain for a contract it didn't deploy here). So a normal deploy→index scans a small, recent window and is fast on **any** RPC, and re-index is incremental (resumes from the last block). It **auto-chunks**, so a range cap never yields *wrong* state — but don't wave a cap away: a **from-genesis** or long-span reconstruction, or a resolver serving many code projects under load, is slow and rate-limit-prone on a getLogs-**range-capped** endpoint. `abx doctor` rates each endpoint and flags a capped one — treat that as a real infra signal, and give a resolver you'll run under load a range-generous **archive** RPC. **If indexing is slow, or a hosted resolver won't serve, check the scan floor FIRST (is it scanning from block 0?), not the RPC tier** — that mis-diagnosis is a known trap. RPC deep-dive + troubleshooting → [reference/setup.md](reference/setup.md).
+**If indexing is slow, or a hosted resolver won't serve, ASK IT: `abx status <addr> [--remote <name>]`**
+reports the lifecycle (`queued`→`backfilling`→`live`, plus `stale`/`failed` with a machine-readable
+cause), so "still catching up" and "broken" stop looking alike. **Check the scan floor (is it scanning
+from block 0?) before blaming the RPC tier** — that mis-diagnosis is a known trap.
 
 ## Reference files
 
-- **Public docs — the human-facing companion** at **https://abx.docs.artblocks.io** (quickstart, guides, the CLI/SDK reference, the protocol model). This skill is YOUR operating manual and stays authoritative for how to drive the CLI; the docs site is what you **link the creator to** for background/onboarding, and a place you can read if you want the protocol rationale behind a command. Don't send the creator commands to run (you run them) — send them the docs to *read*.
-- **Code projects — operating depth** (what to keep running, the resume loop, verify-it-resolves, render ops, `--onchain-uri`/`--image-base`/traits internals, arweave delay, `deploy-code` flags, mint timing/pause/supply) → **[reference/code-projects.md](reference/code-projects.md)**
-- **Operating an existing project** (owner ops, **artist credit + license fields**, **attaching files / the data plane**, selling via the shared minter, `abx mint-page`, moving hosting, resolver→resolver `migrate`) → **[reference/operating.md](reference/operating.md)**
-- **Hosting infrastructure** (storage backends, Turbo lanes + failure playbook, `deploy-resolver`, `deploy-effects`, local-vs-remote stores, token API routes, Docker) → **[reference/hosting.md](reference/hosting.md)**
-- **Environment detail** (RPC selection + failover, multi-chain, troubleshooting) → **[reference/setup.md](reference/setup.md)**
-- **Troubleshooting — "my NFT looks wrong"** (gray placeholder, stale-on-marketplace, tokenURI reverts, localhost baked, "not registered") — diagnose before acting → **[reference/troubleshooting.md](reference/troubleshooting.md)**
+Load one when the decision tree above sends you there — each is the depth behind a routing line here.
 
-## Guarantees
+| File | Holds |
+|---|---|
+| [decisions.md](reference/decisions.md) | the six launch decisions in depth · the READ ceiling (measured) · `--copies` custody · **locks: what freezes and what doesn't** |
+| [code-projects.md](reference/code-projects.md) | the `abx.js` runtime contract · studio loop · PostParam catalog · seeds · in-chain Solidity lane · render ops · what to keep running |
+| [operating.md](reference/operating.md) | owner ops · credit + license · **attaching files (data plane)** · selling via the shared minter · mint page · App Store · deploy mechanics · migrating hosting |
+| [hosting.md](reference/hosting.md) | storage backends + Turbo playbook · gateways and their floors · managed providers + named remotes · `deploy-resolver`/`deploy-effects` |
+| [setup.md](reference/setup.md) | install + `.env` (start here first time) · RPC selection, failover, range caps |
+| [troubleshooting.md](reference/troubleshooting.md) | "my NFT looks wrong" — placeholders, stale listings, reverting `tokenURI`, baked localhost, not-registered |
+| [creator-token.md](reference/creator-token.md) | ERC-721C royalty enforcement — **only when the creator raises it**; plain ERC-721 is the default |
 
-- **Reconstruction from chain alone** — deterministic, idempotent; delete the projection, replay yields identical state.
-- **Trust = the factory** — a clone is canonical only when the ownerless factory's `isAbxClone` confirms it (the `AbxDeployed` beacon is discovery, and spoofable).
-- **Content is verifiable** — the on-chain keccak256 lets anyone re-hash the served bytes (the `verify` route), zero trust in the node.
-- **Keys stay with their owner** — the wallet lane signs in the user's own wallet; the CLI never sees the key. Runtime data lives in `./.abx-self-host/` (gitignored).
+Human-facing companion: **https://abx.docs.artblocks.io** — send creators there, work from this skill.
+
+## Guarantees
 
-Protocol model + full docs → **https://abx.docs.artblocks.io** ([protocol](https://abx.docs.artblocks.io/protocol/), [using ABX](https://abx.docs.artblocks.io/using-abx/), [CLI/SDK reference](https://abx.docs.artblocks.io/reference/)).
+- **Reconstruction from chain alone** — deterministic and idempotent; delete the projection, replay
+  yields identical state.
+- **Trust = the factory.** A clone is canonical only when the ownerless factory's `isAbxClone` confirms
+  it. The `AbxDeployed` beacon is discovery and spoofable, and **the shared minters' events are discovery
+  too**: both minters price a sale for any contract of the right shape, so a hostile target can make the
+  canonical minter emit `Purchase` with no NFT issued. Authenticate the **token** — `isAbxClone`, its own
+  `minter()`, its `Transfer`/`TransferSingle` — never the minter's log.
+- **Content is verifiable** — the on-chain keccak256 lets anyone re-hash the served bytes; zero trust in
+  the node.
+- **Keys stay with their owner** — the wallet lane signs in the user's own wallet; the CLI never sees the
+  key. Runtime data lives in `./.abx-self-host/`, which the CLI makes self-ignoring (it writes a
+  `.gitignore` inside on first use) because that directory can hold a signing-capable Arweave key.