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

package/skill/reference/code.md

@@ -0,0 +1,210 @@
+# 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 |
+| 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

@@ -1,99 +1,94 @@
-# Royalty enforcement — opt-in creator token (ERC-721C / ERC-1155C)
-
-[← back to SKILL.md](../SKILL.md)
-
-**Read this ONLY because the creator brought it up** (royalty enforcement, "make OpenSea pay my
-royalties", ERC-721C/ERC-1155C, transfer restrictions, a transfer validator). If they didn't, this file
-has no business in the conversation: **plain ERC-721 (or plain ERC-1155, for an edition) is the default
-and the recommendation**, every deploy flow already does the right thing with zero `--721c` flags, and
-offering enforcement unprompted reads as a nudge toward a restricted asset. Never present `--721c` as a
-checklist item, a "should we also…", or a row in the deploy readout for a creator who never asked.
-
-**Same flag, both standards.** `--721c` is the one flag for creator-token enrollment everywhere — on a
-721 deploy (`deploy`/`deploy-series`/`deploy-code` with no `--copies`) it enrolls **ERC-721C**; on the
-same commands with `--copies` (an edition) it enrolls **ERC-1155C** instead. Same validator registry,
-same recommended validator, same permanence rule, same UX — only the ERC-165 discovery ids and the
-per-transfer call differ, both invisible to a creator (below).
-
-## The stance (how to frame it when asked)
-
-- **Plain ERC-721 — or plain ERC-1155 for an edition — is the more sovereign asset (the default)**:
-  no third-party contract on the transfer path, tradeable everywhere, nothing anyone — creator
-  included — can later switch off. ABX royalties are already on-chain via ERC-2981
-  (`abx set-royalty`); marketplaces *choose* whether to honor them.
-- **721C/1155C is enforcement for creators who specifically want it**: transfers are checked by a
-  validator contract, and sales that don't route through an authorized venue revert. It is a real
-  trade-off, decided at deploy, **permanently** — present it transparently, recommend it only when
-  the creator's stated goal is enforcement, and get an explicit yes before enrolling.
-- **The honest market picture (2026) — say it, don't oversell**: enforcement via 721C effectively
-  means **OpenSea** plus venues on Limit Break's Payment Processor. OpenSea's own help docs say
-  enforcement limits sales to those venues; Magic Eden's EVM marketplace shut down March 2026, and
-  Blur never honored 721C. The trade: enforced royalties on OpenSea, in exchange for not trading on
-  venues the validator doesn't authorize.
-
-## What enrolling does (the facts to relay)
-
-- **Deploy-time, permanent, both directions.** A plain ABX token (721 or 1155) can **never** grow
-  transfer restrictions later (that's a feature — collectors of unenrolled tokens keep that promise
-  forever), and an enrolled one never sheds the standard. No retrofit exists; the only path to
-  enrollment for a live plain collection is a redeploy.
-- **Suspend ≠ un-enroll.** The owner can re-point the validator or set it to zero (enforcement off,
-  token **stays** enrolled — the owner can re-enable any time). Collectors can see enrollment via
-  ERC-165, suspended or not.
-- **Mints and burns are NEVER validated** — no validator policy can brick minting, the shared
-  fixed-price minter (721 or edition), or a delegated minter.
-- **The recommended validator** (`--721c recommended`, or bare `--721c`) is OpenSea's
-  StrictAuthorizedTransferSecurityRegistry — the same registry, same address, for both standards.
-  Under it, owner-initiated wallet-to-wallet transfers pass; non-authorized operators revert. One
-  decision, done.
-- **On an edition, validation is per `(id, amount)`, not per token.** ERC-1155C's validator call
-  carries the transferred amount and isn't a view (unlike 721C's), and a batch transfer loops one
-  validator call per id — invisible to a creator, but the reason a large batch transfer on an
-  enrolled edition costs more gas than an unenrolled one.
-
-## Commands
+# 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
-# Enroll at deploy — all three deploy commands take the flag (absent = plain, forever):
-abx deploy|deploy-series|deploy-code … --721c [recommended|0x<validator>]
-# On an edition deploy (--copies), the SAME flag enrolls ERC-1155C instead — nothing else changes.
-abx deploy --copies <n|open> … --721c [recommended|0x<validator>]
-
-# Operate an ENROLLED collection (owner-only, any signing lane, --dry-run works):
-abx set-transfer-validator <addr> 0x<validator>   # re-point enforcement
-abx set-transfer-validator <addr> none            # suspend (stays enrolled)
-abx set-transfer-validator <addr> recommended     # the chain's recommended validator
-
-abx state <addr>   # shows a "721C validator" row ONLY when enrolled ("suspended" when zero);
-                    # an enrolled EDITION shows the same row labeled "1155C validator" — same
-                    # ERC-165 id + getter on both standards, so detection is identical
+abx set-transfer-validator <address> recommended
+abx set-transfer-validator <address> 0x...
+abx set-transfer-validator <address> none
 ```
 
-Enrolling prints one plain statement of what enforcement means — relay it, don't embellish. An
-un-enrolled deploy prints nothing about 721C/1155C.
-
-**One exception to "owner-only", worth knowing before you tell a collector they're stuck:** once a
-collection's `owner()` is the zero address (renounced), **anyone** may send the `none` (suspend) form,
-and **nobody** may ever arm a validator again. It's the release valve for an abandoned collection whose
-validator reverts every transfer — the only thing a stranger can do is make the tokens transferable, never
-the reverse. So a creator who plans to renounce should hear the trade: "renounced **and** still enforcing
-royalties forever" is not a state this protocol offers.
-
-## Refusals the CLI enforces (don't fight them; relay the reason)
-
-- **`--721c none`/zero at deploy** — refused: a zero validator never enrolls, and "enrolled but
-  suspended" is not a deploy-time state. Plain (721 or 1155) is already the default; drop the flag.
-- **`--721c recommended` on a chain with no known validator** — refused, naming the chains that have
-  one. Pass an explicit deployed validator address instead; never guess one.
-- **A validator address that isn't a validator** — refused before any gas at deploy AND at re-point
-  (the contract reverts `InvalidTransferValidator()`); a mixed-case address must pass its EIP-55
-  checksum. **Two shapes are refused, not one:** no code at all, and an address that answers *any*
-  call successfully — a **Safe**, an uninitialised proxy, or a 7702-delegated EOA. `validateTransfer`
-  returns nothing, so there's no decode to fail and such an address would enforce nothing while
-  `getTransferValidator()` and ERC-165 both reported enforcement as ON. If a creator offers their Safe
-  address, that's the refusal you'll get — relay it as "that's a wallet, not a validator", and point at
-  `recommended`. A real deploy also refuses to enroll blind when the RPC can't answer (a dry-run
-  defers it).
-- **`set-transfer-validator` on a plain, unenrolled collection** — refused up front (721 or 1155):
-  enrollment is a deploy-time decision and this collection didn't enroll. Do not retry with different
-  flags; if the creator truly needs enforcement, that's a redeploy conversation.
+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.