@artblocks/abx-cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/ownerops.js

@@ -6,22 +6,29 @@
  * served state reflects the change. The agent picks the lane; the human only
  * approves (wallet lane) or it's the env key (hot lane).
  */
-import { assertChainId, deployChunkStore, predictChunkStore, predictFixedPriceMinter, encodeReader, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, abxFixedPriceMinterAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, planChunks, planContentTxs, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetRoyalty, prepareSetTokenField, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareTransfer, prepareTransferOwnership, resolveChain, DEFAULT_CHAIN_KEY, stageContent, storeSupportsWriteContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
-import { SelfHostIndexer } from '@artblocks/abx-indexer';
-import { encodeScalarParam, encodeTag as encodeTagSdk, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
-import { paramsKeysIsLiteral, paramsKeysNudge, readParamsKeys } from './onchain-uri.js';
-import { DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
+import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, predictFixedPriceMinter1155, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, oneOfOneEditionAbi, seriesImageAbi, deployFixedPriceMinter, deployFixedPriceMinter1155, prepareConfigureSale, prepareConfigureSale1155, preparePurchase, preparePurchase1155, readSaleConfig, readSaleConfig1155, prepareEditionMint, prepareEditionTransfer, prepareSetMaxSupply, preparePingURI, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, mintedTokenIds, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, stageFieldContent, planStagedContent, exceedsOnchainSoftLimit, ONCHAIN_IMAGE_SOFT_LIMIT, ONCHAIN_PROJECT_SOFT_LIMIT, } from '@artblocks/abx-sdk';
+import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, tryReadContract, } from '@artblocks/abx-sdk';
+import { hasParamEnumeration } from '@artblocks/abx-sdk';
+import { decodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
 import { toHex as toHexSdk } from 'viem';
 import { readFileSync } from 'node:fs';
 import { basename, resolve as resolvePath } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import { formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
-import { chunkStoreAddress, fixedPriceMinterAddress } from './config.js';
-import { openWalletSession, signTx } from './signer.js';
-import { remoteAddProject } from './remote.js';
-import { unknownFlags } from './flags.js';
-const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // base-sepolia default — MUST match main.ts/config.ts (a stale 'sepolia' here silently ran every owner-op on the wrong chain)
+import { CHAIN, chainId, fixedPriceMinterAddress, fixedPriceMinter1155Address, localIndexer } from './config.js';
+import { CliError } from './errors.js';
+import { detectTokenKind } from './kind.js';
+import { openWalletSession } from './signer.js';
+import { gatedSend, laneFromFlags } from './riskgate.js';
+import { withJson } from './jsonout.js';
+import { resolveRemote, serviceClient } from './remote.js';
+import { isDryRun, positionalArgs, unknownFlags } from './flags.js';
+import { parseSchemaSpecs, describeSchema } from './schema.js';
+// Re-exported for main.ts (the on-chain-vs-off-chain cost model + the compression-mode type now
+// live in the SDK's staging.ts, layered on planChunks/planContentTxs — see the comment at their
+// definition below).
+export { ONCHAIN_PROJECT_SOFT_LIMIT };
 // ── ANSI (local) ─────────────────────────────────────────────────────────────
 const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', yellow: '\x1b[38;5;221m' };
 const dim = (s) => `${C.dim}${s}${C.reset}`;
@@ -33,19 +40,30 @@ const bold = (s) => `${C.bold}${s}${C.reset}`;
 // COMPLETE set — but it's COMPUTED by the resolver/renderer from the token's fields + effect
 // outputs; it is never a field you set. These keys are that computed output, so setting them by
 // hand would only pollute the manifest with a bogus entry (a real round-1 agent trap). Refuse them
-// and point at the real verb. See specs/protocol/data-plane.md.
-const COMPUTED_FIELD_KEYS = new Set(['artifacts', 'abx_provenance']);
+// and point at the real verb. `abx_params` joins them for the same reason: it is COMPUTED from the
+// token's on-chain param enumeration, so a hand-set field of that name would be a decoy sitting
+// beside the real block. See specs/protocol/data-plane.md + specs/protocol/onchain-metadata.md.
+const COMPUTED_FIELD_KEYS = new Set(['artifacts', 'abx_params', 'abx_provenance']);
 export function assertSettableField(field) {
     if (COMPUTED_FIELD_KEYS.has(field)) {
         const what = field === 'artifacts'
             ? "the COMPUTED manifest (the complete list of this token's files), assembled by the resolver/renderer from your fields"
-            : 'the COMPUTED provenance list, assembled by the resolver/renderer';
-        throw new Error(`"${field}" is not a field you set — it's ${what}. To attach a file so it appears in the manifest, ` +
-            `pick your OWN key:\n    abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>`);
+            : field === 'abx_params'
+                ? "the COMPUTED parameter block, enumerated from the token's on-chain params (set one with `abx configure-param`, declare one with `abx set-schema`)"
+                : 'the COMPUTED provenance list, assembled by the resolver/renderer';
+        throw new Error(`"${field}" is not a field you set — it's ${what}.` +
+            (field === 'abx_params'
+                ? `\n  Set a param instead:\n    abx configure-param <address> <tokenId|-> <key> <value>\n  (or attach a FILE under your own key: abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>)`
+                : ` To attach a file so it appears in the manifest, pick your OWN key:\n    abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>`));
     }
 }
+/** Whether a value fits the literal `bytes32` lane of a raw contract-param write (printable ASCII,
+ *  ≤ 31 bytes). Anything longer takes the data path — one blob, its hash evented. */
+function fitsLiteralBytes32(value) {
+    return value.length <= 31 && /^[\x20-\x7e]+$/.test(value);
+}
 /** Flags `abx attach` recognizes — anything else warns (non-fatal), so a silent no-op flag surfaces. */
-const ATTACH_FLAGS = ['file', 'compress', 'collection', 'token', 'send', 'sign', 'unsigned', 'yes', 'dry-run', 'port', 'sign-url-file', 'remote'];
+const ATTACH_FLAGS = ['file', 'compress', 'collection', 'token', 'send', 'sign', 'unsigned', 'yes', 'dry-run', 'confirm', 'port', 'sign-url-file', 'remote'];
 /** Auto-detect the on-chain representation for an off-chain locator by its URI scheme. Returns null
  *  for anything that isn't a recognized durable/http locator (so `attach` can refuse it loudly
  *  rather than silently storing a bad value — the round-1 `--representation` guessing trap). */
@@ -59,21 +77,10 @@ export function representationForLocator(uri) {
         return R.url;
     return null;
 }
-function chainId() {
-    return resolveChain(CHAIN).id;
-}
-/** Resolve the signing lane from flags: --unsigned (cold) · --sign (wallet) · default hot. */
-export function laneFromFlags(flags) {
-    if (flags.unsigned)
-        return 'unsigned';
-    if (flags.sign)
-        return 'sign';
-    return 'send';
-}
 function requireAddress(address, usage) {
     if (!address || address.startsWith('--')) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
     }
     return address;
 }
@@ -81,55 +88,32 @@ function requireFlag(flags, name, usage) {
     const v = flags[name];
     if (!v || v === 'true') {
         console.error(`missing --${name}\nusage: ${usage}\n`);
-        process.exit(1);
+        throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
     }
     return v;
 }
-/** Run a prepared write through the chosen lane, then re-index if the project is known.
- *  Returns whether anything was BROADCAST (false on the cold lane — the tx was only printed). */
+/**
+ * Every owner-op's send choke point. Returns the {@link SignResult} when a tx was broadcast, else
+ * `null` (dry run, or the cold lane which prints a tx instead of sending one).
+ *
+ * It used to return a bare boolean. It returns the result now because a caller sometimes needs the
+ * *receipt* — `abx mint --json` has to report which token id was actually minted, and the only
+ * authoritative answer is the Transfer log the mint emitted. Callers that only asked "did it send?"
+ * keep working: `null` is falsy, and a result object is truthy.
+ *
+ * The dry-run preview / `--confirm` prompt / lane selection live in {@link gatedSend} — the SAME
+ * choke point the deploy family's resumed-setup send routes through — so this is now just "gate,
+ * then re-index if the project is known."
+ */
 async function runWrite(address, provider, flags, expectedSigner) {
-    // --dry-run: preview the exact tx and send NOTHING. This is the shared choke point for every
-    // owner-op, so --dry-run is uniform across them — it must never fall through to a real send just
-    // because the flag isn't wired per-command (a round-1 finding: `set-field --dry-run` silently
-    // reached the send lane and only stopped for lack of a key).
-    if (flags['dry-run']) {
-        const prepared = typeof provider === 'function' ? await provider(expectedSigner ?? zeroAddress) : provider;
-        console.log(`\n  ${C.bold}◆ ${prepared.summary}${C.reset}  ${dim('(dry run — nothing sent)')}`);
-        for (const [k, v] of Object.entries(prepared.fields))
-            console.log(`    ${dim(k.padEnd(12))} ${v}`);
-        console.log(`    ${dim('to'.padEnd(12))} ${prepared.to ?? dim('(contract deploy)')}`);
-        if (expectedSigner)
-            console.log(`    ${dim('owner'.padEnd(12))} ${expectedSigner}`);
-        console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
-        return false;
-    }
-    await assertChainId(CHAIN); // verify the RPC really is CHAIN before any irreversible write
-    const result = await signTx(provider, {
-        lane: laneFromFlags(flags),
-        chainKey: CHAIN,
-        expectedSigner,
-        yes: !!flags.yes,
-        port: flags.port ? Number(flags.port) : undefined,
-        signUrlFile: flags['sign-url-file'],
-    });
+    const result = await gatedSend(provider, flags, { chainKey: CHAIN, expectedSigner });
     if (!result)
-        return false; // cold lane — nothing broadcast
+        return null; // dry run, or the cold lane — nothing broadcast
     await reindexIfKnown(address, flags);
-    return true;
-}
-/** Resolve a `--remote [url]` owner-op target: explicit URL, else ABX_PUBLIC_BASE_URL / ABX_RESOLVER_URL. */
-function remoteResolverTarget(flags) {
-    const v = flags.remote;
-    if (v === undefined)
-        return null;
-    const base = v !== 'true' && v !== '' ? String(v) : (process.env.ABX_PUBLIC_BASE_URL ?? process.env.ABX_RESOLVER_URL);
-    if (!base) {
-        throw new Error('`--remote` needs a resolver URL: pass `--remote https://host` or set ABX_PUBLIC_BASE_URL in .env');
-    }
-    return base.replace(/\/+$/, '');
+    return result;
 }
 async function reindexIfKnown(address, flags) {
-    const indexer = new SelfHostIndexer();
+    const indexer = localIndexer();
     if (indexer.store.getRegistration(address)) {
         const { state, elapsedMs } = await indexer.reindex(address);
         console.log(`  ${green('✓')} re-indexed ${state.name ?? address}: ${state.eventCount} events in ${elapsedMs}ms`);
@@ -137,46 +121,55 @@ async function reindexIfKnown(address, flags) {
     else {
         console.log(dim(`  (not indexed by this node — run \`abx add ${address}\` then \`abx index\` to serve it)`));
     }
-    // Hosted-resolver nudge. A hosted resolver serves from ITS OWN store, so the LOCAL reindex above
+    // Remote-resolver nudge. A remote resolver serves from ITS OWN store, so the LOCAL reindex above
     // never reaches it: after an owner-op — especially a PostParam change — it stays stale, and its
     // effect runner never sees the new inputsHash, so the marketplace thumbnail never auto-updates.
-    // `--remote <url>` re-indexes the hosted resolver (incremental), which pings its effect runner
-    // (ABX_EFFECTS_URL) → the automatic re-render. This is what makes a hosted `configure-param` a
-    // one-command change (no separate `abx index --remote` + no stale thumbnail).
-    const remote = remoteResolverTarget(flags);
+    // `--remote <name|url>` re-indexes the remote resolver (incremental), which pings its effect
+    // runner (ABX_EFFECTS_URL) → the automatic re-render. This is what makes a remote
+    // `configure-param` a one-command change (no separate `abx index --remote` + no stale thumbnail).
+    // Best-effort BY DESIGN: the signed tx already landed, so a missing token soft-skips (a hard
+    // error here would turn an on-chain success into a CLI failure) — worse only than stale-until-reindex.
+    const remote = resolveRemote(flags.remote, flags['remote-token']);
     if (!remote)
         return;
-    const token = process.env.ABX_RESOLVER_ADMIN_TOKEN;
-    if (!token) {
-        console.log(dim(`  (--remote: set ABX_RESOLVER_ADMIN_TOKEN in .env to nudge ${remote}; skipped — it will serve stale state until it re-indexes)`));
+    if (!remote.token) {
+        console.log(dim(`  (--remote: set ${remote.tokenVar} in .env to nudge ${remote.url}; skipped — it will serve stale state until it re-indexes)`));
         return;
     }
     try {
-        const r = await remoteAddProject(remote, token, { address }); // no fromBlock ⇒ incremental nudge
-        console.log(`  ${green('✓')} nudged hosted resolver ${dim(remote)}: ${r.project.eventCount} events (${r.mode}) — its effect runner picks up the change`);
+        // no fromBlock ⇒ incremental nudge
+        const r = await serviceClient(remote).registerProject({ chainId: chainId(), address });
+        // A deferred nudge (202) is NOT waited on here: the signed tx has already landed, and blocking a
+        // completed owner-op behind someone else's backfill would be the wrong trade. Say where it got to.
+        if (isAccepted(r)) {
+            console.log(`  ${green('✓')} nudged remote resolver ${dim(remote.url)}: ${r.project.status} — it will pick up the change (check: abx status ${address} --remote ${flags.remote})`);
+        }
+        else {
+            console.log(`  ${green('✓')} nudged remote resolver ${dim(remote.url)}: ${r.project.eventCount} events (${r.mode}) — its effect runner picks up the change`);
+        }
     }
     catch (e) {
-        console.log(dim(`  (couldn't nudge ${remote}: ${e.message} — run \`abx index ${address} --remote ${remote}\` to refresh it)`));
+        console.log(dim(`  (couldn't nudge ${remote.url}: ${e.message} — run \`abx index ${address} --remote ${flags.remote}\` to refresh it)`));
     }
 }
 async function read(address, functionName, args = []) {
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    try {
-        return (await publicClient.readContract({
-            address,
-            abi: oneOfOneImageAbi,
-            functionName: functionName,
-            args: args,
-        }));
-    }
-    catch (err) {
-        // A read that "returned no data" is usually not a real revert but an address with NO CONTRACT —
-        // previewing before deploy, a typo'd address, or the wrong chain. Every owner-op reads the
-        // owner/ownerOf here FIRST, so this one guard turns the opaque viem error into an actionable one
-        // across all of them. Only runs on the error path (zero cost when the contract exists).
-        await assertContractExists(address);
-        throw err; // the contract DOES exist → surface the original error (a genuine revert)
-    }
+    const result = await tryReadContract(publicClient, { address, abi: oneOfOneImageAbi, functionName, args });
+    if (result !== undefined)
+        return result;
+    // A read that "returned no data" is usually not a real revert but an address with NO CONTRACT —
+    // previewing before deploy, a typo'd address, or the wrong chain. Every owner-op reads the
+    // owner/ownerOf here FIRST, so this one guard turns the opaque viem error into an actionable one
+    // across all of them. Only runs on the error path (zero cost when the contract exists).
+    await assertContractExists(address);
+    // The contract DOES exist → a genuine revert. tryReadContract already swallowed that error, so
+    // re-read once (uncaught) to surface it rather than a generic "read failed".
+    return (await publicClient.readContract({
+        address,
+        abi: oneOfOneImageAbi,
+        functionName: functionName,
+        args: args,
+    }));
 }
 /** Throw a clear, actionable error when `address` has no contract on the active chain — the common
  *  cause of an owner-op's raw `returned no data ("0x")`. No-op when code is present or unknowable. */
@@ -192,7 +185,8 @@ export async function assertContractExists(address) {
     if (!code || code === '0x') {
         throw new Error(`no contract at ${address} on ${CHAIN} — nothing to operate on. Owner ops run AFTER deploy: ` +
             `deploy it first (e.g. abx deploy / deploy-series / deploy-code), or check the address and that ` +
-            `ABX_CHAIN='${CHAIN}' is the right network (a wrong-chain address reads as empty).`);
+            `ABX_CHAIN='${CHAIN}' is the right network — we asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}, and a ` +
+            `wrong-network endpoint reads as empty even when the address is right.`);
     }
 }
 // ── configure-param ──────────────────────────────────────────────────────────
@@ -209,18 +203,35 @@ export async function assertContractExists(address) {
  *  (mirrors parseFlags). `rest.filter(r => !r.startsWith('--'))` was NOT enough: a flag's VALUE
  *  (e.g. the URL after `--remote`, or the path after `--file`) isn't `--`-prefixed, so it leaked
  *  into the positional value (`configure-param … #ff0000 --remote http://h` → value "#ff0000 http://h"). */
-function positionalArgs(args) {
-    const out = [];
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a.startsWith('--')) {
-            if (a.indexOf('=') === -1 && args[i + 1] && !args[i + 1].startsWith('--'))
-                i++; // this flag consumes the next token
-            continue;
+/**
+ * Encode a command-line value for a payload-typed param (`String` / `Bytes`).
+ *
+ * `String` is UTF-8 text — the literal characters are the value, which is what a user means.
+ *
+ * `Bytes` is NOT text, and the old code UTF-8'd whatever string it was handed. A tester passed
+ * base64 (the encoding the params docs mention — which describes the *canonical decode* a program
+ * receives, not what you type here), and 128 packed bytes were stored as 172 bytes of base64 ASCII.
+ * Nothing errored; the in-chain renderer read ASCII where it expected bytes and drew garbage. So a
+ * `Bytes` value must state its encoding: `0x…` hex, or `--file` for real binary. A bare string is
+ * refused rather than guessed at — there is no safe guess between "these characters" and "these
+ * bytes", and the failure is invisible until an artwork renders wrong.
+ */
+export function encodePayloadParam(typeName, valueInput, key) {
+    if (typeName === 'String')
+        return toHexSdk(new TextEncoder().encode(valueInput));
+    const v = valueInput.trim();
+    if (/^0x[0-9a-fA-F]*$/.test(v)) {
+        if (v.length % 2 !== 0) {
+            throw new Error(`--${key} hex value has an odd number of digits (${v.length - 2}) — a byte is two hex digits.`);
         }
-        out.push(a);
-    }
-    return out;
+        return v;
+    }
+    throw new Error(`"${key}" is a Bytes param, so its value must say what its bytes ARE — this looks like text.\n` +
+        `  Pass 0x-prefixed hex:   abx configure-param <addr> <id> ${key} 0x00112233…\n` +
+        `  Or the bytes in a file: abx configure-param <addr> <id> ${key} --file ./payload.bin\n` +
+        `  (Base64 is how a Bytes param is DECODED for your program — not how you write it here. ` +
+        `Storing base64 text would put ASCII on-chain where a renderer expects bytes, silently. ` +
+        `To store these literal characters on purpose, declare the key as String instead.)`);
 }
 export async function cmdConfigureParam(address, rest, flags) {
     const usage = 'abx configure-param <address> <tokenId|-> <key> <value> [--file <path>] [--remote [url]] [--sign|--unsigned]   (tokenId "-" = contract scope, schema-less keys only)';
@@ -229,7 +240,8 @@ export async function cmdConfigureParam(address, rest, flags) {
     const valueInput = valueParts.join(' ');
     if (!tokenIdRaw || !key || (!valueInput && !flags.file)) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const schema = (await publicClient.readContract({
@@ -240,8 +252,9 @@ export async function cmdConfigureParam(address, rest, flags) {
     }));
     const [exists, paramTypeIdx, , , , , , selectOptions] = schema;
     // Contract scope (`-`): the raw owner setters (`setContractParam[Data]`) — the write path of
-    // well-known contract params like `params.keys` / `display.gateway`. Schema-less keys only: a
-    // schema'd key closes the raw path on-chain (`SchemaGoverned`) and is per-token by design.
+    // well-known contract params like `display.gateway`. Schema-less keys only: a schema'd key closes
+    // the raw path on-chain (`SchemaGoverned`) and is per-token by design. No key is special here: a
+    // contract param is enumerated on-chain like any other and lands in tokenData for every token.
     if (tokenIdRaw === '-') {
         if (exists) {
             throw new Error(`"${key}" is schema-governed — it's a per-token PostParam (abx configure-param ${contract} <tokenId> ${key} …). ` +
@@ -254,9 +267,9 @@ export async function cmdConfigureParam(address, rest, flags) {
             await runWrite(contract, prepareSetContractParamData({ contract, key, data, chainId: cid }), flags, owner);
             return;
         }
-        // Same encoding rule as deploy-code's params.keys leg: printable ASCII ≤ 31 chars rides as a
-        // literal readable bytes32; anything longer takes the data path (one blob, hash evented).
-        if (paramsKeysIsLiteral(valueInput)) {
+        // Printable ASCII ≤ 31 chars rides as a literal readable bytes32; anything longer takes the
+        // data path (one blob, hash evented).
+        if (fitsLiteralBytes32(valueInput)) {
             console.log(`  ${key} (contract scope) ← "${valueInput}"  ${dim('(literal bytes32; owner-only raw setter)')}`);
             await runWrite(contract, prepareSetContractParam({ contract, key, value: encodeTagSdk(valueInput), display: valueInput, chainId: cid }), flags, owner);
         }
@@ -268,16 +281,21 @@ export async function cmdConfigureParam(address, rest, flags) {
     }
     const tokenId = BigInt(tokenIdRaw);
     if (!exists) {
-        throw new Error(`no PostParam schema for "${key}" on ${contract}. Schemas are declared at DEPLOY: ` +
-            `abx deploy-code … --schema ${key}:<Type>:<Auth>  (e.g. ${key}:HexColor:TokenOwner). ` +
-            `Adding a param to an already-deployed contract isn't a CLI command yet.`);
+        throw new Error(`no PostParam schema for "${key}" on ${contract}. Declare one — at deploy with ` +
+            `abx deploy-code … --schema ${key}:<Type>:<Auth>, or right now on the live contract with ` +
+            `abx set-schema ${contract} --schema ${key}:<Type>:<Auth>  (e.g. ${key}:HexColor:TokenOwner).`);
     }
     const typeName = ['Bool', 'Select', 'Uint256Range', 'Int256Range', 'DecimalRange', 'HexColor', 'Timestamp', 'String', 'Bytes'][paramTypeIdx];
     let sent;
     if (typeName === 'String' || typeName === 'Bytes') {
         const data = flags.file
             ? toHexSdk(new Uint8Array(readFileSync(flags.file)))
-            : toHexSdk(new TextEncoder().encode(valueInput));
+            : encodePayloadParam(typeName, valueInput, key);
+        const bytes = (data.length - 2) / 2;
+        // Echo the DECODED byte count. The old code echoed the string's length, which is precisely how a
+        // wrong encoding announced itself and was missed: 128 packed bytes passed as base64 printed
+        // "172 bytes".
+        console.log(`  ${key} (${typeName}) ← ${bytes} bytes  ${dim(flags.file ? '(file contents, verbatim)' : typeName === 'Bytes' ? '(decoded from hex)' : '(UTF-8 text)')}`);
         sent = await runWrite(contract, prepareConfigureTokenParamData({ contract, tokenId, key, data, chainId: chainId() }), flags);
     }
     else {
@@ -285,22 +303,7 @@ export async function cmdConfigureParam(address, rest, flags) {
         console.log(`  ${key} (${typeName}) ← ${display}  ${dim('(canonical encode; the chain enforces schema + auth)')}`);
         sent = await runWrite(contract, prepareConfigureTokenParam({ contract, tokenId, key, value, display, chainId: chainId() }), flags);
     }
-    // params.keys drift nudge (best-effort, never fails the command): a project on the on-chain
-    // URI lane enumerates its param surface in the `params.keys` contract param — the canonical
-    // generator reads it to build on-chain tokenData. A configured key that isn't listed is
-    // silently OMITTED there (byte-parity with the resolver breaks), so say it, with the fix.
     if (sent) {
-        try {
-            const csv = await readParamsKeys(publicClient, contract);
-            const fixed = paramsKeysNudge(csv, key);
-            if (fixed !== null) {
-                console.log(`  ${yellow('⚠')} params.keys doesn't list "${key}" — the on-chain generator's tokenData will omit it. Fix:\n` +
-                    `    ${bold(`abx configure-param ${contract} - params.keys ${fixed}`)}`);
-            }
-        }
-        catch {
-            /* nudge is advisory — an RPC hiccup or a non-Params contract must never fail the write */
-        }
         // What happens to the IMAGE depends on how it's produced. If the `image` field is computed
         // on-chain (a `renderer` representation — the in-chain SVG lane), it re-tints AUTOMATICALLY: the
         // renderer reads the param live, so tokenURI's image is already updated, nothing to re-render.
@@ -373,8 +376,12 @@ export async function cmdSetParamHooks(address, flags) {
     }
     catch (err) {
         await assertContractExists(contract); // no contract at all → the actionable no-contract error
-        throw new Error(`${contract} exposes no param hooks — the configure/augment/transfer hooks are a SeriesCode ` +
-            `(PostParams) feature. A 1/1 or a plain Series has no configurable params to hook.`);
+        // Name the ACTUAL kind rather than assuming 721 — a 1/1-edition or EditionImage has no param
+        // hooks either (only EditionCode composes ConfigurableParams, mirroring SeriesCode), so the old
+        // blanket "a 1/1 or a plain Series" message misnamed an edition target's real kind.
+        const kind = await detectTokenKind(publicClient, contract);
+        throw new Error(`${contract} exposes no param hooks — the configure/augment/transfer hooks are a SeriesCode/EditionCode ` +
+            `(PostParams) feature. ${kind.label} has no configurable params to hook.`);
     }
     const cur = { configure: current[0], augment: current[1], transfer: current[2] };
     const label = (a) => (eqAddr(a, zeroAddress) ? dim('none') : a);
@@ -421,7 +428,8 @@ export async function cmdSetDependency(address, rest, flags) {
     const [indexRaw, refRaw] = positionalArgs(rest);
     if (indexRaw === undefined || !refRaw) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (!/^\d+$/.test(indexRaw))
         throw new Error(`<index> must be a non-negative integer (got '${indexRaw}') — the list is dense: index ≤ dependencyCount`);
@@ -445,7 +453,8 @@ export async function cmdSetDependencyRegistry(address, rest, flags) {
     const [raw] = positionalArgs(rest);
     if (!raw) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (raw !== 'none' && !/^0x[0-9a-fA-F]{40}$/.test(raw)) {
         throw new Error(`<registry> must be an address (0x + 40 hex) or 'none' to clear; got '${raw}'`);
@@ -462,30 +471,128 @@ export async function cmdLockDependencies(address, flags) {
     console.log(dim('  note: locking the dependency set is permanent and irreversible (list AND registry pointer freeze).'));
     await runWrite(contract, prepareLockDependencies({ contract, chainId: chainId() }), flags, owner);
 }
+// ── editions: shared small parsers ────────────────────────────────────────────
+/** A non-negative-integer edition flag (`--token-id`, `--amount`, …) — the shared parse +
+ *  bound-check so every edition command that takes "an id" or "a count" rejects the same way. */
+export function parseEditionCountFlag(raw, flag) {
+    if (raw === 'true' || !/^\d+$/.test(raw.trim()))
+        throw new Error(`--${flag} must be a non-negative integer; got '${raw}'.`);
+    return BigInt(raw.trim());
+}
+/** `--token-ids <csv|range>` — the shape `ping-uri` (and any future batch-by-id command) takes: a
+ *  comma-separated list of ids and/or `lo-hi` ranges (`0-9,20,25-30`), de-duplicated and sorted. */
+export function parseTokenIdRange(raw) {
+    const ids = new Set();
+    for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+        const range = part.match(/^(\d+)-(\d+)$/);
+        if (range) {
+            const [lo, hi] = [BigInt(range[1]), BigInt(range[2])];
+            if (lo > hi)
+                throw new Error(`--token-ids: range '${part}' has lo > hi.`);
+            for (let i = lo; i <= hi; i++)
+                ids.add(i);
+        }
+        else if (/^\d+$/.test(part)) {
+            ids.add(BigInt(part));
+        }
+        else {
+            throw new Error(`--token-ids: '${part}' isn't a token id or a 'lo-hi' range.`);
+        }
+    }
+    if (!ids.size)
+        throw new Error("--token-ids needs at least one id (e.g. '0,1,2' or '0-99').");
+    return [...ids].sort((a, b) => Number(a - b));
+}
 // ── mint ─────────────────────────────────────────────────────────────────────
 // Issue a token — a deferred mint (deploy → warm resolver → mint) or a primary sale
 // (mint straight to the buyer). For a 1/1 this is the one-shot token #0. For a Series
 // it mints the next sequential token id (metadata = token id): bare (one), or `--count <n>`
 // (n in order). Owner or an authorized minter signs.
+// For an EDITION (OneOfOneEdition/EditionImage/EditionCode) this mints copies of ONE id:
+// --token-id (required unless the target is a 1/1-edition, whose id space is fixed to {0}) +
+// --amount (default 1). --count is the 721 Series primitive and is refused on an edition.
 export async function cmdMint(address, flags) {
-    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--sign|--unsigned]';
+    const usage = 'abx mint <address> [--to 0x…] [--count <n> | --token-id <id> --amount <n>] [--json] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
-    const owner = await read(contract, 'owner');
-    const to = flags.to ?? owner; // default: pre-mint to the admin
-    let tx;
-    if (flags.count !== undefined && flags.count !== 'true') {
-        const count = BigInt(flags.count);
-        console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
-        tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
-    }
-    else {
-        // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
-        // Series (next sequential token) — one path serves both.
-        console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
-        tx = prepareMint({ contract, to, chainId: chainId() });
-    }
-    await runWrite(contract, tx, flags, owner);
-    console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
+    // `--json`: the TOKEN ID is the value a program came for, and it was previously only obtainable by
+    // regex-scraping coloured prose (B19). It is read from the mint's own Transfer logs rather than by
+    // re-reading `nextTokenId` afterwards — a concurrent mint would make that answer wrong, and a
+    // number that is usually right is worse than no number.
+    return withJson(flags, async () => {
+        const publicClient = makePublicClient({ chainKey: CHAIN });
+        const kind = await detectTokenKind(publicClient, contract);
+        const owner = await read(contract, 'owner');
+        const to = flags.to ?? owner; // default: pre-mint to the admin
+        if (kind.isEdition) {
+            // `--count` is the 721 Series primitive (N sequential ids); an edition mint always names its
+            // id and an amount — there is no "next in order" to count through. Refuse, don't silently
+            // reinterpret it as something else.
+            if (flags.count !== undefined) {
+                throw new Error(`--count is a 721 Series flag (mint N tokens in order) — ${contract} is a ${kind.label} (edition). Use --token-id <id> --amount <n> instead.`);
+            }
+            // OneOfOneEdition's id space is fixed to {0}, so --token-id defaults there; EditionImage/
+            // EditionCode ids are caller-named artworks with no sensible default — require it.
+            if (kind.kind !== '1of1-edition' && flags['token-id'] === undefined) {
+                throw new Error(`--token-id is required on a ${kind.label} — its ids are caller-named artworks, not a single default. ` +
+                    `See existing ids with \`abx tokens ${contract}\`.`);
+            }
+            const tokenId = flags['token-id'] !== undefined ? parseEditionCountFlag(flags['token-id'], 'token-id') : 0n;
+            const amount = flags.amount !== undefined ? parseEditionCountFlag(flags.amount, 'amount') : 1n;
+            console.log(dim(`  minting ${amount} cop${amount === 1n ? 'y' : 'ies'} of #${tokenId} → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
+            const tx = prepareEditionMint({ contract, to, tokenId, amount, chainId: chainId() });
+            const result = await runWrite(contract, tx, flags, owner);
+            if (result)
+                console.log(`  ${green('✓')} minted ${amount} cop${amount === 1n ? 'y' : 'ies'} of ${bold('#' + tokenId)} → ${to}`);
+            console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the change.`));
+            return {
+                contract,
+                chainId: chainId(),
+                to,
+                sent: !!result,
+                txHash: result?.txHash ?? null,
+                blockNumber: result ? String(result.blockNumber) : null,
+                tokenIds: [tokenId.toString()],
+                amount: amount.toString(),
+            };
+        }
+        // 721 path (unchanged): --token-id/--amount have no meaning here — refuse rather than silently
+        // ignore (the membrane rule: enforce, don't warn).
+        if (flags['token-id'] !== undefined || flags.amount !== undefined) {
+            throw new Error(`--token-id/--amount are edition-only (ERC-1155 copies) — ${contract} is a ${kind.label} (721). ` +
+                `Mint the next token with \`abx mint ${contract}\`${kind.kind !== '1of1' ? ' (or --count N for several in order)' : ''}.`);
+        }
+        let tx;
+        let count = 1n;
+        if (flags.count !== undefined && flags.count !== 'true') {
+            count = BigInt(flags.count);
+            console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
+            tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
+        }
+        else {
+            // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
+            // Series (next sequential token) — one path serves both.
+            console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
+            tx = prepareMint({ contract, to, chainId: chainId() });
+        }
+        const result = await runWrite(contract, tx, flags, owner);
+        const tokenIds = result ? await mintedTokenIds(makePublicClient({ chainKey: CHAIN }), contract, result.txHash) : [];
+        if (result && tokenIds.length) {
+            console.log(`  ${green('✓')} minted token${tokenIds.length > 1 ? 's' : ''} ${bold(tokenIds.map((t) => '#' + t).join(', '))} → ${to}`);
+        }
+        console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
+        return {
+            contract,
+            chainId: chainId(),
+            to,
+            // `sent: false` is the dry-run and cold-lane answer — an empty tokenIds with no explanation
+            // would read as a failed mint.
+            sent: !!result,
+            txHash: result?.txHash ?? null,
+            blockNumber: result ? String(result.blockNumber) : null,
+            tokenIds,
+            requestedCount: Number(count),
+        };
+    });
 }
 // ── series owner ops (minter set · supply cap · primary payee) ────────────────
 // The multi-token knobs. All owner-only; each runs through the same signing lane +
@@ -508,6 +615,67 @@ export async function cmdSetMaxInvocations(address, flags) {
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetMaxInvocations({ contract, maxInvocations: max, chainId: chainId() }), flags, owner);
 }
+// ── set-max-supply (editions only) — the per-id twin of set-max-invocations ──────────────────────
+/**
+ * `abx set-max-supply <address> --token-id <n> --cap <n>` — owner overrides ONE id's ERC-1155
+ * supply cap (Edition Supply extension). Monotonically non-increasing once used for that id — the
+ * chain enforces it (`MaxSupplyIncreaseForbidden`/`MaxSupplyBelowFloor`), and `--cap open` is
+ * refused HERE, before any gas: the contract's own "0" means "closed forever" once an id has been
+ * overridden (not "reopen to uncapped" — `EditionSupply.sol`'s own doc calls this out), so accepting
+ * `open` as an alias for 0 would silently promise the opposite of what it does on a re-run.
+ */
+export async function cmdSetMaxSupply(address, flags) {
+    const usage = 'abx set-max-supply <address> --token-id <n> --cap <n> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (!kind.isEdition) {
+        throw new Error(`set-max-supply is edition-only (a per-id ERC-1155 cap) — ${contract} is a ${kind.label} (721). Use \`abx set-max-invocations\` instead (the whole-project cap).`);
+    }
+    const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+    const capRaw = requireFlag(flags, 'cap', usage);
+    if (capRaw.trim().toLowerCase() === 'open') {
+        throw new Error(`--cap open is refused: once you set a cap for #${tokenId} it can only DECREASE (never increase back to uncapped) — ` +
+            `"open" would ask for exactly the increase the chain forbids. If this id has never been overridden, it's already open ` +
+            `(the --copies default from deploy) — there's nothing to set. To lower an existing cap, pass the number.`);
+    }
+    const cap = parseEditionCountFlag(capRaw, 'cap');
+    const owner = await read(contract, 'owner');
+    console.log(dim(`  #${tokenId} supply cap → ${cap}`));
+    await runWrite(contract, prepareSetMaxSupply({ contract, tokenId, cap, chainId: chainId() }), flags, owner);
+}
+// ── ping-uri (editions only) — permissionless URI re-emission ────────────────────────────────────
+/** How many ids one `pingURI` call carries per transaction — large enough that a normal collection
+ *  fits in one tx, small enough that a genuinely huge id list doesn't build one unbounded call. */
+const PING_URI_CHUNK_SIZE = 200;
+/**
+ * `abx ping-uri <address> --token-ids <csv|range>` — re-emit the native ERC-1155 `URI` event for
+ * the given ids after a contract-wide re-point (`set-token-uri`/`set-renderer`), so marketplaces/
+ * indexers that only honor the native event re-index. Permissionless (anyone may call it — it only
+ * re-emits already-public, current truth), so there is no owner check and no `expectedSigner` to
+ * pin; whichever signer the active lane resolves sends it. Chunks a large id list into several
+ * transactions, each through the SAME `--dry-run`/`--confirm` gate as any other write.
+ */
+export async function cmdPingUri(address, flags) {
+    const usage = 'abx ping-uri <address> --token-ids <csv|range> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (!kind.isEdition) {
+        throw new Error(`ping-uri is edition-only — it re-emits the ERC-1155 URI event, which a ${kind.label} (721) doesn't have ` +
+            `(721 emits ERC-4906 MetadataUpdate automatically on a URI change — nothing to re-emit by hand).`);
+    }
+    const ids = parseTokenIdRange(requireFlag(flags, 'token-ids', usage));
+    const chunks = [];
+    for (let i = 0; i < ids.length; i += PING_URI_CHUNK_SIZE)
+        chunks.push(ids.slice(i, i + PING_URI_CHUNK_SIZE));
+    console.log(dim(`  re-emitting URI for ${ids.length} id${ids.length === 1 ? '' : 's'} — permissionless (no owner check) — ${chunks.length} tx${chunks.length === 1 ? '' : '(s)'} of up to ${PING_URI_CHUNK_SIZE} id(s) each`));
+    for (const [i, chunk] of chunks.entries()) {
+        if (chunks.length > 1)
+            console.log(dim(`  chunk ${i + 1}/${chunks.length}: ${chunk.length} id(s) (#${chunk[0]}–#${chunk[chunk.length - 1]})`));
+        await runWrite(contract, preparePingURI({ contract, tokenIds: chunk, chainId: chainId() }), flags);
+    }
+}
 /** Pause minting — restrict it to the owner (config/reserves) until unpaused. */
 export async function cmdPause(address, flags) {
     const contract = requireAddress(address, 'abx pause <address> [--sign|--unsigned]');
@@ -551,15 +719,29 @@ export async function cmdSetPrimaryPayee(address, flags) {
 // marketplaces fetch the on-chain tokenURI; if the resolver wasn't warm they cache
 // a miss until refreshed. We emit ERC-4906 on URI changes (4906-aware marketplaces
 // auto-refresh) — this is the manual fallback for the rest, and after the genesis mint.
-const OPENSEA_CHAIN = { sepolia: 'sepolia', mainnet: 'ethereum' };
-const TESTNET_CHAINS = new Set(['sepolia']);
+/**
+ * OpenSea's own chain slugs, keyed by ours. They are NOT our keys (`base-sepolia` is `base_sepolia`
+ * there) and not derivable from viem, so the map is unavoidable — but a chain missing from it must
+ * produce NO link rather than a wrong one, which is what `osChain ?? CHAIN` used to do.
+ *
+ * It previously listed only `sepolia` and `mainnet`, so the CLI's own DEFAULT chain (`base-sepolia`)
+ * fell through to the raw key: the refresh POST went to `/chain/base-sepolia/…` (a slug OpenSea does
+ * not know) and the printed link pointed at **mainnet** `opensea.io` for a testnet token. Same shape
+ * as the hardcoded explorer table that once sent every Base Sepolia link to Etherscan — hence
+ * `testnet` now comes from the chain registry instead of a second hand-maintained set.
+ */
+const OPENSEA_CHAIN = { 'base-sepolia': 'base_sepolia', sepolia: 'sepolia' };
 export async function cmdRefresh(address, flags) {
     const contract = requireAddress(address, 'abx refresh <address> [--token 0]');
     const tokenId = flags.token ?? '0';
-    const osChain = OPENSEA_CHAIN[CHAIN] ?? CHAIN;
-    const explorer = resolveChain(CHAIN).blockExplorers?.default?.url ?? '';
+    const chain = resolveChain(CHAIN);
+    const osChain = OPENSEA_CHAIN[CHAIN];
+    const explorer = chain.blockExplorers?.default?.url ?? '';
     const apiKey = process.env.OPENSEA_API_KEY;
-    if (apiKey) {
+    if (!osChain) {
+        console.log(dim(`  no OpenSea slug known for '${CHAIN}' — skipping the OpenSea refresh (a guessed slug 404s, and a guessed link would point at the wrong network).`));
+    }
+    else if (apiKey) {
         const url = `https://api.opensea.io/api/v2/chain/${osChain}/contract/${contract}/nfts/${tokenId}/refresh`;
         try {
             const res = await fetch(url, { method: 'POST', headers: { 'x-api-key': apiKey, accept: 'application/json' } });
@@ -575,17 +757,43 @@ export async function cmdRefresh(address, flags) {
     else {
         console.log(dim('  no OPENSEA_API_KEY set — open these and click “Refresh metadata”:'));
     }
-    const osBase = TESTNET_CHAINS.has(CHAIN) ? 'https://testnets.opensea.io' : 'https://opensea.io';
-    console.log(`    ${dim('OpenSea  ')}${osBase}/assets/${osChain}/${contract}/${tokenId}`);
+    // `testnet` from the chain registry (viem), never a local set — that is the drift this bug was.
+    const osBase = chain.testnet ? 'https://testnets.opensea.io' : 'https://opensea.io';
+    if (osChain)
+        console.log(`    ${dim('OpenSea  ')}${osBase}/assets/${osChain}/${contract}/${tokenId}`);
     if (explorer)
         console.log(`    ${dim('Etherscan')} ${explorer}/token/${contract}?a=${tokenId}`);
     console.log(dim('  (ERC-4906 already pings 4906-aware marketplaces on URI changes; this covers the genesis mint + the rest.)'));
 }
 // ── transfer ─────────────────────────────────────────────────────────────────
 export async function cmdTransfer(address, flags) {
-    const contract = requireAddress(address, 'abx transfer <address> --to 0x… [--token 0] [--sign|--unsigned]');
-    const to = requireFlag(flags, 'to', 'abx transfer <address> --to 0x…');
+    const usage = 'abx transfer <address> --to 0x… [--token 0] [--amount <n> --from 0x… (editions only)] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const to = requireFlag(flags, 'to', usage);
     const tokenId = BigInt(flags.token ?? '0');
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (kind.isEdition) {
+        const amount = flags.amount !== undefined ? parseEditionCountFlag(flags.amount, 'amount') : 1n;
+        // Unlike a 721 (one holder, read on-chain via ownerOf), an edition id can have MANY concurrent
+        // holders — there is no single "the owner" to move copies from, so the holder must be named.
+        const fromRaw = flags.from;
+        if (!fromRaw || fromRaw === 'true') {
+            throw new Error(`--from 0x.. is required on a ${kind.label} — an edition id can have many concurrent holders, so ` +
+                `there is no single current owner to read on-chain (unlike a 721). Pass the holder's address.`);
+        }
+        if (!isAddress(fromRaw))
+            throw new Error(`--from must be a 0x address; got '${fromRaw}'.`);
+        const from = getAddress(fromRaw);
+        const tx = prepareEditionTransfer({ contract, from, to, tokenId, amount, chainId: chainId() });
+        await runWrite(contract, tx, flags, from);
+        return;
+    }
+    // 721 path (unchanged): --amount has no meaning — a token transfers as a whole. Refuse rather
+    // than silently ignore.
+    if (flags.amount !== undefined) {
+        throw new Error(`--amount is edition-only (ERC-1155 copies) — ${contract} is a ${kind.label} (721), where a token transfers as a whole. Drop --amount.`);
+    }
     const from = await read(contract, 'ownerOf', [tokenId]);
     const tx = prepareTransfer({ contract, from, to, tokenId, chainId: chainId() });
     await runWrite(contract, tx, flags, from);
@@ -648,126 +856,195 @@ export async function cmdSetRoyalty(address, flags) {
     }
     await runWrite(contract, prepareSetRoyalty({ contract, receiver, bps, chainId: chainId() }), flags, owner);
 }
+// ── ERC-721C (creator token) — the transfer-validator surface ─────────────────
+// Enrollment is a DEPLOY-TIME decision (`--721c` on the deploy commands) and permanent in both
+// directions: an unenrolled token can never gain a validator, an enrolled one never sheds the
+// standard. Within an enrolled token the owner re-points or suspends (zero) the validator freely.
+/** The chain keys the manifest recommends a transfer validator for — for refusal messages. */
+function chainsWithRecommendedValidator() {
+    const ids = new Set(Object.keys(RECOMMENDED_TRANSFER_VALIDATOR).map(Number));
+    return KNOWN_CHAIN_KEYS.filter((k) => ids.has(resolveChain(k).id)).join(', ');
+}
+/**
+ * Parse a transfer-validator choice — the shared grammar of the deploy flag (`--721c`) and the
+ * owner op (`abx set-transfer-validator`):
+ *   - `recommended` (or a bare `--721c`) → the per-chain recommended validator, refusing on a
+ *     chain the manifest has no entry for (naming the chains that do — never guess one);
+ *   - a `0x…` address → checksum-validated (EIP-55) and returned as its canonical form;
+ *   - `none`/zero → `allowNone` decides: the owner op suspends with it; the DEPLOY flag refuses
+ *     it (a zero validator at deploy never enrolls — that is already the default, so someone
+ *     passing it either wants plain ERC-721 (drop the flag) or mistakenly believes "enrolled but
+ *     suspended" is a deploy-time state — it isn't).
+ * Pure (no RPC) — callers do the has-code precheck themselves. Exported for the regression test.
+ */
+export function parseTransferValidatorValue(raw, opts) {
+    const s = raw.trim().toLowerCase();
+    if (s === 'true' || s === '' || s === 'recommended') {
+        const rec = resolveRecommendedTransferValidator(opts.chainId);
+        if (!rec) {
+            throw new Error(`no recommended transfer validator is known for '${opts.chainLabel}' (chainId ${opts.chainId}) — ` +
+                `chains with one: ${chainsWithRecommendedValidator() || '(none shipped)'}. ` +
+                `Pass an explicit validator address instead (it must be a deployed contract on this chain).`);
+        }
+        return rec;
+    }
+    if (s === 'none' || s === 'zero' || s === '0' || s === '0x0' || s === zeroAddress) {
+        if (opts.allowNone)
+            return zeroAddress;
+        throw new Error(`a zero transfer validator never enrolls — a plain (unenrolled) token is already the default, so drop --721c. ` +
+            `("enrolled but suspended" is not a deploy-time state: enroll with a real validator, then suspend ` +
+            `with \`abx set-transfer-validator <address> none\`.)`);
+    }
+    const trimmed = raw.trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new Error(`transfer validator must be 'recommended'${opts.allowNone ? ", 'none'," : ''} or a 0x address (0x + 40 hex); got '${raw}'`);
+    }
+    // `isAddress` strict-validates the EIP-55 checksum of a mixed-case address (all-lowercase carries
+    // no checksum and passes); `getAddress` alone only NORMALIZES — it would silently accept a
+    // mis-cased paste, which is exactly the transposition this check exists to catch.
+    if (!isAddress(trimmed, { strict: true })) {
+        throw new Error(`transfer validator address failed its EIP-55 checksum: '${raw}' — paste it exactly (or all-lowercase).`);
+    }
+    return getAddress(trimmed);
+}
+/**
+ * `abx set-transfer-validator <address> <0x…|none|recommended>` — re-point an ENROLLED (ERC-721C)
+ * collection's transfer validator, or suspend enforcement with `none` (address(0); the token
+ * STAYS enrolled). Refuses up front, before any signing: a plain ERC-721 (enrollment is
+ * deploy-time-only — the contract would revert `NotCreatorToken()`), and a codeless validator
+ * (would revert `InvalidTransferValidator()`). Owner-only, any lane, guards `--dry-run`.
+ */
+export async function cmdSetTransferValidator(address, rest, flags) {
+    const usage = 'abx set-transfer-validator <address> <0x…|none|recommended> [--sign|--unsigned] [--dry-run]';
+    const contract = requireAddress(address, usage);
+    const [raw] = positionalArgs(rest);
+    if (!raw) {
+        console.error(`usage: ${usage}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const cid = chainId();
+    const validator = parseTransferValidatorValue(raw, { chainId: cid, chainLabel: CHAIN, allowNone: true });
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    // Enrollment guard FIRST — a read, not a send. An unenrolled token would revert
+    // `NotCreatorToken()`; refuse with the real story instead of letting the chain say it in hex.
+    // (readCreatorTokenStatus is defensive, so check the contract exists first — a typo'd address
+    // must not read as "plain ERC-721".)
+    await assertContractExists(contract);
+    const status = await readCreatorTokenStatus(publicClient, contract);
+    if (!status.enrolled) {
+        throw new Error(`${contract} did not enroll as a creator token — 721C/1155C enrollment is a deploy-time decision. ` +
+            `Enrollment can never be added to a live collection; if enforcement is required, redeploy with ` +
+            `--721c recommended (or --721c 0x…) on the deploy command.`);
+    }
+    // Codeless-validator guard: the contract refuses a non-zero validator with no code
+    // (`InvalidTransferValidator()`) — surface it before gas is spent.
+    if (validator !== zeroAddress) {
+        let code;
+        try {
+            code = await publicClient.getCode({ address: validator });
+        }
+        catch (err) {
+            throw new Error(`couldn't verify the validator has code at ${validator} (${err.message}) — refusing to re-point blind; retry when the RPC answers.`);
+        }
+        if (!code || code === '0x') {
+            const rec = resolveRecommendedTransferValidator(cid);
+            throw new Error(`no contract code at ${validator} on ${CHAIN} — the token would revert InvalidTransferValidator(). ` +
+                `A transfer validator must be a DEPLOYED contract on this chain` +
+                (rec ? ` (the recommended one: \`abx set-transfer-validator ${contract} recommended\` → ${rec})` : '') + `.`);
+        }
+    }
+    if (eqAddr(status.validator, validator)) {
+        console.log(dim(`  no change — the validator is already ${validator === zeroAddress ? 'suspended (0x0)' : validator}. Nothing sent.`));
+        return;
+    }
+    const label = (a) => (eqAddr(a, zeroAddress) ? 'suspended (0x0)' : a);
+    console.log(dim(`  transfer validator: ${label(status.validator)} → ${label(validator)}${validator === zeroAddress ? '  — transfers go unvalidated until one is set again (the token stays enrolled)' : ''}`));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetTransferValidator({ contract, validator, chainId: cid }), flags, owner);
+}
+// ── multi-chunk on-chain content (the `reader` path) ─────────────────────────
+// The plan math (chunk count + tx shape), the cost-model constants, and the actual
+// plan→resolve-store→stage→encode orchestration all live in the SDK's staging.ts, layered on
+// planChunks/planContentTxs/stageContent/encodeReader/ensureChunkStore — see its module doc. What
+// stays here is Node-only (reading the file, gzip) plus the narration: every console.log below is
+// this file's onEvent handler for the SDK's `StagingEvent`, so the lines are unchanged from before
+// the move.
 export function parseCompress(v) {
     const c = (v ?? 'none').toLowerCase();
     if (c === 'none' || c === 'fastlz' || c === 'gzip')
         return c;
     throw new Error(`--compress must be none | fastlz | gzip (got '${v}')`);
 }
+/** The chunk-store bootstrap narration shared by every content-staging path below — one place so
+ *  the lines are identical whether the store is resolved for a single field ({@link putContentOnChain}
+ *  → the SDK's `stageFieldContent`) or once up front for a whole batch ({@link ensureChunkStore}). */
+function printChunkStoreEvent(e) {
+    if (e.kind === 'stale')
+        console.log(yellow(`  configured chunk store ${e.address} is a stale deployment (no writeContent) — deploying a current one`));
+    else if (e.kind === 'canonical')
+        console.log(dim(`  using the canonical chunk store at its deterministic address ${e.address}`));
+    else if (e.kind === 'deploying')
+        console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
+    else {
+        console.log(`  ${green('✓')} chunk store ${e.address}`);
+        console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${e.address} (or add it to packages/sdk/src/deployments.ts)`));
+    }
+}
 /**
  * The chain's shared multi-chunk store/reader; deploy it once if missing, signing through
  * `send` (the env key on the hot lane, or the connected wallet on the wallet lane) — the
- * store is ownerless, so any funded signer can stand it up.
+ * store is ownerless, so any funded signer can stand it up. Used directly only by
+ * {@link stageImageFieldsBatch} (resolving ONE store up front for every token); a single-field
+ * stage ({@link putContentOnChain}) resolves its store through the SDK's `stageFieldContent`
+ * instead, which calls the very same SDK `ensureChunkStore` internally.
  */
 async function ensureChunkStore(send, override) {
-    // Resolve from the shipped manifest (flag → ABX_CHUNK_STORE → manifest); on a chain with no
-    // entry (or a stale deployment), deploy a current one and tell the operator how to reuse it.
-    const known = chunkStoreAddress(override);
+    // The resolution logic lives in the SDK (`ensureChunkStore`) so an SDK integrator bootstraps
+    // identically instead of hand-rolling the "is this store capable?" guard — forget it and an
+    // incapable store fails deep inside a mint, after transactions have landed. The CLI keeps only the
+    // narration: the SDK reports progress through `onEvent` rather than printing.
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    if (known) {
-        const code = await publicClient.getCode({ address: known });
-        if (code && code !== '0x') {
-            // Has code, but is it the *current* store? A pre-`writeContent` deployment passes a
-            // bare code check yet reverts the staging call — verify the ABI, don't just assume.
-            if (await storeSupportsWriteContent(publicClient, known))
-                return known;
-            console.log(yellow(`  configured chunk store ${known} is a stale deployment (no writeContent) — deploying a current one`));
-        }
-    }
-    // No usable listed store. The canonical store is CREATE2-deterministic, so it may already exist at
-    // its predicted address — deployed by the forge script (or a prior lazy deploy) with the manifest
-    // not yet updated. Check there before deploying: self-healing, and never a duplicate at a random
-    // CREATE address. `deployChunkStore` (below) also lands at exactly this address.
-    const predicted = predictChunkStore();
-    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
-        const pcode = await publicClient.getCode({ address: predicted });
-        if (pcode && pcode !== '0x' && (await storeSupportsWriteContent(publicClient, predicted))) {
-            console.log(dim(`  using the canonical chunk store at its deterministic address ${predicted}`));
-            return predicted;
-        }
-    }
-    console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
-    const { chunkStore } = await deployChunkStore(send);
-    console.log(`  ${green('✓')} chunk store ${chunkStore}`);
-    console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${chunkStore} (or add it to packages/sdk/src/deployments.ts)`));
-    return chunkStore;
+    return sdkEnsureChunkStore(publicClient, send, { chainId: chainId(), override, onEvent: printChunkStoreEvent });
 }
 /**
- * The hot-lane staging signer: the env key signs + broadcasts each chunk-store write. Built
- * lazily so commands that never stage on-chain don't require a key. The wallet lane passes a
- * session-backed sender instead (see {@link openWalletSession}); the cold lane can't stage
- * interactively, so it's rejected up front by the deploy/set-field commands.
+ * The hot-lane staging signer: the env key signs + broadcasts each chunk-store write, via the
+ * SDK's `makeHotSender` (pinned nonce, pinned gas, typed revert). Built lazily so commands that
+ * never stage on-chain don't require a key. The wallet lane passes a session-backed sender
+ * instead (see {@link openWalletSession}); the cold lane can't stage interactively, so it's
+ * rejected up front by the deploy/set-field commands.
  */
 export function envStagingSender() {
     const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    return async (tx) => {
-        const hash = await wallet.sendTransaction({
-            account,
-            chain: wallet.chain,
-            to: tx.to ?? undefined,
-            data: tx.data,
-            value: 0n,
-        });
-        return publicClient.waitForTransactionReceipt({ hash });
-    };
+    return makeHotSender({ wallet, account, publicClient });
 }
 /** Wallet-lane staging signer: each chunk-store write is approved in the human's browser
- *  wallet through the open {@link WalletSession}, sharing one connection with the final tx. */
+ *  wallet through the open {@link WalletSession}, sharing one connection with the final tx. A
+ *  {@link PreparedTx} already carries everything `session.send` needs, so this is a thin adapter. */
 export function sessionStagingSender(session) {
-    const id = chainId();
-    return async (tx) => (await session.send({
-        op: 'stage',
-        to: tx.to,
-        data: tx.data,
-        value: '0x0',
-        chainId: id,
-        summary: tx.summary,
-        fields: tx.fields,
-    })).receipt;
+    return async (tx) => (await session.send(tx)).receipt;
 }
-/**
- * Put `content` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
- * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
- * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
- * `reader-gzip` representation, not on-chain renderable).
- *
- * Staging is one atomic `writeContent` when the content fits a single tx's gas, else
- * gas-bounded chunk-write `multicall`s plus a final manifest write — {@link stageContent}
- * picks, and we print the tx plan up front so the human knows the count before signing.
- * These store writes use the env key (the data contracts are ownerless); the owner only
- * signs the field set that references the manifest.
- */
-/**
- * Pure staging plan for a piece of content — chunk count + transaction shape — with NO
- * chain writes, no signer, no `ensureChunkStore`. Shared by {@link putContentOnChain}
- * (which then actually stages) and the deploy dry-run preview, so the count the human is
- * told up front is the same one the real staging will produce. `chunkSize` defaults to the
- * SDK's {@link planChunks} default (currently 22 KB), so e.g. a 2.8 KB SVG is 1 chunk.
- */
-// On-chain image storage costs ~200 gas/byte (SSTORE2 code deposit) + per-chunk tx overhead, so it
-// is cost-effective ONLY for tiny art. Past these soft limits, off-chain (Arweave pay-once, or a
-// hosted resolver + IPFS) is FAR cheaper — on-chain's remaining edge is self-resolution, not cost.
-// Per-file limit ≈ one 22 KB storage chunk; project limit caps the whole collection's gas.
-export const ONCHAIN_IMAGE_SOFT_LIMIT = 24 * 1024; // per file
-export const ONCHAIN_PROJECT_SOFT_LIMIT = 256 * 1024; // whole collection
 const kb = (n) => `${n < 10 * 1024 ? (n / 1024).toFixed(1) : Math.round(n / 1024)}KB`;
 /** Warn (loudly) when content is too big for on-chain to be the cost-sane choice. Returns true if it warned. */
 export function warnIfLargeForOnChain(bytesLen, label) {
-    if (bytesLen <= ONCHAIN_IMAGE_SOFT_LIMIT)
+    if (!exceedsOnchainSoftLimit(bytesLen))
         return false;
     console.log(yellow(`  ⚠ ${label} is ${kb(bytesLen)} — large for ON-CHAIN storage (~200 gas/byte). Past ~${kb(ONCHAIN_IMAGE_SOFT_LIMIT)}/file, on-chain is FAR more expensive than off-chain, not cheaper.`));
     console.log(dim(`    For art this size prefer off-chain: --backend arweave (pay-once, permanent) or a hosted resolver + IPFS. Use on-chain only if self-resolution is a hard requirement.`));
     return true;
 }
+/**
+ * Pure staging plan for a piece of content — chunk count + transaction shape — with NO chain
+ * writes, no signer, no `ensureChunkStore`. The CLI-facing wrapper over the SDK's pure
+ * {@link planStagedContent}: `gzip` is a Node-only transform, so it happens here (not in the SDK —
+ * see staging.ts's module doc) before handing the result off to the SDK's chunk/tx-shape math.
+ * Shared by {@link putContentOnChain} (which then actually stages) and the deploy dry-run preview,
+ * so the count the human is told up front is the same one the real staging will produce.
+ */
 export function computeContentPlan(bytes, compress) {
     const content = compress === 'gzip' ? new Uint8Array(gzipSync(bytes)) : new Uint8Array(bytes);
-    const fastlz = compress === 'fastlz';
-    const planned = planChunks(content, { fastlz });
-    const plan = planContentTxs(planned);
-    const representation = compress === 'gzip' ? R.readerGzip : R.reader;
-    const stagedBytes = planned.reduce((n, c) => n + c.data.length, 0);
-    return { content, fastlz, chunks: planned.length, stagedBytes, plan, representation };
+    return planStagedContent(content, compress);
 }
 /** Human-readable size line for a content plan, e.g. `2812B → 1 chunk [fastlz 2812→904B]`. */
 function planSizeLine(bytes, p, compress) {
@@ -789,15 +1066,43 @@ function planTxLine(p, finalLabel) {
         ? `plan: 1 staging tx (atomic writeContent) + ${finalLabel} = 2 transactions`
         : `plan: ${p.plan.batches.length} chunk-batch tx(s) + 1 manifest tx + ${finalLabel} = ${p.plan.txCount + 1} transactions`;
 }
+/**
+ * Put `bytes` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
+ * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
+ * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
+ * `reader-gzip` representation, not on-chain renderable) — done here, not in the SDK's
+ * `stageFieldContent` (a Node-only transform; see staging.ts's module doc).
+ *
+ * Staging is one atomic `writeContent` when the content fits a single tx's gas, else
+ * gas-bounded chunk-write `multicall`s plus a final manifest write — the SDK picks, and we
+ * print the tx plan up front (via its `onEvent`) so the human knows the count before signing.
+ * These store writes use the env key (the data contracts are ownerless); the owner only
+ * signs the field set that references the manifest.
+ */
 async function putContentOnChain(bytes, compress, field, send, finalLabel = '1 owner field-set', store) {
-    const p = computeContentPlan(bytes, compress);
     warnIfLargeForOnChain(bytes.length, `'${field}'`);
-    const resolvedStore = store ?? (await ensureChunkStore(send));
-    console.log(dim(`  '${field}' on-chain: ${planSizeLine(bytes.length, p, compress)} via reader ${resolvedStore}`));
-    console.log(dim(`    ${planTxLine(p, finalLabel)}`));
-    const { manifest, txHashes } = await stageContent(send, { store: resolvedStore, content: p.content, fastlz: p.fastlz });
-    console.log(dim(`    staged in ${txHashes.length} tx(s); manifest → ${manifest}`));
-    return { value: encodeReader(resolvedStore, manifest), representation: p.representation };
+    const content = compress === 'gzip' ? new Uint8Array(gzipSync(bytes)) : new Uint8Array(bytes);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    return stageFieldContent({
+        content,
+        compress,
+        field,
+        send,
+        publicClient,
+        chainId: chainId(),
+        store,
+        onEvent: (e) => {
+            if (e.kind === 'chunk-store')
+                printChunkStoreEvent(e.event);
+            else if (e.kind === 'planned') {
+                console.log(dim(`  '${field}' on-chain: ${planSizeLine(bytes.length, e.contentPlan, compress)} via reader ${e.store}`));
+                console.log(dim(`    ${planTxLine(e.contentPlan, finalLabel)}`));
+            }
+            else {
+                console.log(dim(`    staged in ${e.txHashes.length} tx(s); manifest → ${e.manifest}`));
+            }
+        },
+    });
 }
 /**
  * Dry-run preview of staging an image fully on-chain — the REAL chunk + transaction plan,
@@ -845,6 +1150,55 @@ export async function stageImageFieldsBatch(imagePaths, compress, send, storeOve
     }
     return { fields, store };
 }
+// ── the generator repoint guard ───────────────────────────────────────────────
+// The canonical AbxGenerator reads a token's param surface FROM CHAIN (`tokenParamKeys` /
+// `contractParamKeys`). A LEGACY implementation — deployed before enumeration shipped — has neither
+// getter, so the generator finds nothing: every configured param vanishes from tokenData and from
+// the live view, silently, behind a tokenURI that still looks perfectly healthy. That is the exact
+// failure class this toolkit refuses rather than warns about, so pointing a legacy token at the
+// current generator is REFUSED. (Repointing the metadata RENDERER is safe and unguarded: a v4
+// renderer on a legacy token just emits no params block.)
+/** The field-renderer address a `--value` names: the canonical `abi.encode(address)` (32 bytes),
+ *  or a bare 20-byte address. Null when it is neither. */
+function fieldRendererTarget(value) {
+    const hex = value.trim();
+    if (!/^0x[0-9a-fA-F]*$/.test(hex))
+        return null;
+    if (hex.length === 42)
+        return getAddress(hex);
+    if (hex.length !== 66)
+        return null;
+    try {
+        return decodeFieldRenderer(hex);
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertGeneratorRepointable(contract, field, flags, 
+/** Injected for tests; the real probe is one eth_call. */
+probe = (c) => hasParamEnumeration(makePublicClient({ chainKey: CHAIN }), c)) {
+    if (flags.representation !== R.renderer || !flags.value || flags.value === 'true')
+        return;
+    const target = fieldRendererTarget(flags.value);
+    const generator = resolveGenerator(chainId());
+    // Only the CANONICAL generator is guarded — any other field renderer is the creator's own contract
+    // and none of our business.
+    if (!target || !generator || target.toLowerCase() !== generator.toLowerCase())
+        return;
+    // The `owner` read has already succeeded by the time this runs, so the RPC is proven reachable:
+    // a failing probe here means the getter is absent, not that the node is down.
+    if (await probe(contract))
+        return;
+    throw new Error(`refusing to point ${field} at the canonical generator ${generator} — ${contract} does not expose the param\n` +
+        `  enumeration surface (tokenParamKeys/contractParamKeys), so it is a LEGACY implementation. The current\n` +
+        `  generator reads params FROM CHAIN, so on this token it would read NOTHING: every configured param would\n` +
+        `  silently disappear from tokenData, the live view, and every render — with a tokenURI that still looks fine.\n\n` +
+        `  Two honest options:\n` +
+        `    • stay on the generator this project already uses (pass that address as --value; it reads the project's\n` +
+        `      params.keys list, which is how it has always worked here), or\n` +
+        `    • redeploy the project with the current \`abx deploy-code\` — new projects enumerate on-chain and need no list.`);
+}
 // ── set-field ──────────────────────────────────────────────────────────────--
 // Set an on-chain metadata field. `--field` is what (e.g. image, description),
 // `--representation` is how it's carried (default `inline` for --text, `keccak256`
@@ -859,10 +1213,11 @@ export async function cmdSetField(address, flags) {
     const collection = !!flags.collection;
     const lane = laneFromFlags(flags);
     const owner = await read(contract, 'owner');
+    await assertGeneratorRepointable(contract, field, flags); // legacy impl + the current generator = params silently invisible
     const staging = !!(flags.file && flags.file !== 'true'); // large content ON-CHAIN via chunk store/reader
     // --file + --dry-run: preview the on-chain staging plan and store/send NOTHING. (The locator/text
     // path flows through runWrite, which previews there; staging must short-circuit before any upload.)
-    if (staging && flags['dry-run']) {
+    if (staging && isDryRun(flags)) {
         const bytes = readFileSync(resolvePath(flags.file));
         const p = computeContentPlan(bytes, parseCompress(flags.compress));
         console.log(`\n  ${bold('◆ set-field ' + field)} ${dim('(dry run — nothing staged or sent)')}`);
@@ -938,9 +1293,25 @@ export async function cmdSetField(address, flags) {
  *   - computed keys (`artifacts`, `abx_provenance`) are refused — they're the manifest, not inputs.
  * Scope: token (`--token`, default 0) or `--collection`. Any signing lane. Owner-only.
  */
+/**
+ * Attach one or more artifacts. Several `<key> <uri>` pairs in one invocation become **one
+ * transaction**.
+ *
+ * That batching is a safety fix, not a convenience (backlog B20). The CLI's most-documented flow —
+ * mint, then attach each artifact, then refresh — sent one transaction per step with no all-or-nothing
+ * boundary, so a failure partway through left a permanently half-written token that cannot be
+ * un-minted. An integrator hit exactly this and folded 8 operations into 1 transaction using the SDK's
+ * `batchOps`, which the CLI already shipped and did not use. Now it does: N pairs are one
+ * `multicall`, so either every artifact lands or none does.
+ *
+ * A single pair passes through `batchOps` untouched, so the one-artifact case sends the identical
+ * transaction it always did.
+ */
 export async function cmdAttach(rest, flags) {
-    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…>   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
-    const [address, key, uri] = positionalArgs(rest);
+    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…> [<key> <uri> …]   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
+    const [address, ...pairArgs] = positionalArgs(rest);
+    const key = pairArgs[0];
+    const uri = pairArgs[1];
     // Warn (never throw) on an unrecognized flag — a typo or a hopeful `--mime-type` otherwise no-ops
     // INVISIBLY (round-1: an agent passed `--mime-type` and it was silently swallowed). mimeType is
     // declared from the URL extension, not a flag; say so.
@@ -955,13 +1326,15 @@ export async function cmdAttach(rest, flags) {
     const contract = requireAddress(address, usage);
     if (!key) {
         console.error(`usage: ${usage}\n  the <key> is the name your file appears under in the manifest (e.g. print, certificate, stems, readme).\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     assertSettableField(key);
     const hasFile = !!(flags.file && flags.file !== 'true');
     if (!uri && !hasFile) {
         console.error(`usage: ${usage}\n  pass a locator URI (ipfs://… / ar://… / https://…) or --file <path> to store bytes on-chain.\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (uri && hasFile)
         throw new Error('pass EITHER a locator URI OR --file <path>, not both.');
@@ -975,40 +1348,133 @@ export async function cmdAttach(rest, flags) {
     // Locator path (the common case): auto-detect the representation, refuse an unrecognized scheme
     // loudly (never silently store a bad value) — fail fast before any RPC. Derive the declared
     // mimeType from the extension.
-    const representation = representationForLocator(uri);
-    if (!representation) {
-        throw new Error(`"${uri}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
-            'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+    // Every `<key> <uri>` pair, validated BEFORE anything is sent — a batch that would revert partway
+    // is exactly what this command now exists to prevent, so a bad locator in pair 5 must stop pair 1.
+    if (pairArgs.length % 2 !== 0) {
+        throw new Error(`attach takes <key> <uri> PAIRS; got ${pairArgs.length} positional argument(s) after the address. ` +
+            `Last one seen: "${pairArgs[pairArgs.length - 1]}".`);
+    }
+    const pairs = [];
+    for (let i = 0; i < pairArgs.length; i += 2) {
+        const k = pairArgs[i];
+        const u = pairArgs[i + 1];
+        assertSettableField(k);
+        const rep = representationForLocator(u);
+        if (!rep) {
+            throw new Error(`"${u}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
+                'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+        }
+        pairs.push({ key: k, uri: u, representation: rep, mimeType: contentTypeFromPath(u) });
+    }
+    // A key repeated within one batch would have the later write silently win — the same
+    // full-column-upsert hazard that bit `register` and `lock-field`. Refuse instead.
+    const dupes = pairs.map((p) => p.key).filter((k, i, a) => a.indexOf(k) !== i);
+    if (dupes.length) {
+        throw new Error(`the same key appears twice in one batch: ${[...new Set(dupes)].join(', ')}. ` +
+            'Each field holds ONE active value, so the last write would silently win — attach them separately if that is really what you want.');
     }
+    const representation = pairs[0].representation;
     const owner = await read(contract, 'owner');
-    const mimeType = contentTypeFromPath(uri);
-    if (mimeType === 'application/octet-stream') {
+    for (const p of pairs) {
+        if (p.mimeType === 'application/octet-stream') {
+            console.log(yellow('  ⚠ ') +
+                dim(`no file extension in "${p.uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
+                dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
+        }
+    }
+    const mimeType = pairs[0].mimeType;
+    for (const p of pairs) {
+        console.log(`  attaching ${bold(p.key)} ${dim(`(${p.mimeType}, ${p.representation})`)} to ${scope}: ${dim(p.uri)}`);
+    }
+    // Where it surfaces. This used to be one dim line, and it read as a footnote rather than as a
+    // dependency: an integrator attached five audio stems to a fully-on-chain token, paid to store
+    // them, and found `tokenURI` listed none of them — "paid for, stored on-chain, and invisible".
+    // The on-chain renderer deliberately omits locator-represented artifacts (they duplicate no
+    // on-chain type information — see specs/protocol/data-plane.md), so the artifacts manifest comes
+    // from a RESOLVER. When the project has no resolver baked in, that is not a footnote, it is the
+    // difference between a feature working and not existing, so say it as a warning.
+    const uriBase = await read(contract, 'tokenURIBase').catch(() => '');
+    const artifactsPath = `/t/${chainId()}/${contract}/${flags.token ?? '0'}`;
+    if (uriBase && uriBase.trim() !== '') {
+        console.log(dim(`    → listed in this project's resolver artifacts (${artifactsPath} and /data/<key>); a bare on-chain tokenURI carries reserved fields plus abx_params only.`));
+    }
+    else {
         console.log(yellow('  ⚠ ') +
-            dim(`no file extension in "${uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
-            dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
-    }
-    console.log(`  attaching ${bold(key)} ${dim(`(${mimeType}, ${representation})`)} to ${scope}: ${dim(uri)}`);
-    // Where it surfaces — say it on the preview path too (not just post-send), so a creator/agent
-    // doesn't expect an attached custom key in a bare `abx tokenuri` (round-2 finding: they did).
-    console.log(dim(`    → appears in a resolver's artifacts listing (/t/${chainId()}/${contract}/${flags.token ?? '0'} and /data/${key}); a bare on-chain tokenURI shows reserved fields only.`));
-    const buildTx = () => collection
-        ? prepareSetContractField({ contract, field: key, representation, value: toHex(uri), chainId: chainId() })
-        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: key, representation, value: toHex(uri), chainId: chainId() });
-    const sent = await runWrite(contract, buildTx(), flags, owner);
+            `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields plus the computed ${bold('abx_params')} block only — ` +
+            `so ${pairs.map((p) => bold(p.key)).join(', ')} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
+            dim('(Configured params DO appear on-chain — attachments are the surface that needs a resolver.)'));
+        console.log(dim(`    to make attached artifacts visible, point the project at a resolver (${bold('abx deploy-resolver')}, or a managed one via ${bold('abx add <addr> --remote <name>')}) — it serves the listing at ${artifactsPath}.`));
+    }
+    // ONE transaction for the whole set. `batchOps` folds a same-target run into a `multicall` and
+    // passes a lone op through untouched, so a single attach is byte-identical to before.
+    const ops = pairs.map((p) => collection
+        ? prepareSetContractField({ contract, field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() })
+        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() }));
+    const batched = batchOps(ops);
+    if (batched.length !== 1) {
+        // Defensive: every op here targets the same contract and carries no value, so batchOps must
+        // return exactly one tx. If that ever changes, fail loudly rather than send a partial set.
+        throw new Error(`attach expected to batch ${ops.length} op(s) into one transaction, got ${batched.length}`);
+    }
+    if (pairs.length > 1) {
+        console.log(dim(`  ${pairs.length} artifacts → ONE transaction (all-or-nothing: a revert lands none of them, so no half-written token).`));
+    }
+    const sent = await runWrite(contract, batched[0], flags, owner);
     if (sent) {
         const id = flags.token ?? '0';
-        console.log(`  ${green('✓')} attached — ${bold(key)} joins ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
+        const names = pairs.map((p) => bold(p.key)).join(', ');
+        console.log(`  ${green('✓')} attached — ${names} join${pairs.length > 1 ? '' : 's'} ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
             dim(`    verify (a resolver serves the complete listing): `) +
-            `curl <your-resolver>/t/${chainId()}/${contract}/${id}` +
-            dim(`  ${collection ? '' : `→ artifacts[].key "${key}"; /data/${key} fetches it`}\n`) +
-            dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields only.)\n`));
+            `abx tokenuri ${contract}${id === '0' ? '' : ` --token ${id}`} --fetch` +
+            dim(`  ${collection ? '' : `→ artifacts[].key ${pairs.map((p) => `"${p.key}"`).join(', ')}; /data/<key> fetches each`}\n`) +
+            dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields plus abx_params. Params never need a resolver; attachments do.)\n`));
     }
 }
 // ── lock-field ───────────────────────────────────────────────────────────────
+/**
+ * Refuse `lock-field` on a name that is a declared PARAM key.
+ *
+ * Fields and params are two separate namespaces that may share a name, and `lock-field` only ever
+ * locks the *field*. A tester welded `grid` — a `Bytes` param holding the artwork — with
+ * `lock-field --field grid`, got "permanent", got `tokenFieldLocked(0,"grid") == true`, and then
+ * overwrote the artwork with `configure-param` on the next call. Every individual statement the CLI
+ * made was true; together they promised a protection that did not exist. Permanence is the pitch, so
+ * this refuses rather than warns, and names the mechanism that actually welds a param.
+ */
+async function refuseIfParamKey(contract, field) {
+    let exists = false;
+    try {
+        const schema = (await makePublicClient({ chainKey: CHAIN }).readContract({
+            address: contract,
+            abi: seriesCodeAbi,
+            functionName: 'paramSchema',
+            args: [encodeTagSdk(field)],
+        }));
+        exists = !!schema[0];
+    }
+    catch {
+        // No param surface at all (a 1/1 or plain Series) — nothing to confuse the name with.
+        return;
+    }
+    if (!exists)
+        return;
+    throw new Error(`"${field}" is a declared PostParam key on ${contract}, and lock-field does NOT lock params — ` +
+        `it locks the metadata FIELD of the same name. They are separate namespaces, so this would have ` +
+        `reported "permanent" while configure-param stayed free to overwrite the value.\n` +
+        `  To weld the param, lock its schema instead:\n` +
+        `    abx set-schema ${contract} --schema ${field}:<Type>:<Auth>:lock=now\n` +
+        `  (after that every configure-param on "${field}" reverts ParamLockExpired — check with ` +
+        `\`abx inspect ${contract}\`.)\n` +
+        `  If you really did mean the metadata field "${field}" and not the param, re-run with --force-field.`);
+}
 export async function cmdLockField(address, flags) {
     const contract = requireAddress(address, 'abx lock-field <address> --field <name> [--collection | --token 0] [--sign|--unsigned]');
     const field = requireFlag(flags, 'field', 'abx lock-field <address> --field <name>');
     const collection = !!flags.collection;
+    // The metadata field and a same-named param are different things; only an explicit --force-field
+    // says "yes, I mean the field". See refuseIfParamKey.
+    if (flags['force-field'] === undefined)
+        await refuseIfParamKey(contract, field);
     const owner = await read(contract, 'owner');
     console.log(dim(`  note: locking the '${field}' field is permanent and irreversible (freezes all its representations).`));
     const tx = collection
@@ -1069,15 +1535,16 @@ async function readSeries(token, fn, args = []) {
         args: args,
     }));
 }
-async function readSale(minter, token) {
+/** The edition twin of {@link readSeries} — reads a per-id getter (`totalSupply(id)`,
+ *  `maxSupply(id)`, `uri(id)`, …) via the narrowest-common-superset edition ABI. */
+async function readEdition(token, fn, args = []) {
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    const [configured, paymentToken, price, allocation, sold] = (await publicClient.readContract({
-        address: minter,
-        abi: abxFixedPriceMinterAbi,
-        functionName: 'sales',
-        args: [token],
+    return (await publicClient.readContract({
+        address: token,
+        abi: oneOfOneEditionAbi,
+        functionName: fn,
+        args: args,
     }));
-    return { configured, paymentToken, price, allocation, sold };
 }
 /** Resolve the shared minter for the chain (flag → env → manifest), or deploy it if none exists.
  *  It's ownerless, so any funded signer can stand it up — the sibling of `ensureChunkStore`. */
@@ -1101,38 +1568,51 @@ async function ensureFixedPriceMinter(override) {
         }
     }
     const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+    const send = makeHotSender({ wallet, account, publicClient });
     console.log(dim('  deploying the canonical fixed-price minter (shared, ownerless) — CREATE2…'));
-    const { minter, txHash } = await deployFixedPriceMinter(wallet, account, publicClient);
+    const { minter, txHash } = await deployFixedPriceMinter(send, publicClient);
     console.log(`  ${green('✓')} fixed-price minter ${minter}`);
     console.log(dim(`  tx ${txHash}`));
     console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ${bold(`ABX_FIXED_PRICE_MINTER=${minter}`)} (or add it to packages/sdk/src/deployments.ts)`));
     return minter;
 }
+/** The edition twin of {@link ensureFixedPriceMinter} — resolves (or deploys) the chain's shared
+ *  `AbxFixedPriceMinter1155`, the Minter spine's per-`(token, id)` sale singleton. */
+async function ensureFixedPriceMinter1155(override) {
+    const known = fixedPriceMinter1155Address(override);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x')
+            return known;
+        console.log(yellow(`  configured edition minter ${known} has no code on ${CHAIN} — deploying a fresh one`));
+    }
+    const predicted = predictFixedPriceMinter1155();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x') {
+            console.log(dim(`  using the canonical fixed-price edition minter at its deterministic address ${predicted}`));
+            return predicted;
+        }
+    }
+    const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+    const send = makeHotSender({ wallet, account, publicClient });
+    console.log(dim('  deploying the canonical fixed-price edition minter (shared, ownerless) — CREATE2…'));
+    const { minter, txHash } = await deployFixedPriceMinter1155(send, publicClient);
+    console.log(`  ${green('✓')} fixed-price edition minter ${minter}`);
+    console.log(dim(`  tx ${txHash}`));
+    console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ${bold(`ABX_FIXED_PRICE_MINTER_1155=${minter}`)} (or add it to packages/sdk/src/deployments.ts)`));
+    return minter;
+}
 /** A minter write (configure/buy). No re-index — the sale lives on the minter, not the token
- *  projection; the token's own state is unchanged by a sale config. */
+ *  projection; the token's own state is unchanged by a sale config.
+ *
+ * Used to hand-roll its own dry-run guard — "the minter path does not go through runWrite, so it
+ * needs its OWN" — which is exactly the duplication {@link gatedSend} exists to end: this now shares
+ * the identical choke point `runWrite` does, so `minter configure`/`minter buy` also pick up
+ * `--confirm` (previously only the deploy family had it) with no extra code here. */
 async function runMinterWrite(provider, flags, expectedSigner) {
-    // --dry-run: preview the sale-config / purchase tx and send NOTHING. The minter path does not go
-    // through runWrite, so it needs its OWN dry-run guard — without it, `minter configure --dry-run`
-    // silently signs + broadcasts a real sale (a critical footgun: a mainnet creator "previewing"
-    // their sale would send it). Mirrors runWrite's guard.
-    if (flags['dry-run']) {
-        const prepared = typeof provider === 'function' ? await provider(expectedSigner ?? zeroAddress) : provider;
-        console.log(`\n  ${bold('◆ ' + prepared.summary)}  ${dim('(dry run — nothing sent)')}`);
-        for (const [k, v] of Object.entries(prepared.fields))
-            console.log(`    ${dim(k.padEnd(12))} ${v}`);
-        console.log(`    ${dim('to'.padEnd(12))} ${prepared.to ?? dim('(contract deploy)')}`);
-        console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
-        return;
-    }
-    await assertChainId(CHAIN);
-    await signTx(provider, {
-        lane: laneFromFlags(flags),
-        chainKey: CHAIN,
-        expectedSigner,
-        yes: !!flags.yes,
-        port: flags.port ? Number(flags.port) : undefined,
-        signUrlFile: flags['sign-url-file'],
-    });
+    await gatedSend(provider, flags, { chainKey: CHAIN, expectedSigner });
 }
 /** Parse the sale price: `--price-raw <units>` (exact base units) or the friendly `--price <ether>`
  *  (18-decimals). ETH sales use `--price`; non-18-dp ERC-20s should use `--price-raw`. */
@@ -1142,30 +1622,83 @@ function parseSalePrice(flags, usage) {
     if (flags.price && flags.price !== 'true')
         return parseEther(flags.price);
     console.error(`missing --price <ether> or --price-raw <units>\nusage: ${usage}\n`);
-    process.exit(1);
+    throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
 }
 /**
  * `abx minter configure <token> --price <eth> --allocation <n> [--erc20 0x…]` — set the fixed-price
  * sale for a project on the shared minter. Defers to the token owner. Resolves (or deploys) the
  * shared minter, then reports the two remaining grants the owner still needs (assign the minter on
  * the token, set a primary payee) and whether the token is paused.
+ *
+ * On an EDITION (OneOfOneEdition/EditionImage/EditionCode), `--token-id` is REQUIRED (sales are
+ * keyed `(token, id)` — a per-artwork price, not one project-wide sale) and the sale routes to the
+ * shared `AbxFixedPriceMinter1155` instead. Refused on a 721 target.
  */
 export async function cmdMinterConfigure(address, flags) {
-    const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--token-id <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
     const owner = await read(token, 'owner');
     const erc20 = flags.erc20 && flags.erc20 !== 'true' ? flags.erc20 : zeroAddress;
     const allocation = BigInt(requireFlag(flags, 'allocation', usage));
     const price = parseSalePrice(flags, usage);
-    // On --dry-run resolve the minter WITHOUT deploying — ensureFixedPriceMinter would deploy the
-    // shared singleton if absent, and a preview must never send. Fall back to a label if none exists.
-    const dryRun = !!flags['dry-run'];
+    const isEth = erc20 === zeroAddress;
+    // On --dry-run resolve the minter WITHOUT deploying — ensure* would deploy the shared singleton
+    // if absent, and a preview must never send. Fall back to a label if none exists.
+    const dryRun = isDryRun(flags);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const knownMinter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (dryRun && !knownMinter) {
+            console.log(yellow(`  ⚠ no shared edition minter deployed on ${CHAIN} yet — a real run deploys it once (a separate tx) before configuring.`));
+        }
+        const minter = dryRun ? (knownMinter ?? zeroAddress) : await ensureFixedPriceMinter1155(flags['minter-contract']);
+        // Sanity-check the allocation against what THIS id can still mint. `maxSupply(id) === 0` reads
+        // as "open" (the un-overridden --copies default, or an id nobody has ever capped) — the same
+        // convention `tokens.ts`'s TokenRow.maxSupply documents; see set-max-supply's own note on why a
+        // bare 0 can't be told apart from "explicitly closed" without more than this one read.
+        const [maxSupply, supplyNow] = await Promise.all([
+            readEdition(token, 'maxSupply', [tokenId]).catch(() => 0n),
+            readEdition(token, 'totalSupply', [tokenId]).catch(() => 0n),
+        ]);
+        const remaining = maxSupply > 0n ? (maxSupply > supplyNow ? maxSupply - supplyNow : 0n) : null;
+        if (remaining !== null && allocation > remaining) {
+            console.log(yellow(`  ⚠ allocation ${allocation} exceeds the ${remaining} #${tokenId} can still mint `) +
+                dim(`(cap ${maxSupply} − ${supplyNow} minted). Only ${remaining} will actually sell.`));
+            console.log(dim(`    To sell ${allocation}, raise this id's cap is not possible (caps only decrease) — set --allocation ${remaining} (or less, to hold reserves).`));
+        }
+        console.log(dim(`  configuring sale on ${minter}`));
+        console.log(dim(`    token      ${token}  ·  id #${tokenId}`));
+        console.log(dim(`    price      ${isEth ? `${formatEther(price)} ETH` : `${price} units of ${erc20}`} / copy`));
+        console.log(dim(`    allocation ${allocation}`));
+        await runMinterWrite(prepareConfigureSale1155({ minter, token, tokenId, paymentToken: erc20, price, allocation, chainId: chainId() }), flags, owner);
+        const [assignedMinter, payee, paused] = await Promise.all([
+            read(token, 'minter').catch(() => zeroAddress),
+            read(token, 'primaryPayee').catch(() => zeroAddress),
+            read(token, 'paused').catch(() => false),
+        ]);
+        const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+        console.log('');
+        console.log(assigned ? dim('  ✓ minter is assigned on the token') : yellow(`  ⚠ assign this minter on the token:  abx set-minter ${token} --minter ${minter}`));
+        if (payee === zeroAddress)
+            console.log(yellow(`  ⚠ set a primary payee (sales revert without one):  abx set-primary-payee ${token} --payee 0x…`));
+        else
+            console.log(dim(`  ✓ proceeds → ${payee}`));
+        if (paused)
+            console.log(yellow(`  • token is paused — open the sale when ready:  abx unpause ${token}`));
+        console.log(dim(`  buyers then run:  abx minter buy ${token} --token-id ${tokenId} --quantity <n>`));
+        return;
+    }
+    // 721 path (unchanged): --token-id has no meaning — a 721 sale is one project-wide price.
+    if (flags['token-id'] !== undefined) {
+        throw new Error(`--token-id is edition-only (per-(token,id) sales) — ${token} is a ${kind.label} (721), sold as a single project-wide sale. Drop --token-id.`);
+    }
     const knownMinter = fixedPriceMinterAddress(flags['minter-contract']);
     if (dryRun && !knownMinter) {
         console.log(yellow(`  ⚠ no shared minter deployed on ${CHAIN} yet — a real run deploys it once (a separate tx) before configuring.`));
     }
     const minter = dryRun ? (knownMinter ?? zeroAddress) : await ensureFixedPriceMinter(flags['minter-contract']);
-    const isEth = erc20 === zeroAddress;
     // Sanity-check the allocation against what the contract can actually mint. A creator who sets
     // --allocation 100 on a 16-supply Series would only ever sell the remainder (maxInvocations binds
     // tighter than the minter's allocation) and discover it when mint #16 reverts. Warn loudly — but
@@ -1203,19 +1736,67 @@ export async function cmdMinterConfigure(address, flags) {
     console.log(dim(`  buyers then run:  abx minter buy ${token}`));
 }
 /** `abx minter show <token>` — the sale terms + the token's readiness (assigned? payee? paused?).
- *  Read-only; the agent runs it to see exactly what's configured before/after a sale. */
+ *  Read-only; the agent runs it to see exactly what's configured before/after a sale. On an
+ *  edition, `--token-id` is required and the readout is per-id (copies, not a whole-contract cap). */
 export async function cmdMinterShow(address, flags) {
-    const token = requireAddress(address, 'abx minter show <token> [--minter-contract 0x…]');
+    const usage = 'abx minter show <token> [--token-id <n> (editions)] [--minter-contract 0x…]';
+    const token = requireAddress(address, usage);
     // Refuse a nonexistent contract like the sibling owner-ops (state/unpause/minter configure) do —
     // otherwise the minter singleton returns zero-config for the unconfigured token and we print a
     // plausible-but-fake `paused: no (open)` readout for an address that has no project at all.
     await assertContractExists(token);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const minter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (!minter) {
+            console.log(yellow(`  no shared edition minter known for ${CHAIN} — configure a sale (deploys it) or set ABX_FIXED_PRICE_MINTER_1155`));
+            return;
+        }
+        const sale = await readSaleConfig1155(publicClient, minter, token, tokenId);
+        // Every read here goes through the EDITION ABI: the generic `read()` is the 721 1/1 ABI,
+        // which has no minter()/primaryPayee() at all — a swallowed client-side throw there printed
+        // a false "not assigned / no payee" for every correctly-configured edition (caught live by
+        // the Sepolia fixture sweep, 2026-08-05).
+        const [assignedMinter, payee, paused, maxSupply, supply] = await Promise.all([
+            readEdition(token, 'minter').catch(() => zeroAddress),
+            readEdition(token, 'primaryPayee').catch(() => zeroAddress),
+            readEdition(token, 'paused').catch(() => false),
+            readEdition(token, 'maxSupply', [tokenId]).catch(() => 0n),
+            readEdition(token, 'totalSupply', [tokenId]).catch(() => 0n),
+        ]);
+        const isEth = sale.paymentToken === zeroAddress;
+        const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+        console.log(bold(`\n  minter sale — ${token} #${tokenId}`));
+        console.log(`    shared minter:     ${minter}`);
+        if (!sale.configured) {
+            console.log(yellow(`    not configured     — abx minter configure ${token} --token-id ${tokenId} --price <eth> --allocation <n>`));
+        }
+        else {
+            console.log(`    price:             ${isEth ? `${formatEther(sale.price)} ETH` : `${sale.price} units of ${sale.paymentToken}`}`);
+            console.log(`    allocation:        ${sale.sold}/${sale.allocation} sold`);
+        }
+        console.log(`    assigned on token: ${assigned ? green('yes') : yellow(`no — abx set-minter ${token} --minter ${minter}`)}`);
+        console.log(`    primary payee:     ${payee === zeroAddress ? yellow('none — abx set-primary-payee …') : payee}`);
+        console.log(`    paused:            ${paused ? yellow(`yes — abx unpause ${token}`) : green('no (open)')}`);
+        console.log(`    copies:            ${supply}${maxSupply > 0n ? `/${maxSupply}` : dim(' (open — no cap)')}`);
+        const remaining = maxSupply > 0n ? (maxSupply > supply ? maxSupply - supply : 0n) : null;
+        if (sale.configured && remaining !== null && sale.allocation > remaining) {
+            console.log(yellow(`    ⚠ allocation ${sale.allocation} exceeds the ${remaining} still mintable for #${tokenId} (cap ${maxSupply} − ${supply} minted) — only ${remaining} can actually sell.`));
+        }
+        console.log('');
+        return;
+    }
+    if (flags['token-id'] !== undefined) {
+        throw new Error(`--token-id is edition-only — ${token} is a ${kind.label} (721). Drop --token-id.`);
+    }
     const minter = fixedPriceMinterAddress(flags['minter-contract']);
     if (!minter) {
         console.log(yellow(`  no shared minter known for ${CHAIN} — configure a sale (deploys it) or set ABX_FIXED_PRICE_MINTER`));
         return;
     }
-    const sale = await readSale(minter, token);
+    const sale = await readSaleConfig(publicClient, minter, token);
     const [assignedMinter, payee, paused, max, supply] = await Promise.all([
         readSeries(token, 'minter').catch(() => zeroAddress),
         readSeries(token, 'primaryPayee').catch(() => zeroAddress),
@@ -1247,14 +1828,46 @@ export async function cmdMinterShow(address, flags) {
     console.log('');
 }
 /** `abx minter buy <token> [--to 0x…]` — buy one token through the shared minter (public; any
- *  funded signer). ETH sales attach the price; ERC-20 sales need a prior approval to the minter. */
+ *  funded signer). ETH sales attach the price; ERC-20 sales need a prior approval to the minter.
+ *  On an edition, `--token-id` is required and `--quantity` (default 1) buys several copies in the
+ *  same purchase — the total ETH attached is `price × quantity`. */
 export async function cmdMinterBuy(address, flags) {
-    const usage = 'abx minter buy <token> [--to 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const usage = 'abx minter buy <token> [--to 0x…] [--token-id <n> --quantity <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const quantity = flags.quantity !== undefined ? parseEditionCountFlag(flags.quantity, 'quantity') : 1n;
+        if (quantity === 0n)
+            throw new Error('--quantity must be at least 1 (0 copies is not a purchase).');
+        const minter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (!minter)
+            throw new Error(`no shared edition minter known for ${CHAIN} — configure a sale first, or set ABX_FIXED_PRICE_MINTER_1155`);
+        const sale = await readSaleConfig1155(publicClient, minter, token, tokenId);
+        if (!sale.configured)
+            throw new Error(`no sale configured for ${token} #${tokenId} — run: abx minter configure ${token} --token-id ${tokenId} …`);
+        const isEth = sale.paymentToken === zeroAddress;
+        const to = flags.to && flags.to !== 'true' ? flags.to : undefined;
+        // Payment math: price × quantity, computed ONCE and shown in the confirm/dry-run readout below
+        // (via runMinterWrite → gatedSend's own preview) — the exact ETH the tx attaches.
+        const value = isEth ? sale.price * quantity : 0n;
+        if (!isEth) {
+            console.log(yellow(`  ERC-20 sale: the buyer must have approved ${minter} to spend ${sale.price * quantity} units of ${sale.paymentToken} first (else the tx reverts).`));
+        }
+        console.log(dim(`  buying ${quantity} cop${quantity === 1n ? 'y' : 'ies'} of #${tokenId}${to ? ` → ${to}` : ' → signer'} for ` +
+            `${isEth ? `${formatEther(value)} ETH (${formatEther(sale.price)} × ${quantity})` : `${value} units (${sale.price} × ${quantity})`}`));
+        await runMinterWrite(preparePurchase1155({ minter, token, tokenId, quantity, to, value, chainId: chainId() }), flags);
+        console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the change.`));
+        return;
+    }
+    if (flags['token-id'] !== undefined || flags.quantity !== undefined) {
+        throw new Error(`--token-id/--quantity are edition-only — ${token} is a ${kind.label} (721), where a sale buys exactly one token. Drop them.`);
+    }
     const minter = fixedPriceMinterAddress(flags['minter-contract']);
     if (!minter)
         throw new Error(`no shared minter known for ${CHAIN} — configure a sale first, or set ABX_FIXED_PRICE_MINTER`);
-    const sale = await readSale(minter, token);
+    const sale = await readSaleConfig(publicClient, minter, token);
     if (!sale.configured)
         throw new Error(`no sale configured for ${token} — run: abx minter configure ${token} …`);
     const isEth = sale.paymentToken === zeroAddress;
@@ -1267,4 +1880,131 @@ export async function cmdMinterBuy(address, flags) {
     await runMinterWrite(preparePurchase({ minter, token, to, value, chainId: chainId() }), flags);
     console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the new token.`));
 }
+// ── PostParam schemas, after deploy ──────────────────────────────────────────
+// `setParamSchema` is owner-gated with no deploy-time restriction, so a project's param surface was
+// never actually frozen at deploy — the toolkit just had no way to reach it, which read to creators
+// as a protocol limitation ("we must guess every param up front, or redeploy and lose the address").
+// Two commands close that: `set-schema` (attach or replace one key) and `retire-param` (stop all
+// further writes, the closest thing to a delete the protocol has).
+/** Values already stored under a key can be stranded by a schema change — the contract does NOT
+ *  re-validate them. Compare old vs new and name what would break, so the guard can refuse. */
+export function strandingRisks(before, after) {
+    const risks = [];
+    const typeName = (i) => PARAM_TYPES[i] ?? String(i);
+    if (before.paramType !== after.paramType) {
+        risks.push(`type ${typeName(before.paramType)} → ${typeName(after.paramType)} (a stored value keeps its old encoding)`);
+    }
+    const dropped = before.selectOptions.filter((o) => !after.selectOptions.includes(o));
+    if (before.selectOptions.length && dropped.length) {
+        risks.push(`Select option(s) removed: ${dropped.join(', ')} (a token already set to one keeps it)`);
+    }
+    // Narrowing either bound can strand a value that sat inside the old range.
+    const asInt = (h) => (PARAM_TYPES[after.paramType] === 'Int256Range' ? BigInt.asIntN(256, BigInt(h)) : BigInt(h));
+    if (before.min !== after.min && asInt(after.min) > asInt(before.min))
+        risks.push(`min raised (${asInt(before.min)} → ${asInt(after.min)})`);
+    if (before.max !== after.max && asInt(before.max) !== 0n && asInt(after.max) < asInt(before.max)) {
+        risks.push(`max lowered (${asInt(before.max)} → ${asInt(after.max)})`);
+    }
+    return risks;
+}
+/** `abx set-schema <address> --schema key:Type:Auth[:lock=<when>]` — attach or replace ONE key's
+ *  on-chain schema, any time in a project's life. Owner-only. */
+export async function cmdSetSchema(address, flags) {
+    const usage = 'abx set-schema <address> --schema key:Type:Auth[:lock=<when>] [--force] [--dry-run] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const specs = parseSchemaSpecs(flags.schema);
+    if (specs.length !== 1) {
+        console.error(`usage: ${usage}\n\n  One key per call — a schema write is a full-row upsert, so batching them hides which one changed.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const next = specs[0];
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const owner = await read(contract, 'owner');
+    const before = await readParamSchema(publicClient, contract, next.key);
+    if (!before.exists) {
+        console.log(`  ${next.key} ${dim('— new governed key')} ${describeSchema(next)}`);
+    }
+    else {
+        // The upsert hazard: this is a FULL row write, so anything not restated is overwritten. Show
+        // both sides, and refuse a change that could strand values unless the caller insists.
+        console.log(`  ${next.key} ${dim('— replacing an existing schema')}`);
+        console.log(`    ${dim('before')} ${describeSchema(onChainToParsed(next.key, before))}`);
+        console.log(`    ${dim('after ')} ${describeSchema(next)}`);
+        const risks = strandingRisks(before, next);
+        if (risks.length && flags.force === undefined) {
+            throw new Error(`refusing to replace "${next.key}" — this change can strand values already stored under it:\n` +
+                risks.map((r) => `    • ${r}`).join('\n') +
+                `\n\n  The contract does NOT re-validate stored values against a new schema, so affected tokens would keep\n` +
+                `  values their own schema no longer allows. Re-run with --force if that is what you intend.`);
+        }
+        // With --force, say what is being overridden. Silently applying a value-stranding change is the
+        // one outcome worse than refusing it: the operator gets no record of which tokens they may have
+        // just invalidated, and neither does anyone reading the terminal afterwards.
+        if (risks.length) {
+            console.log(`    ${C.yellow}⚠${C.reset} ${bold('--force')} — applying a change that can strand stored values:`);
+            for (const r of risks)
+                console.log(`        • ${r}`);
+            console.log(dim(`        any token already holding a value for "${next.key}" keeps it, now outside what its schema allows.`));
+        }
+        if (before.lockAfter && !next.lockAfter) {
+            console.log(`    ${C.yellow}⚠${C.reset} the existing lock (${new Date(before.lockAfter * 1000).toISOString().slice(0, 19)}Z) is being REMOVED — restate it with :lock= to keep it.`);
+        }
+    }
+    // ONE op. A schema write used to need a `params.keys` companion write in the same tx to keep the
+    // on-chain generator's key list in step; the generator now enumerates params from the token
+    // itself, so the schema write is the whole change.
+    await runWrite(contract, prepareSetParamSchema({
+        contract,
+        key: next.key,
+        paramType: next.paramType,
+        auth: next.auth,
+        authAddress: next.authAddress,
+        lockAfter: next.lockAfter,
+        min: next.min,
+        max: next.max,
+        selectOptions: next.selectOptions,
+        chainId: chainId(),
+        display: describeSchema(next),
+    }), flags, owner);
+}
+/** Render an on-chain schema through the same formatter the CLI uses for a parsed one. */
+function onChainToParsed(key, s) {
+    return {
+        key,
+        paramType: s.paramType,
+        auth: s.auth,
+        authAddress: s.authAddress,
+        lockAfter: s.lockAfter,
+        min: s.min,
+        max: s.max,
+        selectOptions: s.selectOptions,
+    };
+}
+/** `abx retire-param <address> <key>` — permanently stop further writes to a PostParam. */
+export async function cmdRetireParam(address, rest, flags) {
+    const usage = 'abx retire-param <address> <key> [--dry-run] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const [key] = positionalArgs(rest);
+    if (!key) {
+        console.error(`usage: ${usage}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const owner = await read(contract, 'owner');
+    const current = await readParamSchema(publicClient, contract, key);
+    if (!current.exists)
+        throw new Error(`no PostParam schema for "${key}" on ${contract} — nothing to retire.`);
+    if (current.lockAfter && current.lockAfter < Math.floor(Date.now() / 1000)) {
+        console.log(`  ${C.green}✓${C.reset} "${key}" is already retired (locked ${new Date(current.lockAfter * 1000).toISOString().slice(0, 19)}Z). Nothing to do.`);
+        return;
+    }
+    console.log(`  ${key} ${dim(describeSchema(onChainToParsed(key, current)))}`);
+    console.log(`    ${dim('after this: every write reverts ParamLockExpired — permanently, with no way back.')}`);
+    console.log(`    ${dim('the schema stays (a key can never be un-governed), and any value ALREADY stored stays and keeps serving.')}`);
+    // Read-modify-write: carry every field forward and change only the lock. Composing a fresh schema
+    // here would silently reset type/auth/bounds/options — the upsert clobber this command exists to avoid.
+    await runWrite(contract, prepareRetireParam({ contract, key, current, chainId: chainId() }), flags, owner);
+}
 //# sourceMappingURL=ownerops.js.map