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

package/skill/SKILL.md

@@ -1,508 +1,173 @@
 ---
-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, 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+.
+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, locks, and capability questions. Use for requests to create, deploy, mint, host, serve, verify, repair, migrate, 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.31"
+  version: "0.1.0-alpha.33"
 ---
 
-# 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.
-- **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`/`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` (**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.
-
-**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 |
-
-On-chain's edge past small is self-resolution/permanence, **never cost** — don't call it "cheaper" above the threshold.
-
-**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).
-
-**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 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 |
 |---|---|
-| [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 |
-
-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)
+- Managed 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.