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

package/skill/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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.
+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+.
 metadata:
-  version: "0.1.0-alpha.31"
+  version: "0.1.0-alpha.32"
 ---
 
 # ABX Self-Host Toolkit (`abx`)
@@ -65,23 +65,47 @@ L3 agentic surface: image → live self-hosted NFT the creator owns — a **1/1*
   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.
+- **⚠ 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
@@ -114,8 +138,9 @@ Route by the **content** first, then apply the gates below. The three paths diff
 > 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
+> `--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.
@@ -214,10 +239,11 @@ command has finished.
 |---|---|---|
 | **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.
 
-**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).
+**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.
 
@@ -482,7 +508,8 @@ Load one when the decision tree above sends you there — each is the depth behi
 
 | File | Holds |
 |---|---|
-| [decisions.md](reference/decisions.md) | the six launch decisions in depth · the READ ceiling (measured) · `--copies` custody · **locks: what freezes and what doesn't** |
+| [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` |

package/skill/reference/capabilities.md

@@ -0,0 +1,301 @@
+# Can ABX do that? — the four seams, and the honest no-list
+
+**Read this before you tell a creator something is impossible.** The most expensive failure on this
+toolkit is not a bad deploy — it is an agent saying "ABX can't do that" about something ABX does. Three
+real sessions in one week:
+
+- a creator asked to put a **77 KB PNG fully on-chain**; the agent called it "not practical" and sent
+  them to a different protocol. It ships today, warns once, and costs ~31M gas to read.
+- a creator wanted **transfer restrictions plus mutable state**; the agent said no. The creator said
+  "isn't that hooks?", the agent agreed and built it that afternoon.
+- an agent wrote a **bespoke, non-canonical token contract** for a mechanic two stock hooks cover —
+  permanently forfeiting the factory provenance that is the whole point of deploying here.
+
+None of those agents lacked information. Each answered from the **command list**, and the command list
+is a set of *recommended routes*, not the edge of what the protocol does. Falling off the end of a
+routing table is not a "no".
+
+## The rule
+
+**Never answer "ABX can't do that" from the absence of a flag.** Before the words *not possible*, *not
+practical*, *you'd need a different* — or the name of another protocol — leave your mouth:
+
+1. **Check the seam table below.** Can a minter or one of the three hooks carry it? Almost always yes.
+2. **Check [the genuine no-list](#the-genuine-no-list) at the bottom.** Is it actually on it? It is a
+   short list, and it is the whole list.
+3. **If it is on neither, it is possible.** Answer with the *cost*, not a refusal.
+
+**The answer shape is always "yes, and here is what it costs" — never a flat no.** A creator who hears
+*"that's not practical"* hears *"ABX can't"* and leaves. A creator who hears *"that's about 31M gas to
+read, so it needs a high-gas RPC and most marketplaces will show nothing — worth it if permanence is the
+point, and `--backend arweave` is the alternative"* can actually decide. The second one is also true.
+
+**Never route a creator to another protocol for something ABX does.** If ABX genuinely cannot do it,
+say so plainly and stop — recommending a competitor's stack is not your call to make on their behalf,
+and it has so far always been wrong on the facts.
+
+## The four seams
+
+A canonical ABX token is a stock factory clone that never changes. Your mechanic lives *beside* it, in
+contracts the collector can also read. That separation is the product: the buyer verifies the token
+against `isAbxClone`, and verifies your rules independently.
+
+| Seam | Wired with | Runs | Can it veto? |
+|---|---|---|---|
+| **Minter** | `abx set-minter <token> --minter 0x…` (Series or edition — a plain 1/1 has no minter) | when your contract calls `mint(to)` — it may do anything first | n/a — it *is* the mint |
+| **Configure hook** | `abx set-param-hooks <token> --configure 0x…` | before a governed param write persists | **yes** — its revert rejects the write |
+| **Transfer hook** | `abx set-param-hooks <token> --transfer 0x…` | after every ownership change, **mint and burn included** | **yes** — its revert fails the transfer |
+| **Augment hook** | `abx set-param-hooks <token> --augment 0x…` | at read time, when `tokenData` is assembled | no — it **adds and overrides** keys |
+
+One contract can be several of these at once. That is the shape nearly every real mechanic takes: a
+controller holding the money and the rules, wired into a clone that stays byte-identical to every other
+ABX project of its type.
+
+**Between them, these seams run arbitrary Solidity at all three moments in a token's life: when someone
+writes to it, when it moves, and when it is read.** That is the honest scope of the claim. If a mechanic
+can be expressed as *"reject this write"*, *"reject this move"*, *"account for what just happened"*, or
+*"compute this at read time"*, it is buildable here without a custom token.
+
+> **⚠ The precondition, and it is deploy-time-irreversible: hooks exist only on `SeriesCode` /
+> `EditionCode` — the `deploy-code` lane.** A `deploy` 1/1 or a `deploy-series` image collection has no
+> configurable params, therefore no hooks, and `set-param-hooks` refuses it. **The contract type is fixed
+> at deploy and cannot be retrofitted**, so a static-art collection deployed with `deploy-series` has
+> permanently foreclosed every mechanic on this page. **If a creator has hinted at *any* rule — "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 when the art is a plain image** (a script that draws the image is fine, and
+> `--image-renderer` covers the Solidity lane). Ask before you deploy; you cannot ask after.
+>
+> **The minter seam is the exception** — `abx set-minter` works on any Series or edition, so an
+> auction, an allowlist or a raffle needs no code project. Only the three hooks do.
+
+There is a **fifth** transfer-time seam that is not a hook and should never be conflated with one:
+the **ERC-721C / ERC-1155C transfer validator**, an opt-in-at-deploy standards-track mechanism for
+royalty enforcement, managed with `abx set-transfer-validator`. Different purpose, different lock,
+different audience → [creator-token.md](creator-token.md).
+
+## The three hooks, in depth
+
+Full calling conventions live in
+[`IAbxParamHooks.sol`](https://github.com/ArtBlocks/abx/blob/main/contracts/src/extensions/configurable-params/IAbxParamHooks.sol);
+working Solidity for each pattern is at
+https://abx.docs.artblocks.io/using-abx/guides/custom-mechanics/. Wire all three with one
+`abx set-param-hooks` call (the contract has no per-hook setter — omit a role to keep it, `none` to
+clear it).
+
+### Configure hook — the write-time validator
+
+```solidity
+function onParamConfigured(
+    uint256 tokenId, bytes32 key, bytes32 value,
+    address updatedBy, uint256 dataLength, address dataBlobAddress
+) external;
+```
+
+Called **before the value persists**, inside a schema-governed `configure-param`. **Reverting vetoes the
+write.**
+
+- **`tokenParam` still returns the OLD value during this call** — which is what makes "may only go up",
+  "may only be set once", and "must differ from the last" expressible at all.
+- **Two shapes, one function.** A scalar write puts the whole value in `value` and zeroes the last two
+  args. A `String`/`Bytes` write cannot — `value` carries only `keccak256(data)`, and the content is at
+  `dataBlobAddress` (a Solady SSTORE2 pointer, already deployed). `dataLength` is the reliable
+  discriminator: **never `0` on the blob path**.
+- Read the incoming blob with `SSTORE2.read(dataBlobAddress)` — never `CALL` the pointer. A hook that
+  only enforces a size ceiling reads `dataLength` and never pays to touch the bytes.
+- **A veto costs the writer the storage they already paid for** (the blob is written before the hook
+  runs, by necessity). An `eth_call` dry run surfaces the rejection for free — that is what a good
+  configuration UI does before asking for a signature.
+- **You cannot write zero bytes.** A zero-length `String`/`Bytes` write is refused by the contract
+  before your hook ever runs, so "unequip everything" cannot be an empty payload — use a sentinel byte
+  or a scalar companion key.
+
+### Transfer hook — the ownership-change veto
+
+```solidity
+function onTokenTransfer(
+    uint256 tokenId, address from, address to, address operator, uint256 amount
+) external;
+```
+
+Called after every ownership change. **`from == address(0)` is a mint; `to == address(0)` is a burn.**
+**Reverting fails the transfer** — the token no longer swallows the revert, because it could not honestly
+promise otherwise (Solady runs the receiver-acceptance check *after* this call, so a hook could starve
+`safeTransferFrom` regardless).
+
+- **It is a veto, not a trigger.** It can refuse a move; it can never *cause* one.
+- **It vetoes mints too** — a mint is a transfer from `0x0`, so a hook that reverts unconditionally
+  freezes issuance as well as trading.
+- **It sees burns**, which is how burn-to-combine, redemption and vaults settle — but only on a
+  collection deployed `--burnable`, which is **deploy-time-only and cannot be retrofitted**.
+- It may persist and derive state through its own authority; the token exposes no special path.
+- `operator` and `amount` are not redundant with `from`: on an ERC-1155 an approved marketplace moves a
+  holder's copies. **On a multi-copy edition, think hard before storing per-id state** — params are per
+  *id* and therefore shared by every holder, so "the current owner" really means "whoever moved most
+  recently". Aggregate or monotonic state (transfer counts, "has ever been held by") is coherent there;
+  a single-owner notion is not.
+- **A buyer's guarantee that you will never arm one is `abx lock-param-hooks`, not your word.** Freezing
+  an empty set is the proof that no transfer veto can ever exist.
+
+### Augment hook — read-time compute, and the most under-used seam we have
+
+```solidity
+function augmentTokenParams(address token, uint256 tokenId)
+    external view returns (AugmentedParam[] memory);   // { bytes32 key; string value; }
+```
+
+A `view`, called when `tokenData` is assembled — by the on-chain `AbxGenerator` and by the off-chain
+resolver. **No storage, no event, no gas on the token.** It may **add** keys and **override** stored ones
+(augment wins per key, last-wins in every mainstream JSON parser).
+
+- **Its return is bounded only by `eth_call` limits — the ~24 KB stored-blob ceiling does not apply to
+  compute.** This is the lane for large *derived* data.
+- It reads whatever a `view` can reach: block data, an oracle, another contract, the token's own params,
+  a holder's balance elsewhere. A piece that genuinely reacts to live chain state is one hook.
+- Values are the **final canonical string** exactly as `tokenData` carries it — a hook injecting binary
+  base64s it itself (free, view context). Raw, not JSON-escaped; escaping is the serializer's job.
+- **The live view reads it per view (always current); the rendered still is a snapshot of settled state
+  only.** So a volatile hook (a timestamp, a price) animates the live view without re-rendering the
+  thumbnail every block. Re-render triggers are settled-state changes.
+- Reserved `tokenData` keys (`seed`, `tokenId`, …) are rejected — a hook cannot forge them.
+- **It does not reach a renderer you wrote.** `render(token, tokenId, field)` takes no `tokenData`.
+  Whoever builds `tokenData` calls the hook, and in your own renderer that is you: read the live state
+  directly, or read `paramHooks()` and call `augmentTokenParams` yourself, wrapped so a broken hook
+  cannot make `render()` revert. Do **not** tell a creator "augment hooks are a resolver concept" —
+  the generator calls one on-chain.
+- Resolver operators have a kill-switch (`ABX_DISABLE_AUGMENT=1`, degrading to settled params);
+  `abx verify` prints the project's live-data posture.
+
+## Mechanic → seam (the inverse lookup)
+
+Every one of these has been built here, or is one small contract away. When a creator describes a
+mechanic, find the row before you find an objection.
+
+| The creator wants | Seam | Shape |
+|---|---|---|
+| Can't be resold for N days · vesting · lockup | transfer hook | `require(block.timestamp >= unlockAt)` |
+| Soulbound — mint once, never moves | transfer hook | `require(from == address(0))` |
+| Burn to redeem · burn to combine · breeding | `--burnable` + transfer hook | settle on `to == address(0)` |
+| Escrow / vault — ETH locked behind the token | minter **+** transfer hook | take payment on mint, pay out on burn |
+| A value that may only go up (level, growth, high-water) | configure hook | compare against the still-old `tokenParam` |
+| Structured collector input that must be well-formed (equip, layout, inventory) | configure hook | `SSTORE2.read(dataBlobAddress)`, decode, validate |
+| Only holders of *some other* token may configure this | configure hook, or `Address(…)` auth in the schema | check the other contract in the hook |
+| Auction · Dutch auction · allowlist · raffle · free claim | **custom minter** | your contract, `abx set-minter` |
+| Priced in an ERC-20, or in anything but ETH | **custom minter** | take payment however you like, then `mint(to)` |
+| Art that reacts to live chain state (block, price, an oracle) | augment hook | read it in a `view`, return it as `tokenData` |
+| Timed reveal | augment hook | branch on `block.timestamp` |
+| Derived traits too large to store on-chain | augment hook | compute at read time — no blob ceiling |
+| Provenance / transfer count / "has ever been held by" | transfer hook | the hook writes its own storage |
+| A raster of any size fully on-chain | `--onchain-image` | nothing is refused — [below](#on-chain-size-nothing-is-refused-and-the-question-is-who-can-read-it) |
+| Royalty enforcement at the marketplace layer | ERC-721C validator (opt in **at deploy**) | [creator-token.md](creator-token.md) |
+
+**The controller chicken-and-egg has a solution — use it.** The controller needs the token's address at
+construction and the token's schema needs the controller's address. Do not run the five-step dance:
+`abx predict` computes the deterministic address first, so the controller is built against a constant and
+the schema rides the deploy. Recipe, including the salt guard-prefix trap (leading 20 bytes must equal
+your deploying wallet, or the address is permissionless and anyone may take it):
+https://abx.docs.artblocks.io/using-abx/guides/custom-mechanics/#break-the-controller-cycle-with-abx-predict
+
+**`abx scaffold-renderer` is the fastest start even when you are building a hook, not a renderer** — it
+writes a Foundry project with the interfaces vendored and tests wired. And test against a *real* deployed
+clone (`forge test --fork-url`), never a hand-rolled mock: a mock invents its way around the real edge
+cases, starting with the zero-length refusal above.
+
+## On-chain size: nothing is refused, and the question is who can READ it
+
+The routing tables elsewhere in this skill recommend **≲40 KB/token** for on-chain content. That is
+**advice about what is cheap, not a limit** — and reading it as a limit is what produced the 77 KB
+refusal. There is no size the toolkit refuses.
+
+**Two axes, and only one is about size at all.** The **write** is chunked into 22,000-byte SSTORE2
+transactions, so no block gas limit binds it at any size — purely money, ~200 gas/byte, paid once. The
+**read** is a single `eth_call`, and whether it succeeds is a property of *whose endpoint is asking*.
+
+Measured 2026-08-24, which is why the old 100 KB refusal was wrong:
+
+| Endpoint | `eth_call` cap | Content it serves |
+|---|---|---|
+| **`sepolia.base.org`** — the default endpoint of our default chain | **600M** | **~729 KB** |
+| `base-sepolia.publicnode.com` · `base-sepolia.drpc.org` | 50M | ~117 KB |
+| `ethereum-sepolia.publicnode.com` | 50M | ~117 KB |
+
+50M is the **floor**, not the ceiling. The refusal sat at 100 KB — below every endpoint above — so it
+blocked content all of them could read. The CLI now measures the RPC you are actually on (a
+state-override call that sends nothing) and reports it:
+
+| Content per token | What the CLI does |
+|---|---|
+| ≲ **117 KB** (~50M gas) | a plain note with write and read figures — renders anywhere |
+| **above that** | ⚠ names your RPC's measured cap and warns that a 50M-capped provider shows a **revert** |
+| **past your own RPC's cap** | ⚠ says plainly that nothing you can point at renders it |
+
+For that **77 KB PNG**: **~16M gas to write** (four chunks) and **~31M to read** — under the floor, so
+it renders everywhere. Say the numbers; it is not a warn case at all.
+
+**Two things have to survive into the conversation.**
+
+**(1) We can measure YOUR RPC. We cannot know a marketplace's or an indexer's** — and theirs decide
+whether the token displays. A measured cap proves *you* can read it, never that OpenSea can, and it is
+point-in-time besides (pooled endpoints rotate: Sepolia's publicnode measured 50M one hour and 2,000M
+the next). Say the measurement as a measurement.
+
+**(2) Reach is fixable after the fact; the bytes are permanent either way.** The read cost decides
+whether a token resolves *in one `eth_call`*, not whether the content is reachable. A resolver
+(`abx deploy-resolver`, or a hosted one) reads on-chain content with **its own** RPC — `inline`,
+`inline-gzip`, `reader`, `reader-gzip` all resolve through it — 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 exactly where it is.
+
+So keep **storage** and **serving** separate, because they are: on-chain is the strongest storage
+answer available at *any* size, and self-resolving-vs-resolver is a serving decision the creator can
+change later. A token whose read is too big for some endpoint is not a lost token — it is one that
+wants a reader in front of it. `--backend arweave` is the other side of the *storage* trade, not a
+correction of their ask.
+
+**Never quote a BLOCK gas limit as the read ceiling.** Three limits share the name and differ by orders
+of magnitude on one endpoint (measured 2026-08-24, Base Sepolia): **`eth_call` 600M** bounds the read
+that decides display · **`eth_estimateGas` 16,777,216** bounds what can be *sent* (identical on every
+endpoint tried — it is why writes batch at 8M, not the block limit) · **block `gasLimit` 1,200M**
+bounds a contract reading inside a transaction, so a contract there reads ~1,100 KB. Off-chain reads
+are not bounded by block limits, and are routinely far above them.
+
+Two things not to garble: `--compress fastlz` cuts the **write** cost, never the read (the renderer
+rebuilds the full uncompressed bytes every call). And the gate is **per token** — a 300-piece collection
+of 5 KB works reads perfectly well.
+
+Measured gas table and the per-KB curve →
+[decisions.md → The READ cost](decisions.md#the-read-cost--who-can-see-it-and-why-nothing-is-refused).
+
+## The genuine no-list
+
+This is the whole list. If the ask is not here and not blocked by a deploy-time choice already made,
+stop looking for a reason to say no.
+
+**Actually not possible today:**
+
+- **Mainnet.** Testnet only — Base Sepolia by default, Sepolia via `ABX_CHAIN`. Never imply otherwise.
+- **Secondary listings.** Reselling a held token means an external marketplace or a manual
+  `abx transfer`. There is no listing feature and no order book.
+- **`abx` compiling or deploying Solidity for you.** You write hooks, minters and renderers with Foundry
+  and deploy them yourself; `abx scaffold-renderer` writes the project, it does not build or ship it.
+- **Replacing a code project's script through the CLI post-deploy.** There is no `abx set-script`.
+- **Retrofitting a deploy-time choice.** These are permanent from the moment the deploy lands:
+  the **contract type** (hooks require `deploy-code`), **`--burnable`**, **`--copies`** (721 vs 1155),
+  and **ERC-721C enrollment**. Ask about all four *before* the deploy — this is the single most common
+  way a creator ends up genuinely unable to have what they wanted.
+- **Unsupported chains.** Say plainly it is not in the toolkit; do not fabricate a recipe.
+
+**Not a flag — but absolutely possible on a seam.** These belong in the paragraph above only if you also
+say how they are built. Listing them as things "abx doesn't do" is what caused this file to exist:
+
+- auctions, Dutch auctions, allowlists, raffles, free claims, ERC-20 pricing → **a custom minter**
+- transfer restrictions, soulbinding, vesting, redemption, escrow → **the transfer hook**
+- validated or governed collector input → **the configure hook**
+- live, derived, oracle-fed or oversized metadata → **the augment hook**
+- a large raster fully on-chain → **`--onchain-image`**, at any size
+
+**And one thing that is possible but is almost never the right answer: writing your own token contract.**
+It is a legitimate creator choice, but it permanently forfeits `isAbxClone` — the only signal
+marketplaces and the App Store allowlist against — and canonicity cannot be added afterwards. Never make
+that trade *for* a creator silently. 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 for an answer.

package/skill/reference/code-projects.md

@@ -234,7 +234,7 @@ Fork `contracts/src/renderers/examples/{SeedSvgRenderer,SeedTraitsRenderer}.sol`
 
 ## Traits on-chain vs off-chain — is your script's trait logic reproducible in Solidity?
 
-A script's `abx.traits({…})` runs in JS during the render. Whether those traits can appear in a **fully-on-chain** `tokenURI` depends on whether the trait *function* is reproducible in Solidity — `abx inspect` rates this; full analysis (with the p5 LCG port recipe) in [`docs/research/onchain-traits-feasibility.md`](../../../docs/research/onchain-traits-feasibility.md). Give a **graded** answer, never a flat "not feasible":
+A script's `abx.traits({…})` runs in JS during the render. Whether those traits can appear in a **fully-on-chain** `tokenURI` depends on whether the trait *function* is reproducible in Solidity — `abx inspect` rates this; full analysis (with the p5 LCG port recipe) in [`docs/research/onchain-traits-feasibility.md`](https://github.com/ArtBlocks/abx/blob/main/docs/research/onchain-traits-feasibility.md). Give a **graded** answer, never a flat "not feasible":
 
 **First, the load-bearing distinction: *portable* ≠ *deployed*.** `inspect` saying traits "port EXACTLY" means the *logic* can be reproduced in Solidity — it does **not** mean a renderer exists. On-chain traits require the creator to **author + deploy** a Solidity attributes-renderer (fork `SeedTraitsRenderer.sol`) and pass its address to `--attributes-renderer` — a real build step, not a flag with a default. `deploy-code --dry-run` prints the traits disposition (`on-chain` / `off-chain via resolver` / `⚠ OMITTED`) and a real deploy **refuses an `--attributes-renderer` address with no code**. So never present "traits on-chain" as settled off a guessed address: confirm a renderer is deployed, or the honest options are off-chain-via-resolver or omitted.