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

package/skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ABX"
+  short_description: "Launch, host, and operate ABX NFT projects"
+  default_prompt: "Use $abx to plan and safely execute this ABX project workflow."

package/skill/reference/capabilities.md

@@ -1,301 +1,187 @@
-# Can ABX do that? — the four seams, and the honest no-list
+# Capability questions and extension seams
 
-**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:
+Use this reference before answering whether ABX can support an unusual mechanic. The goal is neither
+automatic optimism nor reflexive refusal; it is a proven route with explicit cost and limits.
 
-- 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.
+## Contents
 
-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".
+- [Use the four-way classification](#use-the-four-way-classification)
+- [Inspect the machine-readable contract](#inspect-the-machine-readable-contract)
+- [Use canonical extension seams](#use-canonical-extension-seams)
+- [Map mechanics to seams](#map-mechanics-to-seams)
+- [Respect deploy-time prerequisites](#respect-deploy-time-prerequisites)
+- [Know the supported boundary](#know-the-supported-boundary)
 
-## The rule
+## Use the four-way classification
 
-**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:
+Classify the request as one of:
 
-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.
+1. **Native** — a current CLI command/flag combination performs it directly.
+2. **Extension** — a custom minter, hook, field renderer, seed source, or transfer validator performs
+   it while the token remains a canonical factory clone.
+3. **Unsupported/foreclosed** — the capability contract lists it as unsupported, or the existing
+   contract's immutable type/options exclude the prerequisite.
+4. **Unknown** — no supported route has been demonstrated. Inspect help, implementation/contracts,
+   and state; report uncertainty if it remains unproven.
 
-**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 infer “unsupported” from the absence of a flag. Never infer “possible” merely because an item is
+absent from a short no-list. A capability claim needs a native lane or an exact extension seam.
 
-**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.
+Give the creator the route, engineering required, authority model, gas/hosting/reach tradeoff,
+irreversible prerequisites, and verification plan. “Possible” without those qualifiers is not useful.
 
-## The four seams
+## Inspect the machine-readable contract
 
-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.
+Run:
 
-| 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;
+```bash
+abx capabilities --json
+abx help <relevant-command>
 ```
 
-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;
-```
+The capability contract reports native deployment lanes, EditionCode/static edition differences,
+extension seams, deploy-time choices, and currently unsupported product boundaries. For an existing
+collection, also run `abx state`; capability depends on the contract already deployed, not only on
+what the newest CLI could deploy today.
 
-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; }
-```
+Use a deploy command's `--dry-run --json` for a concrete plan. It is the source of truth for the
+active chain, artifacts, signer, storage, addresses, transaction count, and measured warnings.
 
-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 |
+## Use canonical extension seams
+
+A custom mechanic normally lives beside a canonical token rather than replacing it.
+
+| Seam | Wired with | Runs | Can veto? |
+|---|---|---|---|
+| Custom minter | `abx set-minter --minter 0x…` | before/calling issuance | it controls whether it calls mint |
+| Configure hook | `abx set-param-hooks --configure 0x…` | before a governed parameter write persists | yes |
+| Transfer hook | `abx set-param-hooks --transfer 0x…` | on mint, transfer, and burn | yes |
+| Augment hook | `abx set-param-hooks --augment 0x…` | while token data is assembled | no; computes/adds/overrides data |
+| Image/traits renderer | deploy-code renderer flags | while on-chain metadata fields render | a revert can break that read; design never-revert |
+| Seed source | `abx set-seed-source` | future code-token mints | supplies mint-time seed input |
+| Transfer validator | `--721c` then `set-transfer-validator` | standards-track transfer validation | yes, according to validator |
+
+One external contract may implement several hook/minter roles. Test it against a real deployed clone,
+not a mock that approximates ABX callbacks.
+
+ABX scaffolds a Foundry renderer project but does not compile or deploy custom Solidity. The creator
+or their contract engineer owns code review, deployment, verification, upgrade policy, and audits.
+
+### Custom minter
+
+Series and editions can authorize one minter contract. Use it for pricing/allocation rules that do not
+fit the shared fixed-price minter: auctions, allowlists, raffles, free claims, ERC-20 payment, escrowed
+issuance, or other pre-mint logic. The minter eventually calls the token's canonical mint entry point.
+
+A plain 1/1 has no Series minter seam. Decide whether the requested issuance model actually requires
+a Series/edition before deploying.
+
+### Configure hook
+
+The configure hook receives the proposed typed parameter write before it persists. Its revert rejects
+the write. It can enforce monotonicity, one-time writes, cross-contract authorization, payload shape,
+or size bounds. For blob-backed strings/bytes, validate length before reading large data and read the
+provided data pointer using the documented SSTORE2 convention.
+
+The previously stored value remains visible during validation, enabling comparisons. A rejected
+write may still have paid for preparatory blob storage; front ends should simulate before asking for a
+signature.
+
+### Transfer hook
+
+The transfer hook runs for mints (`from == 0`), ordinary transfers, and burns (`to == 0`). Reverting
+vetoes the entire operation. It can implement vesting, soulbinding, redemption, escrow settlement,
+provenance counters, and lifecycle rules.
+
+It cannot initiate a transfer; it only observes or rejects one. Burn-based mechanics require the
+collection to have been deployed burnable. On editions, ids may have many holders, so shared per-id
+state cannot model a single current owner.
+
+### Augment hook
+
+The augment hook is a read-time view seam. It may read other contracts, an oracle, block state, or
+stored params and return final token-data strings. Use it for live/derived state or computed data that
+should not be stored.
+
+Volatile augmentation makes the live view change without an event or stored write. A marketplace still
+remains a snapshot until it is rendered again. If a custom Solidity field renderer needs augmented
+state, it must read/call the relevant hook/state itself; field-renderer calls do not receive a prepared
+token-data object.
+
+## Map mechanics to seams
+
+| Request | Primary route | Prerequisites/limits |
 |---|---|---|
-| **`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.
+| Auction, allowlist, raffle, free claim | custom minter | Series or edition mint authority |
+| ERC-20 priced mint | custom minter | payment logic/audit outside ABX |
+| Soulbound or timed transfer lock | transfer hook | deploy-code; hook also sees mint |
+| Burn-to-redeem/combine | external controller/minter + burnable; optional transfer/augment hooks | ABX provides seams, not the atomic combine implementation |
+| Escrow tied to token lifecycle | minter + transfer hook | external value-holding contract |
+| Monotonic level/high-water mark | governed param + configure hook | schema and old-value comparison |
+| Structured collector configuration | governed param + configure hook | typed payload and bounded size |
+| Holder of another token may configure | schema address auth or configure hook | cross-contract read |
+| Art reacts to oracle/block/other contract | augment hook or renderer direct read | disclose live/non-deterministic behavior |
+| Timed reveal | augment hook or renderer logic | live view versus still refresh distinction |
+| On-chain SVG and coherent traits | image + attributes renderers | never-revert Solidity implementations |
+| Large raster stored on-chain | `--onchain-image` | measured write cost and endpoint-dependent read reach |
+| Royalty-aware transfer validation | ERC-721C/ERC-1155C validator | opt-in at deploy; marketplace compatibility varies |
+
+When several routes work, prefer the smallest authority surface. Use the stock fixed-price minter
+instead of custom Solidity for an ordinary sale; use a schema without a hook when static authorization
+is sufficient; use an on-chain renderer only when its durability/reach/cost trade is desired.
+
+A transfer hook only observes or vetoes a burn; it does not initiate two burns or mint a replacement.
+For combine mechanics, prove the controller's burn authorization and canonical mint call against a
+real clone, make the transition atomic and replay-safe, and define pair/history storage. On ERC-721,
+`--max` is a lifetime id cap and burns do not reopen slots, so reserve replacement-id headroom or use
+a supply policy that does not require new ids. On a burnable edition, a burn frees live per-id supply,
+but every copy of an id shares its id-level seed and PostParams.
+
+## Respect deploy-time prerequisites
+
+Ask about mechanics before deployment. These decisions cannot be retrofitted:
+
+- static versus code-capable contract type; hooks/PostParams require SeriesCode or EditionCode;
+- ERC-721 versus ERC-1155 edition shape through `--copies`;
+- burnability;
+- ERC-721C/ERC-1155C enrollment.
+
+Other choices may be mutable but become irreversible when locked: URI configuration, fields, script,
+dependencies, hooks, governed values/schema, royalty ceiling, and owner authority. An existing project
+may therefore be capable in protocol terms but foreclosed by its current type or locks. Say that
+specifically instead of saying ABX as a whole cannot do it.
+
+Use `abx predict` to break address cycles where an external controller needs the token address at its
+own construction and the token must reference the controller during deployment. Confirm the guarded
+salt/deployer and predicted address before deploying either side.
+
+## Know the supported boundary
+
+The toolkit currently does not provide:
+
+- mainnet deployment or unsupported-chain recipes;
+- a secondary-market listing/order-book feature;
+- Solidity compilation/deployment through `abx`;
+- CLI replacement of a deployed code project's script;
+- retrofitting a deploy-time contract type, burnability, token standard, or creator-token enrollment.
+
+Do not recommend another protocol automatically when one of these applies. State the boundary and
+stop unless the creator asks for alternatives.
+
+Also distinguish unsupported tooling from possible external engineering. For example, ABX does not
+compile a custom hook, but a hook is an intentional supported seam once independently built and
+deployed. Conversely, “arbitrary Solidity exists” is not proof that every behavior is safe or
+compatible: analyze callback timing, authority, reverts, reentrancy, shared edition state, gas, and
+upgradeability.
+
+Before finalizing a custom mechanic, document:
+
+1. canonical token family and deploy-time prerequisites;
+2. external contracts and their roles/owners/upgrade paths;
+3. callback inputs, state transitions, and every veto path;
+4. mint/transfer/burn behavior including editions;
+5. parameter schema and authorization;
+6. live versus settled/rendered state;
+7. locks and the exact guarantee they create;
+8. unit, fork, and end-to-end test plan;
+9. collector-facing disclosure of remaining powers.