@artblocks/abx-cli 0.1.0-alpha.32 → 0.1.0-alpha.34

package/skill/SKILL.md

@@ -1,535 +1,183 @@
 ---
-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 projects, collector-configurable on-chain parameters (PostParams — typed, auth-gated, settable by creator/token-owner/address), primary sales via the shared fixed-price minter, custom mechanics without a custom token (your own minter contract for auctions/allowlists/raffles/ERC-20 pricing, plus the three param hooks that run arbitrary Solidity at write time, transfer time and read time — soulbinding, vesting, escrow, burn-to-redeem, monotonic ratchets, validated collector input, oracle-fed and derived metadata), fully on-chain content at any size (no refusal — the CLI measures your RPC and reports who can read it), 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, build a custom mechanic (transfer restrictions, soulbound tokens, auctions, allowlists, escrow, redemption, tokens that react to on-chain state) without writing a token contract, put large images fully on-chain, or ASK WHETHER ABX CAN DO SOMETHING AT ALL, 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+.
+name: abx
+description: >-
+  Use the ABX CLI (`abx`) to plan, launch, host, inspect, and operate ABX NFT projects on supported
+  testnets: static 1/1s, image series, editions, JavaScript/code drops, and Solidity-rendered projects.
+  Covers on-chain and off-chain content, managed or self-hosted resolvers, storage, minting and sales,
+  PostParams, hooks, custom minters, migrations, feedback, locks, and capability questions. Use for
+  requests to create, deploy, mint, host, serve, verify, repair, migrate, report ABX feedback, or
+  change an ABX collection, or to determine whether ABX supports a mechanic.
+compatibility: Drives @artblocks/abx-cli on Node 22.13+. Co-versioned with the CLI; install or refresh with `abx skill install`.
 metadata:
-  version: "0.1.0-alpha.32"
+  version: "0.1.0-alpha.34"
 ---
 
