@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.40

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

@@ -0,0 +1,188 @@
+# Capability questions and extension seams
+
+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.
+
+## Contents
+
+- [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)
+
+## Use the four-way classification
+
+Classify the request as one of:
+
+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.
+
+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.
+
+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.
+
+## Inspect the machine-readable contract
+
+Run:
+
+```bash
+abx capabilities --json
+abx help <relevant-command>
+```
+
+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.
+
+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.
+
+## 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 |
+|---|---|---|
+| 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 |
+| One program, each token carries its own data | `deploy-code --script` + `<key>:Bytes:Creator` | mint, then set the creator payload with `configure-param --file`; no on-chain size budget on the param itself |
+| 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.

package/skill/reference/code.md

@@ -0,0 +1,211 @@
+# Code projects, renderers, and PostParams
+
+Use this reference for `preview`, `inspect`, `deploy-code`, JavaScript/build projects, Solidity field
+renderers, marketplace stills and traits, seeds, dependencies, parameters, and code-project locks.
+
+## Contents
+
+- [Choose the runtime lane](#choose-the-runtime-lane)
+- [Design every public surface](#design-every-public-surface)
+- [Preview and inspect honestly](#preview-and-inspect-honestly)
+- [Plan JavaScript projects](#plan-javascript-projects)
+- [Plan Solidity field renderers](#plan-solidity-field-renderers)
+- [Use PostParams and hooks](#use-postparams-and-hooks)
+- [Handle seeds and dependencies](#handle-seeds-and-dependencies)
+- [Verify and freeze](#verify-and-freeze)
+
+## Choose the runtime lane
+
+`deploy-code` selects a code-capable canonical contract. It supports four useful input shapes:
+
+| Shape | Core flags | Typical surfaces |
+|---|---|---|
+| On-chain JavaScript template | `--script <file>` | on-chain program; hosted or on-chain assembled live document |
+| Shared program + per-token payload | `--script` + `--schema <key>:Bytes:Creator` | one chunked engine; after mint, set each token's `Bytes` PostParam with `configure-param --file` |
+| Build directory | `--code-dir <dir>` | uploaded application bundle; resolver/live view |
+| Solidity-computed fields | `--image-renderer` and/or `--attributes-renderer` | on-chain SVG image and/or traits |
+| Hybrid | script plus field renderers | program animation plus Solidity image/traits |
+
+Without `--copies`, the contract is SeriesCode (ERC-721). With `--copies <n|open>`, it is EditionCode
+(ERC-1155): N generated ids, each with multiple copies. EditionCode currently supports scripts,
+dependencies, and field renderers. It does not support `--code-dir`, `--image-base`, or `--resume`.
+Run `abx capabilities --json` immediately before planning.
+
+For one generated work with 100 copies, use `--max 1 --copies 100`. Omitting `--max 1` leaves the
+default multi-id space, producing multiple generated ids with 100 copies available for each id.
+
+A creator who needs parameters or hooks must use a code-capable contract even if the output is a
+static-looking SVG or image. This is a deploy-time type decision.
+
+## Design every public surface
+
+A code project is not one URL. Decide each surface separately:
+
+- **Program/animation** — the live JavaScript document or absence of one.
+- **Marketplace image** — a rendered still, a deterministic image URL, an on-chain Solidity SVG, or
+  an explicit placeholder during development.
+- **Marketplace traits** — renderer-computed JSON, resolver/effects output, or intentionally omitted.
+- **PostParams** — canonical typed state on the token contract, consumed by the program/renderers.
+- **Attachments** — named files served through a resolver's artifacts/data surface.
+
+“The program is on-chain” does not prove that image and traits are on-chain. “The animation works”
+does not prove a marketplace thumbnail exists. Write a surface matrix before deployment and verify
+each row after minting.
+
+## Preview and inspect honestly
+
+Use `abx preview` while authoring and `abx inspect` before choosing a deployment lane.
+
+Preview uses the canonical runtime envelope, dependency order, and token-data shape with synthetic
+inputs. It is a high-fidelity authoring preview, not an end-to-end deployment proof. It does not prove:
+
+- that a chosen dependency resolves on the target chain;
+- that the deployed generator or renderer fits an RPC's read allowance;
+- that real minted seeds and PostParams are consumed correctly in every state;
+- that marketplace metadata contains image and attributes;
+- that a hosted resolver/effects/storage path is reachable.
+
+Use `--shoot` for representative frames. Exercise more than the default seed and every user-facing
+parameter. Then run `abx inspect` to analyze dependencies, deterministic seed usage, declared traits,
+document size, and lane fit. Treat findings as evidence and the deploy dry run/testnet verification as
+the final proof.
+
+Avoid unseeded randomness, wall-clock dependence, environment-only assets, and network fetches when
+claiming reproducibility. A live-data design is valid; label it live rather than deterministic.
+
+## Plan JavaScript projects
+
+### On-chain program, hosted resolution
+
+Use `--script` with `--public-base-url` when a resolver should assemble the live document and expose
+mutable metadata/render surfaces. The script remains on-chain; the public metadata path is HTTP.
+This is normally the most interoperable lane for a sale where thumbnails must update continuously.
+
+Run an effects service for derived stills and traits:
+
+- `abx effects` runs locally and blocks; use it for development or a co-located operator.
+- `abx deploy-effects --resolver-url <url>` scaffolds a continuously running service.
+- `abx render <addr> [ids] --remote <resolver>` performs a one-shot/backfill render.
+
+The renderer must store its bytes in a backend the resolver can retrieve. A hosted resolver cannot
+read a laptop-local `fs` store. Managed providers may advertise managed rendering; confirm with
+`abx remote <name>` rather than assuming it.
+
+### On-chain program and on-chain live document
+
+Use `--script --onchain-uri` when the generator can assemble the animation document entirely from
+on-chain program/dependency bytes. This can remove an always-on resolver for the live program.
+
+Check the deploy dependency report and `abx verify` before calling it chain-complete: a registry
+dependency may resolve through a CDN instead of on-chain bytes. Large assembled documents may exceed
+some endpoints' `eth_call` allowance; report the measured reach, not “any RPC forever.”
+
+For a JavaScript lane, the marketplace image remains a separate decision. With no resolver watcher,
+a still published to a deterministic public `--image-base` is a manual/backfill surface: rerun render
+after relevant parameter changes. An on-chain animation plus automatically updating off-chain still
+requires an operator watching state.
+
+EditionCode does not currently accept `--image-base`. Give it an on-chain image renderer, or run a
+resolver/effects path (`deploy-effects` for continuous rendering; `render --remote` for one-shot
+publication). Do not treat its on-chain animation as a marketplace still.
+
+### Build directory
+
+Use `--code-dir` for an application bundle whose files are uploaded and addressed as a code artifact.
+It requires external storage and public resolution. Inspect the built output, not only the source
+tree, and verify that every referenced asset is included. `--code-dir` is not yet supported with
+`--copies`.
+
+## Plan Solidity field renderers
+
+`--image-renderer <address>` stores an `IAbxFieldRenderer` pointer for the metadata image field;
+`--attributes-renderer <address>` does the same for traits. With `--onchain-uri`, the canonical
+metadata renderer calls them on-chain. A renderer-only project needs no JavaScript program and no
+effects runner.
+
+Start with `abx scaffold-renderer`, then build, test, and deploy the Solidity project using Foundry.
+ABX does not compile or deploy custom Solidity. A real deploy refuses a renderer address with no
+code.
+
+Enforce these invariants in renderer tests:
+
+- `render(token, tokenId, field)` must not revert for unminted ids, missing params, boundary values,
+  unexpected callers, or retired schema state.
+- Return the correct media type and valid complete content: SVG for image, JSON attributes array for
+  traits.
+- Derive image and traits from the same seed/state model.
+- Bound loops and output. Test realistic worst cases through an RPC call, not only local unit gas.
+- Treat a renderer or hook address lock as a pointer lock. Use immutable deployments for stronger
+  permanence claims; an upgradeable proxy can change behavior behind a locked address.
+
+Solidity image/attributes renderers work on both SeriesCode and EditionCode, including renderer-only
+editions. They eliminate off-chain stills only for the fields they compute; a separate JavaScript
+animation may still exist.
+
+## Use PostParams and hooks
+
+PostParams are typed, schema-governed state stored on-chain. Use `--schema` at deployment or
+`abx set-schema` later, then `abx configure-param` through the governed path. Inspect current type,
+authorization, and lock grammar with command help instead of memorizing it.
+
+Model parameters deliberately:
+
+- Define a stable key and type; do not change a key's meaning across versions.
+- Choose creator, token-owner/holder, or address authorization to match the actual state model.
+- Validate input in the UI and again in a configure hook when the rule must be enforced on-chain.
+- Treat string/bytes values as potentially large and price/limit them appropriately.
+- Retire or weld a governed parameter only after the current value and defaults are verified.
+
+### Edition shared state
+
+On EditionCode, parameters belong to an **id**, not an individual physical copy. If token id 3 has
+100 holders, they all read the same value for id 3. With holder authorization any holder may write it;
+the last valid writer wins. This is good for communal state and wrong for “name my personal copy.”
+Use one id per personalized work when per-holder state is required.
+
+A holder-writable large string/bytes parameter can also expand the shared id's metadata beyond common
+RPC read reach. State this before deployment and use schema validation/hooks to bound it when needed.
+
+### Hooks
+
+SeriesCode and EditionCode expose three configurable hook addresses:
+
+- configure hook: validates/vetoes governed writes before they persist;
+- transfer hook: observes every mint, transfer, and burn and may veto the operation;
+- augment hook: computes additional/overriding token data during reads.
+
+Hooks are extension seams, not ordinary CLI flags. Build and deploy them outside ABX, wire them with
+`abx set-param-hooks`, test against a real clone, and read [capabilities.md](capabilities.md). A
+transfer-hook revert fails mints as well as secondary transfers. Freeze the addresses with
+`abx lock-param-hooks` only after testing every lifecycle transition.
+
+## Handle seeds and dependencies
+
+Seeds are generated at mint and drive reproducible variation. `abx inspect` identifies common seed
+misuse, but test multiple real token-data fixtures. A custom seed source affects future mints and is
+an external contract pointer; verify its code/interface and disclose who can change its behavior.
+
+Dependencies are ordered; index 0 is the runtime. A `name@version` reference resolves through the
+collection's dependency-registry pointer, while a `0x…` reference reads a data contract directly.
+Registry availability is chain-specific. Read the deploy dependency report: a named dependency can
+be valid yet served from a CDN, which means the document is not chain-complete.
+
+`lock-dependencies` freezes the reference list and registry pointer, not necessarily the bytes a live
+registry entry returns. Use immutable on-chain data contracts for a stronger frozen-dependency claim.
+
+## Verify and freeze
+
+After deploying and minting representative ids:
+
+1. Read `abx state`, `abx tokens --json`, and `abx tokenuri`.
+2. Open the animation/live view using actual minted token data.
+3. Fetch the marketplace image and inspect `attributes` from token metadata.
+4. Run `abx verify` and resolve placeholder, chain-complete, dependency, or render warnings.
+5. Change every intended parameter through its authorized path; confirm still refresh behavior.
+6. Exercise mint, transfer, and burn paths if hooks or burnability are involved.
+7. Verify dependency and renderer addresses and whether their code is upgradeable.
+8. Lock only the surfaces the creator has explicitly chosen to freeze.
+
+A fully frozen code-project posture may involve URI/field locks, `lock-script`,
+`lock-dependencies`, `lock-param-hooks`, and governed parameter locks. Those locks cover different
+state. Describe exactly what each freezes; never summarize them as “the output can never change.”

package/skill/reference/creator-token.md

@@ -0,0 +1,94 @@
+# ERC-721C / ERC-1155C transfer validation
+
+Use this reference only when the creator asks about creator-token standards, transfer validation,
+royalty-enforcement compatibility, validator selection, or changing/suspending validation.
+
+## Separate three mechanisms
+
+- **Royalties** declare a receiver and basis points through the token's royalty interface. They do
+  not force a marketplace to pay.
+- **Creator-token enrollment** opts the collection into ERC-721C or ERC-1155C validation at deploy.
+  Transfers consult a validator selected by the owner.
+- **ABX transfer hooks** are code-project extension callbacks and may implement arbitrary project
+  lifecycle rules. They are not creator-token validators.
+
+These mechanisms can coexist and may each reject a transfer for a different reason. Diagnose the
+actual contract state and revert path.
+
+## Enrollment is deploy-time
+
+Pass `--721c recommended|0x…` on the selected deploy command to create the creator-token variant. The
+same flag chooses the ERC-1155C twin when `--copies` selects an edition. Absence creates the ordinary
+ERC-721/ERC-1155 family.
+
+Enrollment cannot be added or removed after deployment. Ask before spending:
+
+- Does the creator actually want standards-track transfer validation?
+- Which validator and security policy should govern transfers?
+- Is the intended marketplace/wallet flow compatible on the target chain today?
+- Who may later change or suspend the validator?
+- Is the stronger restriction worth the interoperability and owner-power tradeoff?
+
+Do not default into enrollment merely because the creator set a royalty. Do not present it as a
+guarantee of payment across all marketplaces.
+
+## Select and validate the validator
+
+`recommended` resolves the toolkit's current recommended creator-fee validator for the active chain.
+An explicit address must be a deployed validator contract that actually implements the expected
+interface and rejects unsupported calls. A Safe, EOA, empty proxy, or permissive fallback is not an
+enforcement policy even if it has code.
+
+Let the CLI probe the address. Do not bypass a refusal with a raw transaction. For a custom validator,
+review and test:
+
+- transfer behavior for owner, approved operator, marketplace conduit, and ordinary recipient;
+- mint and burn behavior where the standard invokes validation;
+- upgrade/administration powers and who controls them;
+- failure behavior when external registries are unavailable;
+- ERC-721 versus ERC-1155 amount/batch semantics;
+- interaction with an ABX transfer hook.
+
+Marketplace allowlists, registry addresses, and supported flows change. Use current command output,
+the validator's primary documentation, and a testnet transaction rather than a dated compatibility
+table in this skill.
+
+## Operate an enrolled collection
+
+Read current enrollment and validator state with `abx state`. Use:
+
+```bash
+abx set-transfer-validator <address> recommended
+abx set-transfer-validator <address> 0x...
+abx set-transfer-validator <address> none
+```
+
+Run command help for current syntax and a dry run before writing. Setting `none` suspends the active
+validator where supported; it does not convert the contract back to a plain non-C token. Enrollment
+and the associated owner power remain part of the contract's permanent type.
+
+Before changing the validator:
+
+1. Read the current validator, owner, royalty, minter, and transfer-hook state.
+2. Explain whether the change tightens, loosens, or suspends transfer policy.
+3. Test representative transfers using the intended marketplace/operator on testnet.
+4. Receive exact human confirmation.
+5. Execute once and re-read state.
+
+If a transfer fails, do not clear the validator as a generic repair. Determine whether the failure
+comes from the creator-token validator, an ABX transfer hook, token ownership/approval, pause/mint
+rules, or the receiving contract. Changing enforcement is a policy decision, not troubleshooting.
+
+## Disclose owner powers precisely
+
+Collectors should know:
+
+- the collection is permanently enrolled in the creator-token variant;
+- the current validator address and whether it is upgradeable;
+- who can change or suspend that validator;
+- whether a separate ABX transfer hook can veto transfers/mints;
+- whether hook addresses are locked;
+- the royalty rate, receiver, and permanent ceiling.
+
+A locked ABX hook set does not lock the creator-token validator, and creator-token enrollment does not
+freeze royalties. List each power separately.

package/skill/reference/deploy.md

@@ -0,0 +1,167 @@
+# Static projects and editions
+
+Use this reference for `abx deploy`, `abx deploy-series`, their `--copies` editions, content
+placement, identity, mint timing, and deploy confirmation.
+
+## Contents
+
+- [Choose the contract shape](#choose-the-contract-shape)
+- [Choose custody and resolution](#choose-custody-and-resolution)
+- [Understand on-chain reach](#understand-on-chain-reach)
+- [Prepare identity and economics](#prepare-identity-and-economics)
+- [Plan editions correctly](#plan-editions-correctly)
+- [Plan, execute, and verify](#plan-execute-and-verify)
+
+## Choose the contract shape
+
+Start from the artifact and supply model, not from a preferred storage backend:
+
+| Creator intent | Command | Contract family |
+|---|---|---|
+| One static work, one token | `abx deploy` | OneOfOneImage, ERC-721 |
+| Folder of N distinct works | `abx deploy-series` | SeriesImage, ERC-721 |
+| One work with multiple copies | `abx deploy --copies <n|open>` | OneOfOneEdition, ERC-1155 |
+| N distinct works, copies of each | `abx deploy-series --copies <n|open>` | EditionImage, ERC-1155 |
+
+If the work needs collector parameters, state-derived output, or configure/transfer/augment hooks,
+use `deploy-code` even when the visible artifact looks static. Contract family is fixed at deploy;
+static contracts cannot gain code extensions later.
+
+Run `abx capabilities --json` and the chosen command's help before constructing the plan. The
+capability contract, help, flag validation, and dry-run output are current product truth.
+
+## Choose custody and resolution
+
+Treat custody, resolution, and mutability as separate decisions.
+
+### Bytes and metadata fully on-chain
+
+Use `--onchain-image [--compress fastlz]` for static media bytes behind the on-chain metadata
+renderer. It implies on-chain resolution and requires no host or storage provider. It works for 721
+static projects and their editions in hot or wallet lanes. Cold `--unsigned` staging is refused.
+
+Use `fastlz` for on-chain-readable compression. Gzip is an off-chain decode format and cannot be
+substituted for an on-chain-rendered field. Bare `--onchain-uri` may inline very small SVG/text
+content, but the reader/chunk path is normally more economical for real files; trust the dry-run's
+measured plan rather than a memorized byte threshold.
+
+### Media external, metadata JSON on-chain, no resolver
+
+Use `--onchain-uri --backend arweave|ipfs|cloud`. The CLI uploads media, bakes its public locator into
+on-chain JSON, and does not require an ABX resolver. This is often the simplest durable path for
+static collections:
+
+- Arweave provides pay-once permanent custody through the configured uploader.
+- IPFS requires maintained pinning and a public gateway; a local kubo gateway is development-only.
+- Cloud requires an authenticated upload endpoint and a distinct public read base/CDN URL.
+
+For uniform-extension Series folders, the CLI can use a shared directory/template representation
+rather than one collection field per item. Let the dry run report the chosen representation.
+
+This path can still carry on-chain description, attributes, authorship, license, and other reserved
+fields. “External image” does not mean “off-chain metadata.”
+
+### Hosted resolver
+
+Use `--public-base-url https://…` when metadata must remain operationally editable, when arbitrary
+attached files need enumeration, when large on-chain reads need an HTTP front, or when a JavaScript
+project needs hosted live/render surfaces. The URL must be public and stable; the CLI refuses
+localhost for a real deploy.
+
+A resolver may be managed by a configured remote provider or run by the creator. That choice does
+not change the token contract. Read [hosting.md](hosting.md) before promising who operates the
+service, how effects are rendered, or how migration works.
+
+### Local filesystem
+
+Use `fs` only for local preview and disposable testnet iteration. A token whose public metadata
+depends on a laptop path is not launched. Move the bytes or run a public resolver before presenting
+the collection as complete.
+
+## Understand on-chain reach
+
+There is no fixed supported byte ceiling for `--onchain-image`. Writes are chunked; cost grows with
+the stored bytes. Resolution rebuilds the document in one `eth_call`; success depends on the read-gas
+allowance of the endpoint making that call.
+
+The CLI estimates write cost, estimates read cost, probes the active endpoint, and reports whether the
+document fits that endpoint's measured allowance. Preserve these distinctions:
+
+- A successful write proves storage, not universal display reach.
+- A successful read through the creator's RPC says nothing certain about a marketplace's RPC.
+- Compression can reduce write cost without reducing the gas needed to reconstruct uncompressed
+  output.
+- The limit is per token, not the aggregate size of the collection.
+- If direct self-resolution has insufficient reach, the bytes remain on-chain; a resolver can read
+  them through a capable endpoint and serve ordinary HTTP after `set-renderer --off`.
+
+Never call a size impossible merely because it is expensive or endpoint-dependent. State the dry
+run's cost and reach, offer external permanent custody or resolver-fronted access as alternatives,
+and let the creator decide.
+
+## Prepare identity and economics
+
+Propose and confirm a real name and symbol. The CLI may infer placeholders for a dry run but refuses
+to silently bake a generic identity on a real send unless the user explicitly accepts it. A folder
+named `images` is not a collection title.
+
+Confirm these fields as applicable:
+
+- description and external URL;
+- creator, display notes, creator links, and license;
+- initial royalty and royalty receiver;
+- royalty cap, which is a permanent ceiling that may only decrease;
+- burnability, fixed at deploy;
+- ERC-721C/ERC-1155C enrollment, fixed at deploy;
+- owner/deployer and primary-sale payee;
+- whether metadata fields begin on-chain or in the resolver projection.
+
+The owner may change ordinary royalties within the cap. Lowering the cap is irreversible. Do not
+equate declared royalties with enforced creator fees; transfer-validator enrollment is a separate
+creator-token decision described in [creator-token.md](creator-token.md).
+
+### Mint timing
+
+Choose among minting during deployment, pre-warming with no mint, or preminting part of a Series.
+Pre-warming is valuable when a resolver or render pipeline must be ready before marketplaces observe
+the first token. For hosted paths, register/index and verify the predicted or deployed contract before
+minting; then mint and refresh.
+
+The shared fixed-price minter is normally configured after deployment: set price/allocation, set the
+minter/payee, and unpause when ready. Deploy-time minter flags pre-authorize a known stack; they are not
+a substitute for confirming the actual sale configuration.
+
+## Plan editions correctly
+
+`--copies` changes both the token standard and the ownership model.
+
+- `deploy --copies 100` means one id with a cap of 100 copies.
+- `deploy-series --copies 100` means every folder item is its own id with up to 100 copies.
+- `open` means an uncapped edition at deployment; later cap operations only lower numeric caps.
+- `--mint-amount` is copies per preminted id; `--mint-count`/`--mint-all` select which ids premint.
+- Transfers require an amount and explicit source because an id can have many holders.
+
+For any edition, say “N ids × M copies per id” and the maximum aggregate supply before spending.
+
+Static edition custody is symmetric with the 721 lanes: on-chain bytes, on-chain JSON with external
+media, inline SVG, and hosted resolution are available. `--onchain-image` uses hot or wallet signing,
+not cold unsigned staging.
+
+Do not import code-edition limits into static editions or vice versa. Use the capability output.
+
+## Plan, execute, and verify
+
+1. Run `abx doctor`, storage/remote checks needed by the selected path, and command help.
+2. Run the exact command with `--dry-run --json` and a known `--for` address when needed.
+3. Read back contract family, id/copy arithmetic, custody, resolution, public URLs, signer lane,
+   initial mint, transaction count, cost/reach warnings, and irreversible options.
+4. Receive explicit confirmation.
+5. Run the same normalized command without `--dry-run`; do not start another write using the EOA.
+6. Capture the chain, contract address, deploy block, owner, storage locators, and resolver/remote.
+7. Verify `state`, `contracturi`, `tokenuri`, public image retrieval, and byte integrity.
+8. If pre-warmed, register/serve first, mint second, verify the token-specific surfaces, then refresh.
+9. Apply locks only after production-path verification.
+
+For Arweave or other eventually available storage, an accepted upload is not yet a retrievable asset.
+Use `abx storage status <locator> --json` and wait for `ready`; do not upload again simply because a
+gateway is still propagating.