-# 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. 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.
-- **⚠ NEVER say "ABX can't do that" from the absence of a flag — check
-  [capabilities.md](reference/capabilities.md) first.** This is the most expensive mistake made on this
-  toolkit, and it is made every week: a 77 KB raster called "not practical" (it ships, with one warning),
-  a transfer-and-mutability mechanic declared impossible (it is two hooks), a bespoke non-canonical token
-  written for something stock hooks cover. Falling off the end of a routing table here is **not** a "no" —
-  the tables are recommended routes, not the edge of the protocol. So before the words *not possible*,
-  *not practical*, *you'd need a different* — or the name of another protocol — leave your mouth: check the
-  four seams, then check the genuine no-list. **If it is on neither, it is possible: answer with the COST,
-  never a refusal** ("~31M gas to read, so it needs a high-gas RPC" — not "that's impractical"). And
-  **never route a creator to another protocol for something ABX does.**
-- **What this toolkit genuinely does NOT do** — the whole list; anything else has a seam:
-  no mainnet (testnet only) · no secondary listings · no post-deploy script replace · `abx` never compiles
-  or deploys Solidity (`scaffold-renderer` writes a project, you build it) · and **no retrofitting a
-  deploy-time choice** — contract type (hooks need `deploy-code`), `--burnable`, `--copies`, ERC-721C
-  enrolment are permanent from the deploy. Ask about those four **before** you deploy; that is the one way
-  a creator ends up truly unable to have what they wanted. **Auctions, allowlists, raffles, ERC-20 pricing,
-  soulbinding, vesting, escrow, redemption, oracle-fed metadata and a large raster on-chain are NOT on this
-  list** — they are seams, below.
-- **The four seams — ABX runs YOUR arbitrary Solidity at all three moments in a token's life.** This is
-  the protocol's real power and the thing agents most consistently miss. A token can point at **your own
-  minter** (`abx set-minter` — it may do anything before it calls `mint`), and a code project can arm
-  **three param hooks** (`abx set-param-hooks`, all optional, one contract can be several):
-  **`--configure`** runs *before a param write persists* and its **revert vetoes the write** (the stored
-  value is still readable, so "may only go up" / "set once" are expressible); **`--transfer`** runs *after
-  every ownership change — mint (`from == 0x0`) and burn (`to == 0x0`) included* and its **revert fails
-  the transfer**; **`--augment`** runs *at read time* as a `view` when `tokenData` is assembled, **adding
-  and overriding keys** with anything a `view` can reach — block data, an oracle, another contract — for
-  **no gas on the token and no ~24 KB blob ceiling** (it is bounded only by `eth_call`). Write-time,
-  transfer-time, read-time. Escrow/vault, soulbind, a monotonic ratchet, equip-and-validate,
-  burn-to-combine, timed reveal, live-reactive art are each *a controller plus one or two hooks*, and the
-  token stays a factory clone the buyer verifies. **Mechanic → seam lookup, the hooks in depth, and the
-  `abx predict` recipe that breaks the controller/schema chicken-and-egg:**
-  [capabilities.md](reference/capabilities.md). Two caveats: a **transfer hook is a VETO, not a trigger**
-  (it can refuse a move, never cause one — and a reverting hook stops **mints** too), and none of this is
-  scaffolded, so it is real Foundry engineering.
-- **⚠ Hooks exist ONLY on `deploy-code` projects (`SeriesCode`/`EditionCode`), and the contract type is
-  fixed at deploy forever.** A `deploy` 1/1 or a `deploy-series` image collection has no params, so no
-  hooks, and `set-param-hooks` refuses it. **If the creator has hinted at any rule at all** — "holders can
-  rename it", "it can't be resold for a month", "it levels up", "it reacts to the chain" — **deploy it
-  with `deploy-code` even if the art is a plain image** (a script that draws the image is fine; the
-  Solidity lane is `--image-renderer`). You can ask before the deploy. You cannot ask after.
-- **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`/`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?
-
-Route by the **content** first, then apply the gates below. The three paths differ most in what you have to *keep running* and where the thumbnail comes from:
-
-| You have | Command | `tokenURI` resolves | Thumbnail (marketplace still) |
-|---|---|---|---|
-| **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 |
-
-**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` (**any format, any size — nothing is refused. ≲117 KB reads on every
-> endpoint; above that the CLI measures your RPC and names who else can. A READ-reach question, not a
-> write limit; 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.
-
-**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 | 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 |
-
-Just want to see it work? `abx demo`, skip the rest.
-
-## Gate 2 — who signs? (three lanes)
-
-Every write builds an unsigned tx; pick the lane by stakes:
-
-| Lane | Flag | Signs | Use when |
-|---|---|---|---|
-| **Hot** | default (or `--send`) | env key, in-process | autonomous agent · testnet · low value |
-| **Wallet** | `--sign` | human's own wallet (MetaMask/Ledger) | real value · key shouldn't touch `.env` |
-| **Cold** | `--unsigned` | multisig / offline signer | a Safe / advanced setup |
-
-- **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:
-
-| Content size | Default | Why |
-|---|---|---|
-| **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 |
-| **Bigger, but they want it on-chain anyway** | still **on-chain** (`--onchain-image`) — this row is a *default*, not a limit | **no size is refused**; ≲117 KB renders anywhere, above that the CLI measures your RPC and says who else can read it — quote the gas and let them choose |
-
-On-chain's edge past small is self-resolution/permanence, **never cost** — don't call it "cheaper" above the threshold.
-
-**Nothing is refused at any size — the question is who can READ it.** The **write** is chunked into 22,000-byte SSTORE2 transactions, so no block limit binds it at any size (~200 gas/byte, money only). The **read** is one `eth_call` at **~360–405k gas per KB** (quote the range, never a flat rate), and whether it succeeds belongs to whoever's endpoint is asking. **≲117 KB (~50M gas) reads on every endpoint measured** — that is the floor: geth's default and what publicnode/drpc serve. Above it the CLI **probes your actual RPC** and reports its real cap. Measured 2026-08-24: `sepolia.base.org`, the default endpoint of our default chain, allows **600M (~729 KB)**. **A 77 KB PNG renders everywhere: ~16M gas to write, ~31M to read.** A 312 KB one ships too — it warns that a 50M-capped provider will show a revert. **We can measure YOUR RPC; we cannot know a marketplace's or an indexer's** — and theirs decide whether the token displays, so never present a measured cap as settling that (it is point-in-time too: pooled endpoints rotate). **Reach is fixable after the fact, and the bytes are permanent either way:** a resolver (`abx deploy-resolver`, or a hosted one) reads on-chain content with **its own** RPC and serves plain HTTP, so a marketplace fetches a URL and never makes the big call — `abx set-renderer <addr> --off` repoints `tokenURI` at it with every byte left where it is. **Storage and serving are separate choices:** on-chain is the strongest storage answer at any size; self-resolving vs a resolver is a serving decision you can change later. `--backend arweave` is the other side of the *storage* trade. **Never quote a BLOCK gas limit as the read ceiling** — three limits share that name and differ by orders of magnitude on one endpoint (measured Base Sepolia: `eth_call` 600M · `eth_estimateGas` 16.7M · block 1,200M); the block limit bounds a *contract* reading inside a tx (~1,100 KB there), not an off-chain read. `--compress fastlz` is cheaper to *write*, not to *read*. Per token, so a 300-piece collection of 5 KB SVGs is fine. Measured table → [decisions.md → The READ cost](reference/decisions.md#the-read-cost--who-can-see-it-and-why-nothing-is-refused).
-
-**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…]
-   ```
-   = staging tx(s) + one deploy-that-mints. **Mint at deploy — no `--no-mint`** (nothing to warm).
-3. **Prove + finish:** `abx tokenuri <addr>` (reads metadata straight from chain) · `abx refresh <addr>` (nudge marketplaces) · lock later once it resolves: `abx lock-field <addr> --field image` then `abx lock-uri <addr>`.
-
-For large/dynamic media, off-chain custody, or operating an existing project, use the framework + reference files below.
-
-## Series (multi-token drops)
-
-One contract, **N tokens**, static creator metadata — a folder of media → a collection. **Everything from the 1/1 applies per token** (custody, on-chain vs off-chain, signing lanes, identity, locking, warming); only the three points below are new. Reach for it when there's more than one piece; a single image is `abx deploy`.
-
-```bash
-abx deploy-series --dir <media-dir> --name "…" --symbol … [--onchain-uri --backend arweave|ipfs|cloud | --onchain-image --compress fastlz | --onchain-uri | --public-base-url https://…] [--mint-all | --mint-count N | --no-mint]
-```
-**Quick start — a folder of photos, permanent, no server:**
-```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. **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`): 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 + 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 | — |
+# ABX
+
+Use `abx` as the execution and truth surface. Help, capability output, dry runs, on-chain reads, and
+typed errors outrank remembered prose.
+
+## Non-negotiable rules
+
+- Never read or print `.env`, private keys, RPC URLs, provider tokens, storage credentials, wallet
+  session URLs, or Arweave JWK contents. Use `abx doctor`, `abx remote`, and `abx storage show` to
+  inspect configuration safely.
+- Use `pnpm abx …` inside the ABX source repository. Use `abx …` in a creator project or installed
+  environment. Run `abx version` if provenance is uncertain.
+- Operate only on chains reported by `abx capabilities`; the toolkit is testnet-only today. Select
+  the chain with `ABX_CHAIN=<chain>`; there is deliberately no `--chain` flag.
+- Run `abx help <command>` immediately before composing a non-trivial command. Do not recover flag
+  syntax from this skill.
+- Never infer that a capability is absent because a flag is absent. Run `abx capabilities --json`,
+  identify a native lane or extension seam, and read [capabilities.md](reference/capabilities.md).
+- Never hand-roll transactions, nonces, retry loops, resolver URLs, or contract-type detection when
+  the CLI exposes the operation. One EOA must have one serialized write sequence.
+- Never send, mint, transfer, lower a cap, change authority, or apply a lock until the human confirms
+  the exact action. Locks, ownership transfers, and several deploy choices are irreversible.
+- Never submit feedback, project data, logs, or agent/session context to ABX or a remote provider
+  until the human reviews the preview and approves that specific report. Redact credentials and
+  unrelated personal or project information. `abx feedback` previews by default; `--yes` sends.
+- Never fold `abx submit-app` into deployment. Listing is a separate, optional post-deploy action.
+
+## Use the lifecycle
+
+Follow this state machine instead of accumulating retries:
+
+1. **Discover** — identify the working directory, CLI provenance/version, active chain, artifacts,
+   existing contract addresses, configured remote, and signer preference. Run `abx doctor` for a
+   deployment or unfamiliar environment.
+2. **Classify surfaces** — decide collection shape, runtime, required public surfaces, custody,
+   resolution, authority, mutability, and mint/sale timing. Use the model below.
+3. **Inspect** — run `abx capabilities --json`; for code run `abx inspect` and `abx preview`. For an
+   existing collection run `abx state`, `abx tokens`, `abx tokenuri`, and `abx verify` as relevant.
+4. **Plan** — use the selected deploy command with `--dry-run --json`. Read its normalized shape,
+   addresses, surface warnings, transaction count, storage activity, and irreversible choices back
+   to the creator. A dry run may perform read-only network probes; it must not send or store.
+5. **Confirm** — confirm name, symbol, token standard, code-capable/static type, burnability,
+   ERC-721C/ERC-1155C enrollment, edition arithmetic, royalty ceiling, signer, costs, public URLs,
+   initial mint, and every requested lock.
+6. **Execute** — let the CLI sign and serialize the operation. Do not start a second write process
+   with the same EOA. Honor structured lifecycle states and terminal errors.
+7. **Verify** — verify the contract and each promised surface from its canonical path. Use on-chain
+   reads for self-resolving metadata and `abx verify`/remote status for hosted surfaces. Mint token 0
+   before expecting token-specific renders.
+8. **Operate** — configure sales, publish renders, migrate, refresh marketplaces, transfer authority,
+   or lock only after verification. Record the contract address, chain, deploy block, custody,
+   resolution, owner powers, and remaining mutable surfaces.
+
+When diagnosing, identify the current state and choose one next transition. Read
+[diagnose.md](reference/diagnose.md); do not build a ladder of speculative retries.
+
+## Model the project by independent dimensions
+
+Keep these concepts separate. Most bad ABX plans collapse two of them into “hosting.”
+
+| Dimension | Decide |
+|---|---|
+| **Collection shape** | one work; N unique works; one or N ids with limited/open copies |
+| **Runtime** | static media; JavaScript program; build directory; Solidity field renderer |
+| **Public surfaces** | metadata, image, animation, traits, attachments, PostParams |
+| **Custody** | on-chain bytes, Arweave, IPFS, cloud, or local development storage |
+| **Resolution** | on-chain renderer, hosted resolver, or on-chain JSON pointing at external media |
+| **Rendering** | no derived render, one-shot stills, continuous effects, or Solidity-computed fields |
+| **Authority** | owner, token holder, delegated address, minter, hook, transfer validator |
+| **Mutability** | editable values/pointers, governed values, and the locks applied after verification |
 
-**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).)
+Use precise language:
 
-**Pick your code lane** (all `abx deploy-code`):
+- **On-chain bytes** describes custody. **Self-resolving** describes resolution.
+- **Chain-complete** means the requested document has no off-chain dependency. It does not promise
+  immutability or that every third-party RPC can execute a large read.
+- **Locked** names a particular stored value or pointer. It does not prove that code behind a proxy
+  is immutable or that every output input is frozen.
+- Marketplace refresh re-fetches a projection; it does not mutate canonical state.
 
-| Your sketch | Flags | Result |
-|---|---|---|
-| Vanilla JS, no libraries | `--script f.js --onchain-uri` | **fully on-chain** — resolves from any RPC forever |
-| 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**; 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)
-
-**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. **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`.
-
-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).
-
-**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".
-
-**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:
-
-- **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
-
-`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):
-
-  Name          Donuts & Cake            ⚠ inferred from filename — confirm or rename
-  Symbol        DONUTS                   ⚠ inferred — confirm
-  Description   "<the creator's words>"  ⚠ I have nothing from you — give me a line, or I deploy with none
-  Traits        none                     ⚠ none written — add --traits "Key=Value" or skip
-  Image         donuts-cake.svg · 2.4 KB → reader (fastlz, 1 chunk) · on-chain
-  Resolution    on-chain via renderer 0x5F36…1829 — no server, no localhost
-  Royalty       5% (500 bps) → 0x0248…b13C   (default; confirm rate + receiver)
-  Owner         0x0248…b13C  (the deploying wallet)
-  Mint          token #0 → owner, at deploy
-  Address       0x2619…9Da9  (salt-pinned: --salt 0x…)
-  Locking       deploying UNLOCKED — lock later, after verifying it resolves
-  Transactions  stage image (1) + deploy + mint (1) = 2
-
-  Reply to change anything, or say go.
-```
-
-Rules:
-- **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 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 |
+## Choose the native deployment family
+
+Run `abx capabilities --json` for the current matrix, then load [deploy.md](reference/deploy.md).
+
+| Intent | Command | Default contract shape |
 |---|---|---|
-| **Express** *(default)* | demo, or pre-mint to your own wallet | `deploy` (mints #0) → `serve` → `refresh` |
-| **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, 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.
-
-`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).
-
-## List in the ABX App Store (optional)
-
-**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).
-
-## 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)
-
-Cover these in plain language once it's live; don't wait to be asked.
-
-- **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` 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` 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`).
-
-Install matrix, the npx-cache trap in full, every env var, RPC range caps and pruned log history →
-[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
-
-Load one when the decision tree above sends you there — each is the depth behind a routing line here.
-
-| File | Holds |
+| One static work | `abx deploy` | ERC-721 1/1 |
+| Folder of distinct static works | `abx deploy-series` | ERC-721 Series |
+| Program or state-derived work | `abx deploy-code` | ERC-721 SeriesCode |
+| Copies of any family | add `--copies <n|open>` | corresponding ERC-1155 edition |
+
+Important boundaries:
+
+- `deploy-code --copies` supports `--script`, dependencies, and Solidity image/attributes renderers.
+  It does not currently support `--code-dir`, `--image-base`, or `--resume`.
+- `--onchain-image` works for static 721s and editions in hot or wallet-signing lanes. It cannot be
+  prepared as one cold `--unsigned` bundle because staged transactions depend on prior receipts.
+- A code project may need no public host when its image/traits are computed by Solidity renderers.
+  A JavaScript program still needs a deliberate marketplace-image plan even when its animation is
+  chain-complete.
+- Content size is not a fixed refusal. The CLI measures write cost and the active RPC's read reach.
+  State the measured reach; never generalize it to every marketplace endpoint.
+
+## Treat public surfaces as an acceptance test
+
+Before deploying, write down the promised value for each applicable row:
+
+| Surface | Verify with |
 |---|---|
-| [capabilities.md](reference/capabilities.md) | **"can ABX do X?" — the four seams (minter + the three hooks), mechanic→seam lookup, and the genuine no-list.** Read it before you ever tell a creator something is impossible |
-| [decisions.md](reference/decisions.md) | the six launch decisions in depth · the READ cost + measured RPC caps · `--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 |
-
-Human-facing companion: **https://abx.docs.artblocks.io** — send creators there, work from this skill.
-
-## Guarantees
-
-- **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.
+| Contract identity and owner powers | `abx state <addr>` and the deploy readout |
+| Token metadata | `abx tokenuri <addr> --token <id>` |
+| Collection metadata | `abx contracturi <addr>` |
+| Image | decoded metadata plus a successful fetch or on-chain field provenance |
+| Animation/live view | the decoded `animation_url`, loaded with a real minted token |
+| Marketplace traits | decoded `attributes`, not merely console output from the program |
+| Parameters and values | `abx state` for schemas; `abx tokens --json` for token values |
+| Attached artifacts | resolver metadata and `/data/<key>`; attachments are not enumerable in bare on-chain metadata |
+| Byte integrity | `abx verify <addr>` |
+| Hosted lifecycle | `abx status --remote <name> --watch` or provider status |
+
+Do not call a launch complete because the transaction mined. Complete it when every promised surface
+has the expected provenance and is retrievable through the path collectors will use.
+
+## Confirm irreversible and shared-state choices
+
+Before any real deploy, say these choices explicitly when relevant:
+
+- The contract family and ERC-721 versus ERC-1155 edition shape cannot be changed later.
+- Hooks and PostParams require a code-capable contract. A static image contract cannot gain them.
+- `--burnable` and creator-token enrollment are deploy-time choices.
+- A royalty cap only moves downward.
+- Edition arithmetic is **number of ids × copies per id**. For one work with 100 copies, use one id;
+  do not accidentally create the code default's multiple-id space.
+- An ERC-721 Series cap is lifetime minted ids: burning never reopens a slot. An ERC-1155 edition's
+  per-id cap is live supply: when burnable, a burned copy may be minted again.
+- PostParams on an edition are stored per id, not per physical copy. A holder-authorized value is
+  shared by all holders of that id, and the last valid writer wins.
+- Metadata, URI, script, dependency, hook, schema/value, and authority locks are distinct. Verify
+  first and lock last.
+
+## Use capability classification, not optimism or refusal
+
+Classify an unusual request as exactly one of:
+
+1. **Native** — a documented CLI lane performs it.
+2. **Extension** — a custom minter, configure/transfer/augment hook, field renderer, or seed source
+   performs it while the token remains a canonical factory clone.
+3. **Unsupported or foreclosed** — the capability contract lists it, or the existing collection's
+   irreversible type/flags already exclude it.
+4. **Unknown** — no route has been proven. Inspect code/help/contracts and report uncertainty; do not
+   turn absence from a no-list into a promise.
+
+Custom Solidity is built and deployed outside `abx`; `abx scaffold-renderer` supplies a Foundry
+starting point. Read [capabilities.md](reference/capabilities.md) before designing a custom mechanic.
+
+## Load only the reference needed
+
+- Environment, installation, signer lanes, and safe setup → [setup.md](reference/setup.md)
+- Static projects, editions, placement, costs, and deploy confirmation → [deploy.md](reference/deploy.md)
+- Programs, renderers, thumbnails, traits, PostParams, seeds, and dependencies → [code.md](reference/code.md)
+- First-party hosted services, API-key signup, and core/provider feedback → [services.md](reference/services.md)
+- Generic remotes, self-hosted resolvers/effects, storage, lifecycle, and migration → [hosting.md](reference/hosting.md)
+- Existing-project reads, mint/sales, fields, transfers, authority, and locks → [operate.md](reference/operate.md)
+- Failure classification, resume, RPC/storage/rendering faults, and retry discipline → [diagnose.md](reference/diagnose.md)
+- Capability questions, extension seams, mechanics, and hard boundaries → [capabilities.md](reference/capabilities.md)
+- ERC-721C/ERC-1155C enrollment and validator operations → [creator-token.md](reference/creator-token.md)
+
+Read every reference applicable to the requested workflow before sending a real transaction. Do not
+load unrelated references merely because they exist.