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

package/dist/commands/deploy.js

@@ -15,7 +15,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
-import { DEFAULT_CHAIN_KEY, DEP_RESOLUTION, METADATA_FIELD as F, contentIdFromLocator, METADATA_REPRESENTATION as R, analyzeScript, assertChainId, checkRegistryDeps, dependencySetupCalls, deployOneOfOne, deploySeries, deployOneOfOneEdition, deployEditionImage, discoverDeployBlock, encodeFieldRenderer, encodeTag, expectedChainComplete, makeHotSender, makePublicClient, makeWalletClient, normalizeAttributes, onchainUriSetupCalls, oneOfOneImageAbi, oneOfOneEditionAbi, parseTraitPairs, planResume, predictClone, probeSeedSource, prepareCodeSetup, prepareDeployOneOfOne, prepareDeploySeries, prepareDeploySeriesCode, prepareDeployOneOfOneEdition, prepareDeployEditionImage, prepareDeployEditionCode, redactRpcUrl, resolveChain, resolveDepRegistryPointer, resolveGenerator, probeTransferValidator, resolveRecommendedTransferValidator, resolveRpcUrl, resolveSeedSource, resolveSeriesCodeFactory, saltFor, seriesCodeAbi, seriesCodeFactoryAbi, tryReadContract, AbxServiceClient, } from '@artblocks/abx-sdk';
+import { DEFAULT_CHAIN_KEY, DEP_RESOLUTION, METADATA_FIELD as F, contentIdFromLocator, METADATA_REPRESENTATION as R, analyzeScript, assertChainId, checkRegistryDeps, dependencySetupCalls, DEFAULT_TX_GAS_BUDGET, MEASURED_ESTIMATE_GAS_ALLOWANCE, SETUP_LEG_GAS, estimateChunkGasForBytes, packCallsByGas, deployOneOfOne, deploySeries, deployOneOfOneEdition, deployEditionImage, discoverDeployBlock, encodeFieldRenderer, encodeTag, expectedChainComplete, makeHotSender, makePublicClient, makeWalletClient, normalizeAttributes, onchainUriSetupCalls, oneOfOneImageAbi, oneOfOneEditionAbi, editionCodeAbi, parseTraitPairs, planResume, planEditionResume, predictClone, probeSeedSource, prepareCodeSetup, prepareDeployOneOfOne, prepareDeploySeries, prepareDeploySeriesCode, prepareDeployOneOfOneEdition, prepareDeployEditionImage, prepareDeployEditionCode, redactRpcUrl, resolveChain, resolveDepRegistryPointer, resolveGenerator, probeTransferValidator, resolveRecommendedTransferValidator, resolveRpcUrl, resolveSeedSource, resolveSeriesCodeFactory, saltFor, seriesCodeAbi, seriesCodeFactoryAbi, tryReadContract, AbxServiceClient, } from '@artblocks/abx-sdk';
 import { DIRECT_URL_BACKENDS, contentTypeFromPath, decideImageContentLane, hashContent, isTurboArweave, resolveBackend, validateRenderStorageCombo, } from '@artblocks/abx-storage';
 import { DEFAULT_PORT, contentHash, generateContent, resolveBaseUrl, startTokenApiServer } from '@artblocks/abx-token-api';
 import { encodeFunctionData, getAddress, toHex, zeroAddress } from 'viem';
@@ -25,7 +25,8 @@ import { isDryRun, parseSaltFlag, refuseStrayFlags, warnSignWithoutFor } from '.
 import { isEditionContract } from '../kind.js';
 import { jsonSafe, withJson } from '../jsonout.js';
 import { planOnChainScript } from '../script-chunks.js';
-import { bold, c, dim, ensureFactory, ensureRenderer, ensureSeedSource, ensureSeriesCodeFactory, ensureSeriesFactory, ensureOneOfOneEditionFactory, ensureEditionFactory, ensureEditionCodeFactory, g, info, keepAlive, ok, p, portInUse, printServing, registerAndIndexLocally, reindexAfterDeploy, step, warn, } from '../output.js';
+import { bold, c, dim, ensureFactory, ensureRenderer, ensureSeedSource, ensureSeriesCodeFactory, ensureSeriesFactory, ensureOneOfOneEditionFactory, ensureEditionFactory, ensureEditionCodeFactory, g, info, keepAlive, ok, p, portInUse, printServing, registerAndIndexLocally, reindexAfterDeploy, step, warn as printWarn, } from '../output.js';
+import { DEPLOY_PLAN_SCHEMA_VERSION, stripAnsiForPlan, } from '../deploy-plan.js';
 import { parseRoyaltyBps, AUTHORSHIP_DEPLOY_FIELDS, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, tokenUriGasEstimate, authorshipContractFields, gatewayContractFields, servingGateway, computeContentPlan, envStagingSender, parseCompress, parseSeedSourceValue, canonicalSeedSource, refuseUnusableSeedSource, parseTransferValidatorValue, guardOnChainSize, previewImageStaging, refusePrewrappedImage, sessionStagingSender, stageImageField, stageImageFieldsBatch, } from '../ownerops.js';
 import { canonicalLabel } from '../remote.js';
 import { assertLaneCanSign, confirmSend, gatedSend, laneFromFlags } from '../riskgate.js';
@@ -33,6 +34,24 @@ import { describeSchema, editionSchemaAdvisory, parseSchemaSpecs } from '../sche
 import { parseSeriesTraits } from '../series-traits.js';
 import { decodeOnChainJson } from '../served.js';
 import { openWalletSession, signHotSequence, signTx } from '../signer.js';
+// ── plan-object warning capture (issue #123) ─────────────────────────────────────────────────────
+// The structured `--json` plan object (deploy-plan.ts) reports "the warnings the lane raised"
+// alongside every other computed field — but ~400 `warn()` call sites in this file exist purely as
+// human prose, and rewriting each to ALSO push onto a collector would be exactly the kind of
+// touch-every-call-site change the plan-object work was scoped to avoid (a wording regression is one
+// typo away, across 17 test files that assert on this prose byte-for-byte). Re-binding the name
+// instead means every existing `warn(...)` call — unchanged, still reading `warn` from this file's own
+// scope — transparently also feeds the plan. `planWarnings` is reset at the top of each
+// `cmdDeploy*Body` (`beginPlanWarnings`) and read once, right before that invocation's `emit()` call(s).
+// Not reentrant/thread-safe by construction — fine, since one CLI process runs exactly one command.
+let planWarnings = [];
+function beginPlanWarnings() {
+    planWarnings = [];
+}
+function warn(s) {
+    planWarnings.push(stripAnsiForPlan(s));
+    printWarn(s);
+}
 // Product dimensions — what you can launch. Two concrete contract FAMILIES exist today: the 721
 // ladder (`--type`, below — 1/1 image or Series) and, orthogonally, ERC-1155 editions (`--copies`,
 // on ANY of the three deploy commands — see `parseCopies`). `--type` picks among unique-token
@@ -629,6 +648,7 @@ export async function cmdDeploy(flags, serveAfter) {
     return withJson(flags, async (emit) => cmdDeployBody(flags, serveAfter, emit));
 }
 export async function cmdDeployBody(flags, serveAfter, emit) {
+    beginPlanWarnings(); // see the collector's own module note, above the DIMENSIONS block
     refuseStrayFlags(flags, DEPLOY_FLAGS, 'deploy');
     warnSignWithoutFor(flags);
     const dimension = resolveDimension(flags.type ?? '1of1');
@@ -906,10 +926,22 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     // never disagree. Counts TX signatures only: a storage upload signed by a connected wallet
     // (Arweave via --storage-signer eth) is a message signature, not a transaction, and is already
     // named separately (see the `remoteEthUpload` narration) — it does not add to this count.
+    // Also captures the plan object's `custody.image` file metadata (issue #123 follow-up): the SAME
+    // bytes read here for the tx-count math, hashed/typed locally (no chain read) — never re-derived
+    // at the emit site below.
+    let planImageFile = null;
     const approvals = onchainImage
         ? (() => {
-            const plan = computeContentPlan(readFileSync(resolvePath(flags.image)), parseCompress(flags.compress)).plan;
-            return (plan.mode === 'single' ? 1 : plan.txCount) + 1; // staging tx(s) + the deploy tx
+            const bytes = readFileSync(resolvePath(flags.image));
+            const compress = parseCompress(flags.compress);
+            const contentPlan = computeContentPlan(bytes, compress);
+            planImageFile = {
+                bytes: bytes.length,
+                stagedBytes: contentPlan.stagedBytes,
+                mimeType: contentTypeFromPath(resolvePath(flags.image)),
+                contentHash: hashContent(bytes),
+            };
+            return (contentPlan.plan.mode === 'single' ? 1 : contentPlan.plan.txCount) + 1; // staging tx(s) + the deploy tx
         })()
         : 1;
     // Mint-on-deploy is the default; --no-mint defers it so you can stand up + warm
@@ -978,6 +1010,10 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     };
     let clone;
     let blockNumber;
+    // The eventual owner/signer — set in whichever lane branch below learns it, so the SENT plan
+    // object (further down) can report `roles` without re-deriving anything. `undefined` only while
+    // no branch has run yet; every path that reaches the sent `emit()` has set it by then.
+    let deployerAddr;
     if (dryRun) {
         let deployer;
         if (flags.for)
@@ -1035,7 +1071,41 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
         // A dry run DOES know the address when --salt pinned it (a pure function of factory+salt); without
         // --salt it's null — reporting the freshly-reserved one would be a real-looking value a script
         // could act on that the actual deploy will not land at. `saltPinned` still says why.
-        emit(jsonSafe({ command: 'deploy', dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
+        emit(jsonSafe({
+            command: 'deploy', dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol,
+            // The structured plan (issue #123) — built from the SAME locals the readout above just
+            // printed; nothing here is re-derived or newly computed. `deployer` is a real wallet address
+            // regardless of salt pinning (only the PREDICTED CONTRACT address carries that caveat, and
+            // this plan doesn't repeat it — see `address`, above), so roles are safe to report unconditionally.
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: '1of1',
+                lane,
+                transactions: { approvals, legs: onchainImage ? ['onchain-image-staging', 'deploy'] : null },
+                // The 1/1 lane's InitParams has no minter/primaryPayee field at all — `null` here means
+                // "no concept on this lane", not "unset".
+                roles: { signer: deployer, owner: deployer, royaltyReceiver: deployer, primaryPayee: null, minter: null },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    imageOnChain: onchainImage,
+                    backend: !onChainUri && !onchainImage ? backendResolution(storageOverrides(flags)).backend : null,
+                    // `''` (on-chain lane, no explicit --public-base-url) is reported as `null` here — the
+                    // human line already spells out WHY (renderer-authoritative); a JSON consumer just needs
+                    // "nothing baked", not an empty string to interpret.
+                    tokenUriBase: params.tokenURIBase || null,
+                    contractUriBase: params.contractURIBase || null,
+                    renderer: onChainUri ? renderer : null,
+                    image: planImageFile,
+                },
+                mint: { deferred: noMint, count: noMint ? 0 : 1, amountPerId: null, recipient: noMint ? null : deployer },
+                estimate: { ethApprox: null, gasApprox: null }, // the 1/1 lane computes no cost estimate
+                warnings: planWarnings.slice(),
+                surfaces: null, // the code lanes' per-surface disposition has no equivalent here
+                dependencies: null, // the 1/1 lane has no dependency-registry concept
+                resume: null,
+            },
+        }));
         return;
     }
     // opt-in --confirm: a final y/N before the real send (no-op without --confirm; never blocks scripts)
@@ -1044,6 +1114,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     if (lane === 'send') {
         // hot lane: the env key is the deployer, known up front.
         const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         const { clone: predicted, params, salt, contentNote } = await buildForDeployer(account.address);
         info(`deterministic address: ${predicted}`);
         info(describeDeployField('description', flags.description, onChainUri || !!flags['description-onchain']));
@@ -1081,6 +1152,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
         let r;
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             // Stage on-chain through the session (sets bakedImage, which buildForDeployer reads below).
             const { field, note } = await stageImageField(flags.image, parseCompress(flags.compress), sessionStagingSender(session));
             bakedImage = field;
@@ -1113,6 +1185,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
         let r;
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             // Route Turbo uploads' signatures to this session before building content (which uploads).
             uploadRemoteEth = { address: signer, signMessage: (m) => session.signMessage(m, 'Sign Arweave upload (paid from your Turbo credits)') };
             const { clone: predicted, params, salt, contentNote } = await buildForDeployer(signer);
@@ -1137,6 +1210,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
             ? 'a wallet will become the owner; the token resolves from chain — no URI base is baked in.'
             : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
+            deployerAddr = signer;
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeployOneOfOne({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
         }, { lane, chainKey: CHAIN, yes: !!flags.yes, expectedSigner: flags.for, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
@@ -1150,7 +1224,34 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     }
     // Emitted the moment the address is known, and again below once minting is settled — so a crash in
     // the indexing steps that follow still yields the address of a contract that really does exist.
-    emit(jsonSafe({ command: 'deploy', address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol }));
+    emit(jsonSafe({
+        command: 'deploy', address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: '1of1',
+            lane,
+            transactions: { approvals, legs: onchainImage ? ['onchain-image-staging', 'deploy'] : null },
+            roles: { signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null, primaryPayee: null, minter: null },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: onchainImage,
+                backend: !onChainUri && !onchainImage ? backendResolution(storageOverrides(flags)).backend : null,
+                // Recomputed from the same top-level locals `buildForDeployer`'s `params` used (no branch
+                // carries `params` out to this scope) — never a new decision, the identical ternary.
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? renderer : null,
+                image: planImageFile,
+            },
+            mint: { deferred: noMint, count: noMint ? 0 : 1, amountPerId: null, recipient: noMint ? null : deployerAddr ?? null },
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: null,
+            dependencies: null,
+            resume: null,
+        },
+    }));
     step(serveAfter ? 'What the chain knows now' : 'Index it — replay the event spine from chain');
     const indexer = localIndexer();
     // Off-chain traits ride in the registration (on-chain ones are already in the contract fields).
@@ -1284,6 +1385,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
 // spreads `DEPLOY_FLAGS`, so it must come AFTER that declaration at module scope, same reason
 // `DEPLOY_SERIES_EDITION_FLAGS` sits next to it rather than beside `cmdDeployEditionImageBody`.)
 export async function cmdDeployOneOfOneEditionBody(flags, emit) {
+    beginPlanWarnings();
     refuseStrayFlags(flags, DEPLOY_EDITION_FLAGS, 'deploy');
     warnSignWithoutFor(flags);
     // `--type` is the 721 lane's OWN dimension seam (cmdDeployBody redirects `--type series` to
@@ -1436,10 +1538,21 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
     // The edition paths shipped without this and without the readout line below, so `--copies` previews
     // silently dropped the approval count the skill promises "every preview" prints — leaving an agent
     // with nothing to tell the creator about how many wallet prompts to expect.
+    // Also captures `custody.image` file metadata (issue #123 follow-up) — see the 1/1 twin's identical
+    // local for why it's computed here rather than re-derived at the emit site.
+    let planImageFile = null;
     const approvals = onchainImage
         ? (() => {
-            const plan = computeContentPlan(readFileSync(resolvePath(flags.image)), parseCompress(flags.compress)).plan;
-            return (plan.mode === 'single' ? 1 : plan.txCount) + 1;
+            const bytes = readFileSync(resolvePath(flags.image));
+            const compress = parseCompress(flags.compress);
+            const contentPlan = computeContentPlan(bytes, compress);
+            planImageFile = {
+                bytes: bytes.length,
+                stagedBytes: contentPlan.stagedBytes,
+                mimeType: contentTypeFromPath(resolvePath(flags.image)),
+                contentHash: hashContent(bytes),
+            };
+            return (contentPlan.plan.mode === 'single' ? 1 : contentPlan.plan.txCount) + 1;
         })()
         : 1;
     if (onChainUri) {
@@ -1487,6 +1600,8 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
     };
     let clone;
     let blockNumber;
+    // See the 1/1 lane's identical local for why this is hoisted (feeds the sent plan's `roles`).
+    let deployerAddr;
     if (dryRun) {
         let deployer;
         if (flags.for)
@@ -1531,13 +1646,43 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
         }
         info(dim('the values above are exactly what a real deploy writes — nothing else is added.'));
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent, no bytes stored. Re-run without --dry-run to deploy.')}\n`);
-        emit(jsonSafe({ command: 'deploy', kind: '1of1-edition', copies: editionSize.toString(), dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
+        emit(jsonSafe({
+            command: 'deploy', kind: '1of1-edition', copies: editionSize.toString(), dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol,
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: '1of1-edition',
+                lane,
+                transactions: { approvals, legs: onchainImage ? ['onchain-image-staging', 'deploy'] : null },
+                roles: {
+                    signer: deployer, owner: deployer, royaltyReceiver: deployer,
+                    primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                    minter: minter !== zeroAddress ? minter : null,
+                },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    imageOnChain: onchainImage,
+                    backend: !onChainUri && !onchainImage ? backendResolution(storageOverrides(flags)).backend : null,
+                    tokenUriBase: params.tokenURIBase || null,
+                    contractUriBase: params.contractURIBase || null,
+                    renderer: onChainUri ? renderer : null,
+                    image: planImageFile,
+                },
+                mint: { deferred: mintAmount === 0n, count: mintAmount > 0n ? 1 : 0, amountPerId: mintAmount.toString(), recipient: mintAmount > 0n ? deployer : null },
+                estimate: { ethApprox: null, gasApprox: null },
+                warnings: planWarnings.slice(),
+                surfaces: null,
+                dependencies: null,
+                resume: null,
+            },
+        }));
         return;
     }
     await confirmSend(`About to deploy an edition of "${name}" (${symbol}) — ${editionSize === 0n ? 'open' : editionSize.toString()} copies${flags.image ? ' with your image' : ' (generative demo content)'}; mint: ${mintAmount > 0n ? `${mintAmount} at deploy` : 'deferred'}; approvals: ${approvals} wallet approval(s); owner+royalty: your wallet @ ${royaltyBps / 100}%.` +
         (transferValidator !== zeroAddress ? ` ERC-1155C: enrolled at deploy, permanently (validator ${transferValidator}).` : ''), flags);
     if (lane === 'send') {
         const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         const { clone: predicted, params, salt, contentNote } = await buildForDeployer(account.address);
         info(`deterministic address: ${predicted}`);
         info(describeDeployField('description', flags.description, onChainUri || !!flags['description-onchain']));
@@ -1568,6 +1713,7 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
         let r;
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             await stageOnChainImage(sessionStagingSender(session)); // sets bakedImage, read by buildForDeployer
             const { clone: predicted, params, salt, contentNote } = await buildForDeployer(signer);
             info(contentNote);
@@ -1587,6 +1733,7 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
         // wallet lane without staging, or the cold lane: a single deploy tx.
         info(onChainUri ? 'a wallet will become the owner; the token resolves from chain — no URI base is baked in.' : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
+            deployerAddr = signer;
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeployOneOfOneEdition({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
         }, { lane, chainKey: CHAIN, yes: !!flags.yes, expectedSigner: flags.for, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
@@ -1598,7 +1745,36 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
         blockNumber = result.blockNumber;
         ok(`deployed ${clone}`);
     }
-    emit(jsonSafe({ command: 'deploy', kind: '1of1-edition', copies: editionSize.toString(), address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol }));
+    emit(jsonSafe({
+        command: 'deploy', kind: '1of1-edition', copies: editionSize.toString(), address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: '1of1-edition',
+            lane,
+            transactions: { approvals, legs: onchainImage ? ['onchain-image-staging', 'deploy'] : null },
+            roles: {
+                signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null,
+                primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                minter: minter !== zeroAddress ? minter : null,
+            },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: onchainImage,
+                backend: !onChainUri && !onchainImage ? backendResolution(storageOverrides(flags)).backend : null,
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? renderer : null,
+                image: planImageFile,
+            },
+            mint: { deferred: mintAmount === 0n, count: mintAmount > 0n ? 1 : 0, amountPerId: mintAmount.toString(), recipient: mintAmount > 0n ? deployerAddr ?? null : null },
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: null,
+            dependencies: null,
+            resume: null,
+        },
+    }));
     step('Index it — replay the event spine from chain');
     const indexer = localIndexer();
     const offChainTraits = !traitsOnchain && traits.length ? JSON.stringify(traits) : undefined;
@@ -1668,6 +1844,7 @@ export async function cmdDeploySeries(flags) {
     return withJson(flags, async (emit) => cmdDeploySeriesBody(flags, emit));
 }
 export async function cmdDeploySeriesBody(flags, emit) {
+    beginPlanWarnings();
     refuseStrayFlags(flags, DEPLOY_SERIES_FLAGS, 'deploy-series');
     warnSignWithoutFor(flags);
     const name = flags.name ?? 'ABX Series';
@@ -2070,14 +2247,50 @@ export async function cmdDeploySeriesBody(flags, emit) {
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent, no bytes stored.')}\n`);
         // Without --salt, `address` would be a freshly-reserved value a real deploy will NOT land at —
         // report null rather than a real-looking value a script could wrongly act on.
-        emit(jsonSafe({ command: 'deploy-series', dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
+        emit(jsonSafe({
+            command: 'deploy-series', dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol,
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: 'series',
+                lane,
+                // A staged on-chain collection is many chunk-write txs, one per file — that per-token detail
+                // is printed above (`previewImageStaging`), not re-derived here; `legs` just names the shape.
+                transactions: { approvals, legs: onchainImage ? ['onchain-image-staging (per token)', 'deploy'] : null },
+                roles: {
+                    signer: deployer, owner: deployer, royaltyReceiver: deployer,
+                    primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                    minter: minter !== zeroAddress ? minter : null,
+                },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    imageOnChain: onchainImage,
+                    backend: offchainImageOnchainJson || !onChainUri ? backendId : null,
+                    tokenUriBase: params.tokenURIBase || null,
+                    contractUriBase: params.contractURIBase || null,
+                    renderer: onChainUri ? renderer : null,
+                    // Series stages ONE FILE PER TOKEN under --onchain-image — no single-file shape fits (see
+                    // this field's own doc comment) — so this stays null even when `imageOnChain` is true.
+                    image: null,
+                },
+                mint: { deferred: mintCount === 0, count: mintCount, amountPerId: null, recipient: mintCount > 0 ? deployer : null },
+                estimate: { ethApprox: null, gasApprox: null },
+                warnings: planWarnings.slice(),
+                surfaces: null,
+                dependencies: null,
+                resume: null,
+            },
+        }));
         return;
     }
     let clone;
     let blockNumber;
+    // See the 1/1 lane's identical local for why this is hoisted (feeds the sent plan's `roles`).
+    let deployerAddr;
     if (lane === 'send') {
         // hot lane: the env key stages every token up front (deployer-independent), then deploys.
         const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         if (onchainImage)
             await buildFields(envStagingSender());
         const { clone: predicted, params, salt } = await buildForDeployer(account.address);
@@ -2104,6 +2317,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
         });
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             if (onchainImage)
                 await buildFields(sessionStagingSender(session));
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
@@ -2129,6 +2343,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
         });
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             // Route Turbo uploads through the wallet (mutate the SAME opts.arweave the backend captured).
             if (opts.arweave)
                 opts.arweave.remoteEth = { address: signer, signMessage: (m) => session.signMessage(m, 'Sign Arweave upload (paid from your Turbo credits)') };
@@ -2151,6 +2366,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
             ? 'a wallet will become the owner; tokens resolve from chain — no URI base is baked in.'
             : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
+            deployerAddr = signer;
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeploySeries({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
         }, { lane, chainKey: CHAIN, yes: !!flags.yes, expectedSigner: flags.for, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
@@ -2168,7 +2384,36 @@ export async function cmdDeploySeriesBody(flags, emit) {
     info(`permanent: size ${count} · royalty ${royaltyBps / 100}%${flags['royalty-bps'] === undefined ? ' ⚠ default' : ''} → the deploying wallet` +
         ` · cap ${maxRoyaltyBps / 100}%${burnable ? ' · burnable' : ''}` +
         dim('  (rate is changeable with `abx set-royalty`; the CAP only ever goes down)'));
-    emit(jsonSafe({ command: 'deploy-series', address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol }));
+    emit(jsonSafe({
+        command: 'deploy-series', address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: 'series',
+            lane,
+            transactions: { approvals, legs: onchainImage ? ['onchain-image-staging (per token)', 'deploy'] : null },
+            roles: {
+                signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null,
+                primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                minter: minter !== zeroAddress ? minter : null,
+            },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: onchainImage,
+                backend: offchainImageOnchainJson || !onChainUri ? backendId : null,
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? renderer : null,
+                image: null, // per-token staging — see the dry-run emit's identical comment
+            },
+            mint: { deferred: mintCount === 0, count: mintCount, amountPerId: null, recipient: mintCount > 0 ? deployerAddr ?? null : null },
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: null,
+            dependencies: null,
+            resume: null,
+        },
+    }));
     step('Index it — replay the event spine from chain');
     const indexer = localIndexer();
     const baseReg = {
@@ -2244,6 +2489,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
 // (`DEPLOY_SERIES_EDITION_FLAGS` is declared further down, beside `DEPLOY_EDITION_FLAGS` — see that
 // const's own note on why.)
 export async function cmdDeployEditionImageBody(flags, emit) {
+    beginPlanWarnings();
     refuseStrayFlags(flags, DEPLOY_SERIES_EDITION_FLAGS, 'deploy-series');
     warnSignWithoutFor(flags);
     const editionSize = parseCopies(flags.copies);
@@ -2563,6 +2809,8 @@ export async function cmdDeployEditionImageBody(flags, emit) {
     };
     let clone;
     let blockNumber;
+    // See the 1/1 lane's identical local for why this is hoisted (feeds the sent plan's `roles`).
+    let deployerAddr;
     if (dryRun) {
         let deployer;
         if (flags.for)
@@ -2602,11 +2850,48 @@ export async function cmdDeployEditionImageBody(flags, emit) {
             info(`address: pinned by salt — re-run with ${bold(`--salt ${salt}`)} (same address).`);
         }
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent, no bytes stored. Re-run without --dry-run to deploy.')}\n`);
-        emit(jsonSafe({ command: 'deploy-series', kind: 'edition', copies: editionSize.toString(), ids: count, dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
+        emit(jsonSafe({
+            command: 'deploy-series', kind: 'edition', copies: editionSize.toString(), ids: count, dryRun: true, sent: false, address: explicitSalt ? predicted : null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol,
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: 'series-edition',
+                lane,
+                transactions: { approvals, legs: onchainImage ? ['onchain-image-staging (per id)', 'deploy'] : null },
+                roles: {
+                    signer: deployer, owner: deployer, royaltyReceiver: deployer,
+                    primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                    minter: minter !== zeroAddress ? minter : null,
+                },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    imageOnChain: onchainImage,
+                    backend: !onchainImage && (offchainImageOnchainJson || !onChainUri) ? backendId : null,
+                    tokenUriBase: params.tokenURIBase || null,
+                    contractUriBase: params.contractURIBase || null,
+                    renderer: onChainUri ? renderer : null,
+                    // Series-edition stages ONE FILE PER id under --onchain-image — no single-file shape fits
+                    // (see this field's own doc comment) — so this stays null even when `imageOnChain` is true.
+                    image: null,
+                },
+                mint: {
+                    deferred: effectiveMintCount === 0,
+                    count: effectiveMintCount,
+                    amountPerId: mintAmount.toString(),
+                    recipient: effectiveMintCount > 0 ? deployer : null,
+                },
+                estimate: { ethApprox: null, gasApprox: null },
+                warnings: planWarnings.slice(),
+                surfaces: null,
+                dependencies: null,
+                resume: null,
+            },
+        }));
         return;
     }
     if (lane === 'send') {
         const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         // hot lane: the env key stages every id up front (deployer-independent), then deploys.
         if (onchainImage)
             await buildFields(envStagingSender());
@@ -2635,6 +2920,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
         let r;
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             await buildFields(sessionStagingSender(session));
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             info(`mint: ${effectiveMintCount > 0 ? `${effectiveMintCount} id(s) × ${mintAmount} cop${mintAmount === 1n ? 'y' : 'ies'} → ${signer} at deploy` : 'deferred'}`);
@@ -2652,6 +2938,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
     else {
         info(onChainUri ? 'a wallet will become the owner; the tokens resolve from chain — no URI base is baked in.' : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
+            deployerAddr = signer;
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeployEditionImage({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
         }, { lane, chainKey: CHAIN, yes: !!flags.yes, expectedSigner: flags.for, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
@@ -2663,7 +2950,41 @@ export async function cmdDeployEditionImageBody(flags, emit) {
         blockNumber = result.blockNumber;
         ok(`deployed ${clone}`);
     }
-    emit(jsonSafe({ command: 'deploy-series', kind: 'edition', copies: editionSize.toString(), ids: count, address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol }));
+    emit(jsonSafe({
+        command: 'deploy-series', kind: 'edition', copies: editionSize.toString(), ids: count, address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: 'series-edition',
+            lane,
+            transactions: { approvals, legs: onchainImage ? ['onchain-image-staging (per id)', 'deploy'] : null },
+            roles: {
+                signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null,
+                primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                minter: minter !== zeroAddress ? minter : null,
+            },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: onchainImage,
+                backend: !onchainImage && (offchainImageOnchainJson || !onChainUri) ? backendId : null,
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? renderer : null,
+                image: null, // per-id staging — see the dry-run emit's identical comment
+            },
+            mint: {
+                deferred: effectiveMintCount === 0,
+                count: effectiveMintCount,
+                amountPerId: mintAmount.toString(),
+                recipient: effectiveMintCount > 0 ? deployerAddr ?? null : null,
+            },
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: null,
+            dependencies: null,
+            resume: null,
+        },
+    }));
     step('Index it — replay the event spine from chain');
     const indexer = localIndexer();
     const offChainTraits = !seriesTraitsOnchain && offChainTokenTraits ? offChainTokenTraits : undefined;
@@ -2919,6 +3240,10 @@ export const DEPLOY_CODE_FLAGS = new Set([
     'dry-run', 'confirm', 'yes',
     'json', // the deployed address as data, narration to stderr
     'resume', // finish an existing contract whose setup transaction never landed (no deploy)
+    // Meaningful ONLY on `--resume` against an EditionCode target (per-id copies for the premint
+    // shortfall) — kept in the allowlist (not stray) so a misuse elsewhere gets this function's own
+    // pointed refusal instead of the generic "unrecognized flag". See the --resume block.
+    'mint-amount',
 ]);
 // Storage + signing + preview flags shared by every deploy path (mirrors storageOverrides() + the lanes).
 export const SHARED_DEPLOY_FLAGS = [
@@ -2963,6 +3288,76 @@ export const DEPLOY_SERIES_FLAGS = new Set([
 // module has finished evaluating.
 export const DEPLOY_EDITION_FLAGS = new Set([...DEPLOY_FLAGS, 'copies', 'mint-amount', 'minter', 'primary-payee', 'unpaused']);
 export const DEPLOY_SERIES_EDITION_FLAGS = new Set([...DEPLOY_SERIES_FLAGS, 'copies', 'mint-amount']);
+export const chunkSetupLeg = (index, hex, data) => {
+    const bytes = (hex.length - 2) / 2;
+    return { calls: [data], gas: estimateChunkGasForBytes(bytes), label: `script chunk [${index}] (${bytes} bytes)`, kind: 'chunk', chunkBytes: [bytes] };
+};
+export const schemaSetupLeg = (key, data) => ({
+    calls: [data], gas: SETUP_LEG_GAS.schema, label: `param schema '${key}'`, kind: 'schema', schemaKey: key,
+});
+export const depsSetupLeg = (calls) => ({
+    calls, gas: calls.length * SETUP_LEG_GAS.dependency, label: `${calls.length} dependency declaration(s)`, kind: 'deps',
+});
+export const uriSetupLeg = (calls) => ({
+    calls, gas: calls.length * SETUP_LEG_GAS.onchainUri, label: 'on-chain URI wiring', kind: 'uri',
+});
+export const mintSetupLeg = (data) => ({ calls: [data], gas: SETUP_LEG_GAS.mint, label: 'reserve mint', kind: 'mint' });
+/** `SetupLegsCore` (resume.ts's id-agnostic four leg groups, shared by both 721 and EditionCode) →
+ *  the gas-batching shape above — schemas individually (resume diffs them per-key too), deps and
+ *  on-chain-URI as one atomic leg apiece (resume diffs them as one group too — see resume.ts's
+ *  `planCoreLegs`). Mints are NOT included here: their shape differs by lane (721 whole-total vs
+ *  EditionCode per-id vs a `--resume` shortfall) — every caller builds its own mint legs. */
+export function coreSetupLegs(legs) {
+    return {
+        chunks: legs.chunks.map((c) => chunkSetupLeg(c.index, c.hex, c.data)),
+        config: [
+            ...legs.schemas.map((s) => schemaSetupLeg(s.key, s.data)),
+            ...(legs.deps.calls.length ? [depsSetupLeg(legs.deps.calls)] : []),
+            ...(legs.uri.calls.length ? [uriSetupLeg(legs.uri.calls)] : []),
+        ],
+    };
+}
+/**
+ * Split three ordered leg groups into gas-bounded batches — chunks, then config, then mints, NEVER
+ * mixed (see the module note above). Refuses BEFORE building anything if a single leg's own gas
+ * estimate alone exceeds the binding `eth_estimateGas` ceiling: batching only helps when the problem
+ * is too MANY legs, not one leg too big, and that case must never reach a raw "gas limit too high".
+ * Deterministic in the legs' `.gas` values alone (never their `.calls`), so calling this once early
+ * (to size `approvals`, before an owner is even known) and again later with the real calldata
+ * produces the IDENTICAL batch shape both times — no drift between what's previewed and what's sent.
+ */
+export function planCodeSetupBatches(groups) {
+    const all = [...groups.chunks, ...groups.config, ...groups.mints];
+    if (all.length === 0)
+        return [];
+    const oversized = all.find((leg) => leg.gas > MEASURED_ESTIMATE_GAS_ALLOWANCE);
+    if (oversized) {
+        throw new Error(`setup leg — ${oversized.label} — needs ~${oversized.gas.toLocaleString()} gas on its own, which exceeds the ` +
+            `~${MEASURED_ESTIMATE_GAS_ALLOWANCE.toLocaleString()} eth_estimateGas ceiling every transaction is bound by ` +
+            `(that RPC allowance is the binding constraint — not the higher block gas limit). No amount of batching can ` +
+            `make ONE leg fit a transaction by itself — shrink it before deploying (a smaller chunk size, fewer items in ` +
+            `this leg), then re-run.`);
+    }
+    const total = all.reduce((g, l) => g + l.gas, 0);
+    if (total <= DEFAULT_TX_GAS_BUDGET)
+        return [all]; // fits one tx — unchanged common-case behavior
+    return [...packCallsByGas(groups.chunks), ...packCallsByGas(groups.config), ...packCallsByGas(groups.mints)].filter((b) => b.length > 0);
+}
+/** Turn ordered setup-leg batches into the actual `prepareCodeSetup` transactions — rebuilding each
+ *  batch's chunk/schema/dependency/on-chain-URI labeling from its OWN legs, since a batch born from
+ *  the split may carry only part of a group (see {@link planCodeSetupBatches}). */
+export function codeSetupTxsFromBatches(batches, args) {
+    return batches.map((batch) => prepareCodeSetup({
+        contract: args.contract,
+        chainId: args.chainId,
+        calls: batch.flatMap((l) => l.calls),
+        chunkCount: batch.filter((l) => l.kind === 'chunk').length,
+        chunkBytes: batch.filter((l) => l.kind === 'chunk').flatMap((l) => l.chunkBytes ?? []),
+        schemaKeys: batch.filter((l) => l.kind === 'schema').map((l) => l.schemaKey),
+        deps: batch.some((l) => l.kind === 'deps') ? args.deps : [],
+        onchainUri: batch.some((l) => l.kind === 'uri'),
+    }));
+}
 export async function cmdDeployCode(flags) {
     // `--resume` targets an EXISTING contract — its standard (721 or edition) was fixed at THAT
     // contract's own deploy, so `--copies` (a creation-time choice) is nonsensical alongside it.
@@ -2981,6 +3376,7 @@ export async function cmdDeployCode(flags) {
     return withJson(flags, async (emit) => cmdDeployCodeBody(flags, emit));
 }
 export async function cmdDeployCodeBody(flags, emit) {
+    beginPlanWarnings();
     const usage = 'abx deploy-code (--script <file> | --code-dir <dir>) --name "Title" --symbol SYM ' +
         '(--public-base-url https://your.resolver.domain | --onchain-uri) ' +
         '[--description "<s>"] [--external-url <url>] [--image-base <url> | --image-renderer 0x..] [--attributes-renderer 0x..] ' +
@@ -3004,6 +3400,16 @@ export async function cmdDeployCodeBody(flags, emit) {
     // Shared path so the "did you mean --max / price is post-deploy" hints fire here too.
     refuseStrayFlags(flags, DEPLOY_CODE_FLAGS, 'deploy-code');
     warnSignWithoutFor(flags);
+    // --mint-amount only means anything on a --resume against an EXISTING EditionCode target (a per-id
+    // premint shortfall needs an amount; a fresh 721 deploy has no such field, and a 721 resume's mint
+    // leg is a single whole-contract shortfall with no amount either). Checked HERE, before the dry-run
+    // preview branch below returns early for a fresh deploy — a --resume against an actual EditionCode
+    // (where the flag DOES apply) gets the more specific 721-vs-edition guard further down instead.
+    if (flags['mint-amount'] !== undefined && flags.resume === undefined) {
+        throw new Error('--mint-amount only applies to `abx deploy-code --resume <address>` against an EXISTING EditionCode contract — ' +
+            'a fresh 721 deploy (this command, without --copies) has no per-id mint amount. For a NEW edition deploy, use ' +
+            '`abx deploy-code --copies <n|open> --mint-amount <n>`.');
+    }
     const dryRun = isDryRun(flags);
     const name = flags.name ?? 'ABX Code';
     const symbol = flags.symbol ?? 'ABXC';
@@ -3393,7 +3799,7 @@ export async function cmdDeployCodeBody(flags, emit) {
     if (flags['image-renderer'] || flags['attributes-renderer']) {
         warn(`${bold('renderer check — yours to verify')} (the CLI confirms code at the address, NOT that render() behaves): an IAbxFieldRenderer must ` +
             `${bold('NEVER revert')} for any token/param state incl. the collection surface (tokenId = type(uint256).max) — a revert bricks the WHOLE tokenURI (no try/catch) — ` +
-            `and must return the right content-type (image → ${bold('image/svg+xml')} · attributes → a JSON array). Review the render function + forge-test it before shipping. Invariants: reference/code-projects.md.`);
+            `and must return the right content-type (image → ${bold('image/svg+xml')} · attributes → a JSON array). Review the render function + forge-test it before shipping. Invariants: reference/code.md.`);
     }
     // ── Surfaces disposition — resolve EVERY product dimension explicitly, up front ──────────────
     // A code project has four surfaces that each land somewhere (or nowhere). A real session shipped
@@ -3458,6 +3864,10 @@ export async function cmdDeployCodeBody(flags, emit) {
                 // PostParams it reads (unlike the JS lane's static paramHints), so nudge — the palette-miss.
                 ? `⚠ none declared — if your Solidity renderer reads ANY collector PostParam, declare EACH with ${bold('--schema <key>:Type:Auth')} (matching the key your renderer reads — e.g. ${bold('palette:HexColor:TokenOwner')}) or that input is FIXED at the renderer's default forever and collectors can't set it (the CLI can't detect the key — a Solidity renderer is opaque, so this is on you to declare)`
                 : 'none declared';
+    // Hoisted here (rather than beside its one printed use, in the Surfaces block below) so BOTH the
+    // dry-run's Surfaces block and the plan object's `surfaces.postParams.ok` (populated at every one
+    // of this lane's emit sites, dry-run/sent/resume alike) read the exact same verdict.
+    const paramsNudge = !scriptAnalysis && !schemas.length && (hasImageRenderer || hasAttributesRenderer);
     // TOKENURI PUBLIC-READ GAS — a large --onchain-uri document assembles on-chain per call; an
     // unauthenticated public read (Etherscan "Read Contract" with no wallet connected) can hit a client
     // gas cap and appear to REVERT. Expected, not a bug — a real session mis-diagnosed it as indexing lag.
@@ -3493,7 +3903,60 @@ export async function cmdDeployCodeBody(flags, emit) {
     // one whenever a dependency leg rode the multicall alongside a renderer-only (`foldIntoInit`) fold.
     const depLegs = deps.length + (depRegistry ? 1 : 0);
     const setupLen = scriptChunks.length + schemas.length + depLegs + (onchainUriLegs?.length ?? 0) + setupMintCount;
-    const approvals = 1 + (setupLen > 0 ? 1 : 0); // deploy tx + (a setup multicall only if something rides it)
+    // The setup legs, GROUPED. The normal deploy flattens them; `--resume` diffs them against chain
+    // state and sends only what is missing (see resume.ts). One builder for both, so a resume can never
+    // drift from what a fresh deploy would have written — a second implementation of this sequence is
+    // the failure mode a repair verb most easily introduces. Moved up here (it used to sit right before
+    // `preparedFor`, far below) so `approvals`/`planSetupLegs`/the dry-run's tx-count line can all size
+    // themselves off the SAME gas-bounded batch plan `preparedFor` actually sends — see
+    // `planCodeSetupBatches`'s own doc for why calling it here with a placeholder owner and again below
+    // with the real one can never disagree (it's a pure function of each leg's `.gas`, never its
+    // `.calls`, and owner only ever appears in a mint call's calldata, never its gas).
+    const setupLegGroups = (owner) => ({
+        chunks: scriptChunks.map((chunk, i) => ({
+            index: i,
+            hex: chunk,
+            data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), chunk] }),
+        })),
+        schemas: schemas.map(({ key, paramType, auth, authAddress, lockAfter, min, max, selectOptions }) => ({
+            key,
+            data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setParamSchema', args: [encodeTag(key), paramType, auth, authAddress, lockAfter, min, max, selectOptions] }),
+        })),
+        deps: { count: deps.length, registry: depRegistry ?? null, calls: dependencySetupCalls(deps, depRegistry) },
+        // program lane only: animation_url field · the URI renderers (before the mints)
+        uri: { calls: onchainUriLegs ?? [], animationField: onchainUriLegs?.length ? F.animationUrl : null },
+        // The INTENDED TOTAL, not a count to add — a resume mints the shortfall. `mintCount` covers both
+        // lanes: folded-into-init (renderer-only) and setup-carried, since either way it is what the
+        // creator asked for.
+        mints: { intendedTotal: mintCount, data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'mint', args: [owner] }) },
+    });
+    // Gas-bounded setup-transaction batches for a FRESH deploy — chunks, then config, then mints, never
+    // mixed (see `planCodeSetupBatches`). `owner` is irrelevant to the batch SHAPE (only a mint call's
+    // calldata embeds it, never its gas), so `zeroAddress` here is a placeholder that's never sent —
+    // it exists purely so `approvals`/`planSetupLegs` (and the dry-run prose) can report the REAL
+    // transaction count before a deployer is even known, with zero risk of drifting from what
+    // `preparedFor` below actually builds and sends.
+    const freshDeployBatches = planCodeSetupBatches({
+        ...coreSetupLegs(setupLegGroups(zeroAddress)),
+        mints: Array.from({ length: setupMintCount }, () => mintSetupLeg('0x')),
+    });
+    const approvals = 1 + freshDeployBatches.length; // deploy tx + however many gas-bounded setup batches
+    // Ordered legs riding the setup (if any), for the plan object's `transactions.legs` — GROUP names,
+    // not a literal per-transaction count (a group can span more than one batch — see deploy-plan.ts's
+    // own doc comment on `legs`). The SAME booleans `setupLen`/`setupBits` (the dry-run's own
+    // `transactions:` line, below) already use, so this can't drift from the tx(es) the wallet actually
+    // signs. Always ends with `'deploy'` when non-null — the setup batch(es) (if any) ride AHEAD of the
+    // deploy tx, never instead of it.
+    const planSetupLegs = setupLen > 0
+        ? [
+            scriptChunks.length ? 'chunks' : null,
+            schemas.length ? 'param-schemas' : null,
+            depLegs ? 'dependencies' : null,
+            onchainUriLegs ? 'onchain-uri' : null,
+            setupMintCount ? 'mints' : null,
+            'deploy',
+        ].filter((leg) => leg !== null)
+        : null;
     // opt-in --confirm: one y/N before ANY upload or send (no-op without --confirm; never blocks scripts).
     if (!dryRun) {
         const renderHome = process.env.ABX_STORAGE_BACKEND || 'fs'; // empty string counts as unset (=fs)
@@ -3609,13 +4072,20 @@ export async function cmdDeployCodeBody(flags, emit) {
             onchainUriLegs ? 'on-chain-uri' : '',
             setupMintCount ? 'mints' : '',
         ].filter(Boolean).join('/');
-        info(`transactions: ${1 + (setupLen > 0 ? 1 : 0)} (deploy${foldIntoInit ? ' — on-chain-uri wiring + mint fold into it' : ''}${setupLen > 0 ? ` + one setup multicall: ${setupBits}` : ''})` +
-            (foldIntoInit && setupLen === 0 ? ` ${dim('— single transaction, fully self-contained')}` : ''));
+        info(`transactions: ${approvals} (deploy${foldIntoInit ? ' — on-chain-uri wiring + mint fold into it' : ''}` +
+            (freshDeployBatches.length > 0
+                ? ` + ${freshDeployBatches.length} setup ${freshDeployBatches.length === 1 ? 'transaction' : 'transactions (gas-bounded)'}: ${setupBits}`
+                : '') +
+            ')' +
+            (foldIntoInit && freshDeployBatches.length === 0 ? ` ${dim('— single transaction, fully self-contained')}` : ''));
         info(`approvals   ${approvals} wallet approval(s)`); // TX signatures only; the same number the tx-count line above implies
         // Best-effort cost guidance (owner: a bonus in dry-run, never a blocker — silently skip if the
         // RPC can't price gas; see cli-ux-decisions). On-chain byte storage dominates a template drop,
         // so apply the skill's own ~200 gas/byte heuristic to the stored bytes + coarse per-op costs,
         // priced at the live gas price. Clearly hedged — it's an order-of-magnitude figure, not a quote.
+        // `planEstimate` carries the SAME figures into the plan object below — `null` (not computed)
+        // when the RPC can't price gas, exactly mirroring the human line's own silent skip.
+        let planEstimate = null;
         try {
             const chunkBytes = scriptChunks.reduce((n, c) => n + (c.length - 2) / 2, 0);
             const fieldBytes = contractFields.reduce((n, f) => n + (f.value.length - 2) / 2, 0);
@@ -3632,6 +4102,7 @@ export async function cmdDeployCodeBody(flags, emit) {
             const ethStr = eth >= 0.00001 ? eth.toFixed(5) : '<0.00001';
             info(`est. on-chain cost: ${dim('~')}${ethStr} ETH ` +
                 dim(`(very rough — ~${Number(roughGas).toLocaleString()} gas @ ${(Number(gasPrice) / 1e9).toFixed(2)} gwei; excludes off-chain storage${codeDir ? ', the dominant cost for a directory drop' : ''})`));
+            planEstimate = { ethApprox: ethStr, gasApprox: roughGas.toString() };
         }
         catch { /* gas pricing unavailable — cost guidance is a bonus, skip silently */ }
         // ── Surfaces — every marketplace-facing dimension, resolved NOW (none is backfillable) ──────
@@ -3675,8 +4146,7 @@ export async function cmdDeployCodeBody(flags, emit) {
                 info(`  ${dim('render storage home:')} ${bold(renderHome)} ${dim('— a public home the runner uploads to ✓')}`);
             }
         }
-        (traitsBroken ? warn : info)(`traits: ${traitsDisposition}`);
-        const paramsNudge = !scriptAnalysis && !schemas.length && (hasImageRenderer || hasAttributesRenderer);
+        (traitsBroken ? warn : info)(`traits: ${traitsDisposition}`); // `paramsNudge` is hoisted above (with `paramsDisposition`) — shared with the plan object
         ((undeclaredParams.length || paramsNudge ? warn : info))(`postparams: ${paramsDisposition}`);
         if (anySurfaceBroken) {
             const remedies = [
@@ -3769,7 +4239,46 @@ export async function cmdDeployCodeBody(flags, emit) {
         // `address` is null without --salt pinning it or in the wallet lane with no --for (the
         // signer decides the salt, so no address exists yet) — reporting null is the honest answer;
         // inventing one would be a wrong reservation.
-        emit(jsonSafe({ command: 'deploy-code', dryRun: true, sent: false, address: shownAddr, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt: salt ?? null, saltPinned: !!explicitSalt, name, symbol, onChainUri }));
+        emit(jsonSafe({
+            command: 'deploy-code', dryRun: true, sent: false, address: shownAddr, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt: salt ?? null, saltPinned: !!explicitSalt, name, symbol, onChainUri,
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: 'code',
+                // `lane` (the hoisted const) isn't declared until AFTER this early-return block — reading it
+                // here would hit its temporal dead zone. `laneFromFlags` is pure (flags only), so call it
+                // directly; the sent-side emit, below `const lane = …`, uses the hoisted binding instead.
+                lane: laneFromFlags(flags),
+                transactions: { approvals, legs: planSetupLegs },
+                roles: {
+                    signer: deployer, owner: deployer, royaltyReceiver: deployer,
+                    primaryPayee: flags['primary-payee'] ?? null,
+                    minter: flags.minter ?? null,
+                },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    // The code lane's image is one of several independently-disposed surfaces, not a single
+                    // boolean — see `surfaces.thumbnail` below.
+                    imageOnChain: null,
+                    backend: dirUpload ? dirUpload.backend.id : null,
+                    tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                    contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                    renderer: onChainUri ? metadataRenderer : null,
+                    // This lane has no single `--image` file — see `surfaces.thumbnail` below instead.
+                    image: null,
+                },
+                mint: { deferred: mintCount === 0, count: mintCount, amountPerId: null, recipient: mintCount > 0 ? deployer : null },
+                estimate: planEstimate ?? { ethApprox: null, gasApprox: null },
+                warnings: planWarnings.slice(),
+                surfaces: {
+                    thumbnail: { ok: !imageOrphaned, detail: stripAnsiForPlan(imageDisposition) },
+                    traits: { ok: !traitsBroken, detail: stripAnsiForPlan(traitsDisposition) },
+                    postParams: { ok: !(undeclaredParams.length > 0 || paramsNudge), detail: stripAnsiForPlan(paramsDisposition) },
+                },
+                dependencies: { count: deps.length, registry: depRegistry ?? null },
+                resume: null,
+            },
+        }));
         return;
     }
     // Real deploy: perform the deferred directory upload now (past the confirm gate).
@@ -3820,47 +4329,21 @@ export async function cmdDeployCodeBody(flags, emit) {
         tokenFields: [],
         contractFields,
     });
-    // The setup legs, GROUPED. The normal deploy flattens them; `--resume` diffs them against chain
-    // state and sends only what is missing (see resume.ts). One builder for both, so a resume can never
-    // drift from what a fresh deploy would have written — a second implementation of this sequence is
-    // the failure mode a repair verb most easily introduces.
-    const setupLegGroups = (owner) => ({
-        chunks: scriptChunks.map((chunk, i) => ({
-            index: i,
-            hex: chunk,
-            data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), chunk] }),
-        })),
-        schemas: schemas.map(({ key, paramType, auth, authAddress, lockAfter, min, max, selectOptions }) => ({
-            key,
-            data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setParamSchema', args: [encodeTag(key), paramType, auth, authAddress, lockAfter, min, max, selectOptions] }),
-        })),
-        deps: { count: deps.length, registry: depRegistry ?? null, calls: dependencySetupCalls(deps, depRegistry) },
-        // program lane only: animation_url field · the URI renderers (before the mints)
-        uri: { calls: onchainUriLegs ?? [], animationField: onchainUriLegs?.length ? F.animationUrl : null },
-        // The INTENDED TOTAL, not a count to add — a resume mints the shortfall. `mintCount` covers both
-        // lanes: folded-into-init (renderer-only) and setup-carried, since either way it is what the
-        // creator asked for.
-        mints: { intendedTotal: mintCount, data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'mint', args: [owner] }) },
-    });
-    const setupCalls = (owner) => {
-        const g = setupLegGroups(owner);
-        return [
-            ...g.chunks.map((c) => c.data),
-            ...g.schemas.map((x) => x.data),
-            ...g.deps.calls,
-            ...g.uri.calls,
-            // folded mints ride init, not here — so this uses setupMintCount, not the intended total.
-            ...Array.from({ length: setupMintCount }, () => g.mints.data),
-        ];
-    };
+    // `setupLegGroups` (the shared, resume-compatible builder) and the fresh-deploy batch shape
+    // (`freshDeployBatches`) are hoisted above — see the comment there for why. Build the REAL
+    // transactions for the actual signer from the SAME batch shape (identical `.gas` sequence ⇒
+    // identical split — see `planCodeSetupBatches`'s doc), this time with real mint calldata.
     const cid = resolveChain(CHAIN).id;
     const preparedFor = async (owner) => {
         const salt = parseSaltFlag(flags.salt) ?? saltFor(owner);
         const clone = (await publicClient.readContract({ address: factory, abi: seriesCodeFactoryAbi, functionName: 'predictDeterministicAddress', args: [salt] }));
-        const calls = setupCalls(owner);
-        const txs = [prepareDeploySeriesCode({ factory, params: initParamsFor(owner), salt, chainId: cid, clone })];
-        if (calls.length)
-            txs.push(prepareCodeSetup({ contract: clone, calls, chainId: cid, chunkCount: scriptChunks.length, chunkBytes: scriptChunks.map((h) => (h.length - 2) / 2), schemaKeys: schemas.map((x) => x.key), deps: deps.map((d) => d.display), onchainUri: onChainUri && hasProgram }));
+        const g = setupLegGroups(owner);
+        const batches = planCodeSetupBatches({
+            ...coreSetupLegs(g),
+            mints: Array.from({ length: setupMintCount }, () => mintSetupLeg(g.mints.data)),
+        });
+        const setupTxs = codeSetupTxsFromBatches(batches, { contract: clone, chainId: cid, deps: deps.map((d) => d.display) });
+        const txs = [prepareDeploySeriesCode({ factory, params: initParamsFor(owner), salt, chainId: cid, clone }), ...setupTxs];
         return { clone, txs };
     };
     // ── --resume: finish an EXISTING contract, deploy nothing ──────────────────────────────────
@@ -3894,36 +4377,39 @@ export async function cmdDeployCodeBody(flags, emit) {
             if (flags[flag] !== undefined)
                 throw new Error(`--resume cannot be combined with --${flag}: ${why}.`);
         }
-        // Edition resume is NOT supported: the SDK's `planResume`/`ResumeReader` (resume.ts) assume the
-        // 721 shape throughout — a single sequential `mint(address)` shortfall against a whole-contract
-        // `totalSupply()`, neither of which exists on EditionCode (`mint(address,uint256,uint256)` per id,
-        // no whole-contract total — see tokens.ts's `TokenListing.totalSupply` doc). Refuse cleanly rather
-        // than diff against the wrong shape and silently under- or over-report what's missing.
-        if (await isEditionContract(publicClient, target)) {
-            throw new Error(`--resume ${target}: this is an EditionCode contract, and resume isn't wired for editions yet — the diff logic ` +
-                `(packages/sdk/src/resume.ts) assumes the 721 shape (one sequential mint, one whole-contract totalSupply), ` +
-                `neither of which an edition has. If the setup multicall is what failed, the safest path right now is a hand-` +
-                `assembled resend (the SAME idea resume.ts automates for 721 — see its class-level doc comment) or filing this ` +
-                `as a gap: edition resume needs its own ResumeReader/SetupLegs shape (per-id totalSupply, a (to,id,amount) mint leg).`);
-        }
+        // 721 SeriesCode vs EditionCode: same setup shape (script chunks, schemas, deps, on-chain URI
+        // legs), different mint shape — a 721 mints ONE sequential token against a whole-contract
+        // `totalSupply()`; an edition mints AMOUNT copies of a specific id against that id's own
+        // `totalSupply(id)` (there is no whole-contract total on an edition — see tokens.ts's
+        // `TokenListing.totalSupply` doc). `resume.ts` models both (`planResume`/`planEditionResume`,
+        // sharing the four non-mint legs via `planCoreLegs`); this is the one place that decides which.
+        const isEdition = await isEditionContract(publicClient, target);
+        if (!isEdition && flags['mint-amount'] !== undefined) {
+            throw new Error(`--resume ${target}: this is a 721 SeriesCode contract, so --mint-amount has nothing to address — its mint leg ` +
+                `is a single whole-contract shortfall with no per-id amount. Drop --mint-amount (use --mint-count).`);
+        }
+        const abi = isEdition ? editionCodeAbi : seriesCodeAbi;
         const owner = await publicClient
-            .readContract({ address: target, abi: seriesCodeAbi, functionName: 'owner' })
+            .readContract({ address: target, abi, functionName: 'owner' })
             .catch(() => undefined);
         if (!owner)
-            throw new Error(`--resume ${target}: could not read owner() — is this an ABX SeriesCode contract?`);
+            throw new Error(`--resume ${target}: could not read owner() — is this an ABX SeriesCode/EditionCode contract?`);
         step('Resume — read what is missing, send only that');
-        info(`target ${bold(target)} ${dim(`· owner ${owner}`)}`);
+        info(`target ${bold(target)} ${dim(`· owner ${owner}${isEdition ? ' · EditionCode (ERC-1155)' : ''}`)}`);
         // Every read is a view on the target; the intended legs come from the SAME builder a fresh deploy
-        // uses, so what gets sent is by construction what the deploy would have written.
+        // uses, so what gets sent is by construction what the deploy would have written. Only the four
+        // non-mint groups are used on the edition branch below — `legs.mints` is the 721 shape and is
+        // rebuilt per-id there instead (see resume.ts's class doc for why the split).
         const legs = setupLegGroups(owner);
-        // ResumeReader's contract is `T | null` (its planner distinguishes "read failed" from a
-        // legitimately-falsy result); tryReadContract's is `T | undefined` — adapt at the boundary.
+        // The contract is `T | null` (the planner distinguishes "read failed" from a legitimately-falsy
+        // result); tryReadContract's is `T | undefined` — adapt at the boundary.
         const readAt = async (functionName, args = []) => {
-            const result = await tryReadContract(publicClient, { address: target, abi: seriesCodeAbi, functionName, args });
+            const result = await tryReadContract(publicClient, { address: target, abi, functionName, args });
             return result === undefined ? null : result;
         };
         const nonZero = (a) => (a && a !== zeroAddress ? a : null);
-        const reader = {
+        // The four id-agnostic reads, shared verbatim by both standards (see resume.ts's `ResumeReaderCore`).
+        const coreReads = {
             scriptChunkCount: async () => Number((await readAt('scriptChunkCount')) ?? 0n),
             scriptChunk: (index) => readAt('scriptChunk', [BigInt(index)]),
             schemaExists: async (key) => {
@@ -3938,53 +4424,180 @@ export async function cmdDeployCodeBody(flags, emit) {
                 const r = await readAt('contractField', [encodeTag(field)]);
                 return !!r && r[0] !== `0x${'0'.repeat(64)}`;
             },
-            totalSupply: async () => Number((await readAt('totalSupply')) ?? 0n),
         };
-        const plan = await planResume(reader, legs);
+        const plan = isEdition
+            ? await (async () => {
+                // `--mint-count`/`--mint-amount` are the SAME flags a fresh `--copies` deploy reads (see
+                // cmdDeployEditionCodeBody) — so re-running the original command with `--copies` swapped
+                // for `--resume <address>` reproduces the identical intended mint plan: ids 0..mintCount-1,
+                // each an intended TOTAL of mintAmount copies.
+                const mintAmount = flags['mint-amount'] !== undefined ? parseNonNegativeIntFlag(String(flags['mint-amount']), 'mint-amount') : 1n;
+                if (mintCount > 0 && mintAmount === 0n) {
+                    throw new Error('--mint-amount 0 with ids being pre-minted makes no sense — pass a positive --mint-amount, or drop --mint-count/--no-mint it entirely.');
+                }
+                const editionLegs = {
+                    chunks: legs.chunks,
+                    schemas: legs.schemas,
+                    deps: legs.deps,
+                    uri: legs.uri,
+                    mints: Array.from({ length: mintCount }, (_, id) => ({
+                        id: BigInt(id),
+                        intendedAmount: mintAmount,
+                        dataForAmount: (amount) => encodeFunctionData({ abi: oneOfOneEditionAbi, functionName: 'mint', args: [owner, BigInt(id), amount] }),
+                    })),
+                };
+                const reader = {
+                    ...coreReads,
+                    totalSupplyForId: async (id) => Number((await readAt('totalSupply', [id])) ?? 0n),
+                };
+                return planEditionResume(reader, editionLegs);
+            })()
+            : await planResume({ ...coreReads, totalSupply: async () => Number((await readAt('totalSupply')) ?? 0n) }, legs);
         for (const line of plan.done)
             ok(line);
         for (const line of plan.todo)
             info(`will send — ${line}`);
+        // A resume plan object (below) reports its OWN family/roles/custody, deliberately lighter than a
+        // fresh deploy's: royalty, mint, and byte custody are InitParams fields fixed at the ORIGINAL
+        // deploy — a resume only ever finishes MISSING setup legs, so those fields are explicit `null`
+        // (see deploy-plan.ts's own doc comments) rather than restating what this invocation's flags say,
+        // which a resume does not actually write.
+        // ANNOTATED, not inferred: this object is spread into four `satisfies DeployPlan` emits below, and
+        // an un-annotated literal WIDENS its own properties (`schemaVersion` 1 -> number, `family`
+        // 'code'|'code-edition' -> string), so every one of those spreads would fail to satisfy the plan.
+        // The Omit names exactly the three keys each call site supplies for itself.
+        const resumePlanBase = {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: isEdition ? 'code-edition' : 'code',
+            lane,
+            roles: { signer: owner, owner, royaltyReceiver: null, primaryPayee: null, minter: null },
+            royalty: null,
+            // renderer/image: null — both are InitParams facts fixed at the ORIGINAL deploy (like
+            // royalty/mint above); a resume doesn't re-read or re-decide either here.
+            custody: { onChainUri, imageOnChain: null, backend: null, tokenUriBase: null, contractUriBase: null, renderer: null, image: null },
+            mint: null,
+            warnings: planWarnings.slice(),
+            // Still reflects what THIS invocation's flags say about every marketplace-facing surface —
+            // computed once, unconditionally, at the top of the function (see `imageDisposition` et al.),
+            // so it's available whether this run turns out to be a fresh deploy or a `--resume`.
+            surfaces: {
+                thumbnail: { ok: !imageOrphaned, detail: stripAnsiForPlan(imageDisposition) },
+                traits: { ok: !traitsBroken, detail: stripAnsiForPlan(traitsDisposition) },
+                postParams: { ok: !(undeclaredParams.length > 0 || paramsNudge), detail: stripAnsiForPlan(paramsDisposition) },
+            },
+            dependencies: { count: deps.length, registry: depRegistry ?? null },
+        };
         if (!plan.calls.length) {
             ok(`nothing missing — this contract's setup is already complete. ${dim('Confirm with `abx verify ' + target + '`.')}`);
-            emit(jsonSafe({ command: 'deploy-code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, sent: false, complete: true, sentLegs: 0 }));
+            emit(jsonSafe({
+                command: 'deploy-code', kind: isEdition ? 'edition-code' : 'code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, sent: false, complete: true, sentLegs: 0,
+                plan: {
+                    ...resumePlanBase,
+                    transactions: { approvals: 0, legs: null },
+                    estimate: { ethApprox: null, gasApprox: null },
+                    resume: { target, sentLegs: 0, complete: true },
+                },
+            }));
             console.log('');
             return;
         }
-        const tx = prepareCodeSetup({
+        // Reconstruct `plan.calls` (one flat, ORDERED array) back into the four leg groups it was built
+        // from — chunks, schemas, deps, uri, in that exact order (resume.ts's `planCoreLegs` guarantees
+        // it; see its module doc) — using the counts `plan.sending` already reports, so this can't drift
+        // from what the diff actually decided to send. Mints (whatever is left) are appended by
+        // `planResume`/`planEditionResume` AFTER these four, also guaranteed by resume.ts.
+        let resumeCallPtr = 0;
+        const takeResumeCalls = (n) => {
+            const slice = plan.calls.slice(resumeCallPtr, resumeCallPtr + n);
+            resumeCallPtr += n;
+            return slice;
+        };
+        const missingChunkCalls = takeResumeCalls(plan.sending.chunkIndices.length);
+        const missingSchemaCalls = takeResumeCalls(plan.sending.schemaKeys.length);
+        const missingDepsCalls = takeResumeCalls(plan.sending.deps ? legs.deps.calls.length : 0);
+        const missingUriCalls = takeResumeCalls(plan.sending.uri ? legs.uri.calls.length : 0);
+        const missingMintCalls = takeResumeCalls(plan.sending.mints);
+        // Same gas-bounded batching a fresh deploy uses (`planCodeSetupBatches`) — a `--resume` whose
+        // setup never landed AT ALL is missing exactly as much as a fresh deploy would have sent, so it
+        // needs the identical split to clear the same `eth_estimateGas` ceiling.
+        const resumeBatches = planCodeSetupBatches({
+            chunks: missingChunkCalls.map((data, i) => {
+                const bytes = plan.sending.chunkBytes[i];
+                return { calls: [data], gas: estimateChunkGasForBytes(bytes), label: `script chunk [${plan.sending.chunkIndices[i]}] (${bytes} bytes)`, kind: 'chunk', chunkBytes: [bytes] };
+            }),
+            config: [
+                ...missingSchemaCalls.map((data, i) => schemaSetupLeg(plan.sending.schemaKeys[i], data)),
+                ...(missingDepsCalls.length ? [depsSetupLeg(missingDepsCalls)] : []),
+                ...(missingUriCalls.length ? [uriSetupLeg(missingUriCalls)] : []),
+            ],
+            mints: missingMintCalls.map(mintSetupLeg),
+        });
+        const setupTxs = codeSetupTxsFromBatches(resumeBatches, {
             contract: target,
-            calls: plan.calls,
             chainId: resolveChain(CHAIN).id,
-            chunkCount: plan.sending.chunkIndices.length,
-            chunkBytes: plan.sending.chunkBytes,
-            schemaKeys: plan.sending.schemaKeys,
             deps: plan.sending.deps ? deps.map((d) => d.display) : [],
-            onchainUri: plan.sending.uri,
         });
+        // `transactions.legs` names WHICH groups ride the setup, from the same `plan.sending` flags that
+        // build the batches above (never re-derived) — GROUP names, not a literal per-transaction count
+        // (see deploy-plan.ts's own doc comment on `legs`; a `--resume` may now send more than one setup
+        // transaction, same as a fresh deploy).
+        const resumeLegs = [
+            plan.sending.chunkIndices.length ? 'chunks' : null,
+            plan.sending.schemaKeys.length ? 'param-schemas' : null,
+            plan.sending.deps ? 'dependencies' : null,
+            plan.sending.uri ? 'onchain-uri' : null,
+        ].filter((leg) => leg !== null);
         // Routed through the shared risk gate — the same choke point ownerops.ts's `runWrite` uses for
         // every owner-op: --dry-run preview / --confirm prompt / lane selection / signing, all one way.
         // This used to be its own hand-rolled copy of that exact shape (a dry-run print then confirmSend
         // then signTx, duplicated from ownerops.ts's `runWrite`); a deploy-family write is a write like
         // any other, so it takes the identical gate (the preview also gains the `to`/`owner` lines
-        // `runWrite`'s preview always printed).
+        // `runWrite`'s preview always printed) — called once per gas-bounded batch, in order.
         if (isDryRun(flags)) {
-            emit(jsonSafe({ command: 'deploy-code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, dryRun: true, sent: false, complete: false, sentLegs: plan.calls.length }));
+            emit(jsonSafe({
+                command: 'deploy-code', kind: isEdition ? 'edition-code' : 'code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, dryRun: true, sent: false, complete: false, sentLegs: plan.calls.length,
+                plan: {
+                    ...resumePlanBase,
+                    transactions: { approvals: setupTxs.length, legs: resumeLegs },
+                    estimate: { ethApprox: null, gasApprox: null },
+                    resume: { target, sentLegs: plan.calls.length, complete: false },
+                },
+            }));
         }
-        const result = await gatedSend(() => tx, flags, { chainKey: CHAIN, expectedSigner: owner });
-        if (!result) {
-            if (isDryRun(flags))
-                return;
-            console.log(`\n${dim('  unsigned — broadcast it, then re-run `abx verify ' + target + '` to confirm the setup completed.')}\n`);
-            emit(jsonSafe({ command: 'deploy-code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, sent: false, complete: false, sentLegs: plan.calls.length }));
+        let lastResult = null;
+        for (const tx of setupTxs) {
+            const result = await gatedSend(() => tx, flags, { chainKey: CHAIN, expectedSigner: owner });
+            if (result) {
+                ok(`${tx.summary}`);
+                lastResult = result;
+            }
+        }
+        if (isDryRun(flags))
+            return;
+        if (!lastResult) {
+            // The cold ('unsigned') lane: every batch printed its own unsigned tx above (in order — they
+            // target the SAME already-existing contract, so unlike a fresh deploy's deploy→setup dependency
+            // there's no reason to withhold the later ones). Nothing was broadcast, so there is no block to
+            // scan from and no indexing to do yet.
+            console.log(`\n${dim(`  unsigned — broadcast ${setupTxs.length > 1 ? 'these, in order,' : 'it'} then re-run \`abx verify ${target}\` to confirm the setup completed.`)}\n`);
+            emit(jsonSafe({
+                command: 'deploy-code', kind: isEdition ? 'edition-code' : 'code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, sent: false, complete: false, sentLegs: plan.calls.length,
+                plan: {
+                    ...resumePlanBase,
+                    transactions: { approvals: setupTxs.length, legs: resumeLegs },
+                    estimate: { ethApprox: null, gasApprox: null },
+                    resume: { target, sentLegs: plan.calls.length, complete: false },
+                },
+            }));
             return;
         }
-        ok(`${tx.summary}`);
         // Locals, not the outer clone/deployBlock: this branch never falls through to the deploy path, and
         // the authoritative scan floor is still the clone's CREATION block (getCode search), not this
         // repair tx's block — flooring the resolver above the deploy would hide the `code` field again.
-        const resumedFloor = (await discoverDeployBlock(publicClient, target)) ?? result.blockNumber;
+        const resumedFloor = (await discoverDeployBlock(publicClient, target)) ?? lastResult.blockNumber;
         emit(jsonSafe({
             command: 'deploy-code',
+            kind: isEdition ? 'edition-code' : 'code',
             resumed: target,
             address: target,
             chain: CHAIN,
@@ -3993,16 +4606,34 @@ export async function cmdDeployCodeBody(flags, emit) {
             sent: true,
             complete: true,
             sentLegs: plan.calls.length,
-            txHash: result.txHash,
+            txHash: lastResult.txHash,
+            plan: {
+                ...resumePlanBase,
+                transactions: { approvals: setupTxs.length, legs: resumeLegs },
+                estimate: { ethApprox: null, gasApprox: null },
+                resume: { target, sentLegs: plan.calls.length, complete: true },
+            },
         }));
         step('Index');
-        await registerAndIndexLocally(target, { 'from-block': resumedFloor.toString(), factory, label: name });
+        // The factory HINT registerAndIndexLocally passes through to detectCanonicalFactory is taken as
+        // an UNVERIFIED override when present (see anchors.ts) — so it must name the RIGHT factory family
+        // for this target. `factory` (outer scope) is the 721 SeriesCode factory this function resolved at
+        // its own "Trust anchor" step; an EditionCode target needs its own factory's address instead (a
+        // read-only manifest lookup — never bootstraps one, unlike a real edition deploy).
+        await registerAndIndexLocally(target, {
+            'from-block': resumedFloor.toString(),
+            factory: isEdition ? editionCodeFactoryAddress(flags.factory) : factory,
+            label: name,
+        });
         console.log(`\n  ${g('\u2713 setup finished')} \u2014 ${dim('confirm it resolves:')} ${bold(`abx verify ${target}`)}` +
             `${onChainUri ? dim('  (chain-complete + the on-chain tokenURI)') : ''}\n`);
         return;
     }
     let clone;
     let deployBlock;
+    // See the 1/1 lane's identical local for why this is hoisted (feeds the sent plan's `roles`). The
+    // 'unsigned' branch below returns before the sent `emit()`, so it never needs to set this.
+    let deployerAddr;
     if (lane === 'unsigned') {
         // cold lane: deterministic deploy makes the whole sequence pre-computable — the clone
         // address is a pure function of (factory, salt), so setup + mints target it up front.
@@ -4027,6 +4658,7 @@ export async function cmdDeployCodeBody(flags, emit) {
         const session = await openWalletSession({ chainKey: CHAIN, expectedSigner: flags.for, total: approvals, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             const { clone: predicted, txs } = await preparedFor(signer);
             // The scan floor is the clone-CREATION block (txs[0]) — NOT the last tx. A wallet session can
             // span blocks (deploy at N, setup+mint at N+2), and the `code` field is written in the deploy
@@ -4052,6 +4684,7 @@ export async function cmdDeployCodeBody(flags, emit) {
         // `signHotSequence` (signer.ts) / `makeHotSender` (sdk execute.ts) for the read-after-write-lag
         // reasoning this used to be a hand-rolled loop for.
         const { account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         const { clone: predicted, txs } = await preparedFor(account.address);
         const results = await signHotSequence(txs, { chainKey: CHAIN, yes: !!flags.yes });
         clone = predicted;
@@ -4087,6 +4720,39 @@ export async function cmdDeployCodeBody(flags, emit) {
         name,
         symbol,
         onChainUri,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: 'code',
+            lane,
+            transactions: { approvals, legs: planSetupLegs },
+            roles: {
+                signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null,
+                primaryPayee: flags['primary-payee'] ?? null,
+                minter: flags.minter ?? null,
+            },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: null, // see `surfaces.thumbnail`
+                backend: dirUpload ? dirUpload.backend.id : null,
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? metadataRenderer : null,
+                image: null, // see `surfaces.thumbnail`
+            },
+            mint: { deferred: mintCount === 0, count: mintCount, amountPerId: null, recipient: mintCount > 0 ? deployerAddr ?? null : null },
+            // Unlike the dry run, the sent path computes no cost estimate (the gas-guidance try/catch is
+            // dry-run-only — a real send just pays whatever `estimateGas` returns at signing time).
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: {
+                thumbnail: { ok: !imageOrphaned, detail: stripAnsiForPlan(imageDisposition) },
+                traits: { ok: !traitsBroken, detail: stripAnsiForPlan(traitsDisposition) },
+                postParams: { ok: !(undeclaredParams.length > 0 || paramsNudge), detail: stripAnsiForPlan(paramsDisposition) },
+            },
+            dependencies: { count: deps.length, registry: depRegistry ?? null },
+            resume: null,
+        },
     }));
     step('Index');
     await registerAndIndexLocally(clone, { 'from-block': deployBlock.toString(), factory, label: name });
@@ -4175,43 +4841,51 @@ export const DEPLOY_CODE_EDITION_FLAGS = new Set([
     'public-base-url', 'onchain-uri', 'generator', 'renderer', 'port',
     'sign', 'unsigned', 'for', 'salt', 'factory', 'bootstrap-factory', 'sign-url-file',
     'dry-run', 'confirm', 'yes', 'json', 'copies',
-    // v1-scope-cut flags: kept in the ALLOWLIST (not stray) so they reach this function's own
-    // pointed refusal below, rather than the generic "unrecognized flag" `refuseStrayFlags` would
-    // give them otherwise — a real but less helpful refusal (it doesn't say WHY, or the way out).
+    // storage (directory mode + --image-base's off-chain still) — mirrors storageOverrides(), same
+    // allowlist entries as the 721 twin's DEPLOY_CODE_FLAGS.
+    'code-dir', 'backend', 'endpoint', 'bucket', 'region', 'prefix', 'public-base', 'gateway', 'mode', 'api-url', 'upload-url', 'provider', 'storage-signer',
+    'ipfs-gateway', 'arweave-gateway',
+    // NOT scope cuts: --image-renderer/--attributes-renderer (on-chain field renderers) and
+    // --image-base (an off-chain deterministic-per-id still) are all fully wired on EditionCode —
+    // `abx help deploy-code` documents them as working. --dep/--dep-registry likewise: EditionCode
+    // inherits the same Dependencies extension, and the legs ride the same setup multicall.
+    'image-renderer', 'attributes-renderer', 'image-base', 'dep', 'dep-registry',
+    // v1-scope-cut flag: kept in the ALLOWLIST (not stray) so it reaches this function's own pointed
+    // refusal below, rather than the generic "unrecognized flag" `refuseStrayFlags` would give it
+    // otherwise — a real but less helpful refusal (it doesn't say WHY, or the way out).
     // (`resume` is NOT here: --resume + --copies is refused earlier, at cmdDeployCode's dispatch —
     // this function never runs with flags.resume set, so listing it here would just be dead.)
-    'code-dir', 'image-renderer', 'attributes-renderer', 'image-base', 'no-delegation',
-    // NOT scope cuts: --dep/--dep-registry are fully wired on EditionCode (it inherits the same
-    // Dependencies extension, and the legs ride the same setup multicall — see the Dependencies step
-    // below). They're plain supported flags; `abx help deploy-code` documents them as working.
-    'dep', 'dep-registry',
+    'no-delegation',
 ]);
 export async function cmdDeployEditionCodeBody(flags, emit) {
-    const usage = 'abx deploy-code --copies <n|open> --script <file> --name "Title" --symbol SYM (--public-base-url https://your.resolver.domain | --onchain-uri) ' +
+    beginPlanWarnings();
+    const usage = 'abx deploy-code --copies <n|open> (--script <file> | --code-dir <dir>) --name "Title" --symbol SYM (--public-base-url https://your.resolver.domain | --onchain-uri) ' +
         '[--description "<s>"] [--external-url <url>] [--max N] [--mint-count N | --mint-all] [--mint-amount N] ' +
         '[--schema key:Type:Auth,…] [--no-seed | --seed-source 0x..] [--unpaused] [--minter 0x..] [--primary-payee 0x..] [--royalty-bps N] [--721c recommended|0x..]';
     refuseStrayFlags(flags, DEPLOY_CODE_EDITION_FLAGS, 'deploy-code');
     warnSignWithoutFor(flags);
     const editionSize = parseCopies(flags.copies);
-    if (flags['code-dir']) {
-        throw new Error('--code-dir is not yet supported for edition code deploys (--copies) — use --script (on-chain chunks) instead. Tracked as a follow-up.');
-    }
-    // --image-base stays refused: unlike the renderer flags it is not a field write, it needs the
-    // effect runner's per-token still + the url-template's `{id}` substitution over an id SPACE rather
-    // than a token sequence. That port is real work; these two were not.
-    if (flags['image-base']) {
-        throw new Error('--image-base is not wired for edition code deploys (--copies) yet — it needs the effect runner to write a\n' +
-            '  still per id, which the edition lane does not drive. The two flags beside it DO work here:\n' +
-            '  `--image-renderer 0x.. --attributes-renderer 0x.. --onchain-uri` computes image + traits in Solidity, on\n' +
-            '  chain, with nothing to render or host. Otherwise use --public-base-url and a resolver.');
-    }
+    const scriptPath = flags.script;
+    const codeDir = flags['code-dir'];
+    if (scriptPath && codeDir)
+        throw new Error(usage);
     // The in-chain Solidity renderer lane, same as the 721 twin: EditionCode composes the same
     // OnChainMetadata extension and the same URI-renderer slots, so `image`/`attributes` at a
     // `renderer` representation resolve through the canonical metadata renderer with no server in the
     // graph. Proven end-to-end in contracts/test/EditionOnChainRender.t.sol.
     const imageRendererFlag = flags['image-renderer'] ? String(flags['image-renderer']) : undefined;
     const attributesRendererFlag = flags['attributes-renderer'] ? String(flags['attributes-renderer']) : undefined;
-    const hasProgram = !!flags.script;
+    // --image-renderer and --image-base both set the `image` field — pick ONE, same rule as the 721
+    // twin. Checked before either is resolved so the refusal is immediate rather than after a renderer
+    // code-presence probe.
+    if (imageRendererFlag && flags['image-base']) {
+        throw new Error('--image-renderer and --image-base both set the `image` field — pick ONE: an ON-CHAIN Solidity render (--image-renderer, no infra) OR an off-chain bucket URL (--image-base).');
+    }
+    // A JS program either way (template chunks or a hosted build) — same "hasProgram" test as the 721
+    // twin (see its own `const hasProgram = !!(scriptPath || codeDir);`), so every downstream
+    // conditional gated on it (generator resolution, animation_url, the on-chain-URI legs) already
+    // does the right thing for a directory build without a SEPARATE flag to thread through.
+    const hasProgram = !!(scriptPath || codeDir);
     const hasFieldRenderers = !!(imageRendererFlag || attributesRendererFlag);
     if (!hasProgram && !hasFieldRenderers) {
         throw new Error(`${usage}\n  (or, for a FULLY on-chain Solidity render with no program: --copies <n|open> --image-renderer 0x.. ` +
@@ -4373,11 +5047,30 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
             }
         }
     }
+    // Content: directory mode uploads the build (its root locator → the `code` collection field);
+    // template mode chunks the script for on-chain storage. The directory UPLOAD is deferred until
+    // after the --confirm gate (and skipped entirely on --dry-run) so a preview never pins bytes —
+    // same shape as the 721 twin's identical block (see its own comment for the full reasoning).
     step('Content');
     let scriptChunks = [];
+    let dirUpload = null;
     let contentSummary;
-    if (hasProgram) {
-        const source = readFileSync(resolvePath(flags.script), 'utf8');
+    if (codeDir) {
+        const dirPath = resolvePath(codeDir);
+        const files = readdirSync(dirPath).filter((f) => !f.startsWith('.') && statSync(joinPath(dirPath, f)).isFile());
+        if (!files.includes('index.html'))
+            throw new Error(`${dirPath} has no index.html — the directory entry, by convention`);
+        const backend = resolveBackend(storageOptions(storageOverrides(flags)));
+        if (!backend.putDirectory)
+            throw new Error(`storage backend '${backend.id}' has no directory upload — use --backend ipfs (pinata) or arweave`);
+        const entries = files.map((f) => ({ name: f, bytes: new Uint8Array(readFileSync(joinPath(dirPath, f))), contentType: contentTypeFromPath(joinPath(dirPath, f)) }));
+        dirUpload = { backend, entries, sizes: entries.map((e) => e.bytes.length) };
+        contentSummary = `${entries.length} file(s) → ${backend.id} directory (code field)`;
+        info(`${entries.length} file(s) from ${basename(dirPath)}/ → ${backend.id} directory (code field)`);
+        info(dim('the live view 302s through the gateway — it must serve HTML (the shared Pinata public gateway does not; use a dedicated gateway or arweave).'));
+    }
+    else if (scriptPath) {
+        const source = readFileSync(resolvePath(scriptPath), 'utf8');
         scriptChunks = planOnChainScript(source);
         contentSummary = `script ${Buffer.byteLength(source, 'utf8')} bytes → ${scriptChunks.length} on-chain chunk(s)`;
         ok(contentSummary);
@@ -4431,16 +5124,67 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     if (hasFieldRenderers && !onChainUri) {
         warn('--image-renderer/--attributes-renderer compute fields ON-CHAIN, but without --onchain-uri the URI renderers are never wired, so uri() still resolves through your resolver and nothing reads them. Add --onchain-uri.');
     }
+    // --image-base: bake the on-chain `image` as a url-template (`{base}/{id}.png`) — same field write
+    // as the 721 twin's identical block (see its own comment for the full reasoning), one id space
+    // finer: `{id}` substitutes the EditionCode id, not a sequential 721 token number, and the effect
+    // runner's render sweep already excludes an id with no live copies (harness.ts) — an id with no
+    // mint-time seed drawn yet has nothing to render FROM, the same reason a burned 721 token is
+    // excluded. There is no per-copy addressing: every copy of an id shares one image, same as every
+    // other field on an id.
+    if (flags['image-base']) {
+        const base = String(flags['image-base']);
+        // --image-base needs a mutable, path-addressed URL (the effect runner overwrites the SAME key in
+        // place) — a content-addressed gateway URL (ipfs/arweave) can't back a FIXED per-id address, no
+        // matter what THIS deploy's own --backend happens to be. One shared validator decides this
+        // (packages/storage/content-plan.ts), so this can never disagree with the 721 lane's own refusal.
+        const imageBaseCombo = validateRenderStorageCombo({ imageBaseUrl: base });
+        if (!imageBaseCombo.ok) {
+            if (dryRun)
+                warn(`would REFUSE — ${imageBaseCombo.reason}`);
+            else
+                throw new Error(imageBaseCombo.reason);
+        }
+        // NEVER bake a localhost/loopback image host on-chain — the token's `image` would resolve for no
+        // one. This is the marketplace still's PERMANENT address.
+        if (loopbackBaseUrl(base)) {
+            const m = `--image-base ${base} is localhost/loopback — the on-chain image URL would resolve for no marketplace. Use a PUBLIC bucket (S3/R2/CDN) you control.`;
+            if (dryRun)
+                warn(`would REFUSE — ${m}`);
+            else
+                throw new Error(m);
+        }
+        // The exact trap a real agent hit on the 721 lane: it baked the S3 API endpoint (auth-only) as
+        // --image-base. Refuse the R2 API form (never public); warn on the S3 API form.
+        if (/\.r2\.cloudflarestorage\.com/i.test(base)) {
+            const m = `--image-base ${base} is R2's S3 API endpoint (auth-only) — marketplaces get 403, it is NEVER public. Put THIS URL in ${bold('ABX_S3_ENDPOINT')} (uploads), and pass --image-base your bucket's PUBLIC read URL — enable an ${bold('r2.dev')} public URL (\`https://pub-<hash>.r2.dev\`) or a custom domain in the R2 dashboard.`;
+            if (dryRun)
+                warn(`would REFUSE — ${m}`);
+            else
+                throw new Error(m);
+        }
+        else if (/(^|\/\/)s3[.-][^/]*amazonaws\.com/i.test(base) || /\.s3[.-][^/]*amazonaws\.com/i.test(base)) {
+            warn(`--image-base ${base} looks like the S3 API host — marketplaces can read it ONLY if the bucket has public-read (or you front it with CloudFront/a domain). If it's not public, use that URL in ${bold('ABX_S3_ENDPOINT')} and pass a public URL here instead.`);
+        }
+        const imageTemplate = base.includes('{id}') ? base : `${base.replace(/\/+$/, '')}/{id}.png`;
+        contractFields.push({ field: encodeTag(F.image), representation: encodeTag(R.urlTemplate), value: toHex(imageTemplate) });
+        info(`collection image → on-chain url-template ${bold(imageTemplate)} ${dim('(off-chain thumbnail at a deterministic per-id URL; the effect runner overwrites each key once a copy is minted)')}`);
+        info(`  ${dim('the runner uploads stills here via')} ${bold('ABX_S3_ENDPOINT · ABX_S3_BUCKET · ABX_S3_ACCESS_KEY_ID · ABX_S3_SECRET_ACCESS_KEY')} ${dim('(set ABX_S3_PUBLIC_BASE to this same --image-base; `abx storage show` checks them; details → reference/hosting.md)')}`);
+        const s3Base = process.env.ABX_S3_PUBLIC_BASE?.replace(/\/+$/, '');
+        if (s3Base && !imageTemplate.startsWith(`${s3Base}/`)) {
+            warn(`--image-base isn't under ABX_S3_PUBLIC_BASE (${s3Base}) — the runner keys its deterministic publish off that base, so it won't auto-upload here unless they share an origin.`);
+        }
+    }
     const onchainUriLegs = onChainUri ? onchainUriSetupCalls({ generator, metadataRenderer }) : [];
     step('Deploy');
     const lane = laneFromFlags(flags);
     const minter = flags.minter ?? zeroAddress;
     const primaryPayee = flags['primary-payee'] ?? zeroAddress;
     const explicitSalt = parseSaltFlag(flags.salt);
-    // Always TWO transactions (deploy + one setup multicall) — this leaner lane skips the 721 code
-    // lane's "fold reserve mints + renderers into init" micro-optimization (only reachable there for
-    // a renderer-only, no-program drop, which this function refuses anyway — every edition-code
-    // deploy has a program).
+    // Normally TWO transactions (deploy + one gas-bounded setup batch) — this leaner lane skips the
+    // 721 code lane's "fold reserve mints + renderers into init" micro-optimization (only reachable
+    // there for a renderer-only, no-program drop, which this function refuses anyway — every
+    // edition-code deploy has a program). A setup large enough to miss the `eth_estimateGas` ceiling
+    // (a big script) splits into MORE than one setup transaction — see `planCodeSetupBatches`.
     const initParamsFor = (owner) => ({
         owner,
         name,
@@ -4466,53 +5210,52 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
         tokenFields: [],
         contractFields,
     });
-    const setupCallsFor = (owner) => {
-        const calls = [];
-        for (let i = 0; i < scriptChunks.length; i++) {
-            calls.push(encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), scriptChunks[i]] }));
-        }
-        for (const s of schemas) {
-            calls.push(encodeFunctionData({
-                abi: seriesCodeAbi,
-                functionName: 'setParamSchema',
-                args: [encodeTag(s.key), s.paramType, s.auth, s.authAddress, s.lockAfter, s.min, s.max, s.selectOptions],
-            }));
-        }
-        // Dependency legs, ordered (index 0 = the runtime) + the SOFT registry pointer when one resolved.
-        // Built by the SDK's shared `dependencySetupCalls` — the same function the 721 lane uses — so the
-        // two lanes can never encode `setDependency` differently.
-        calls.push(...dependencySetupCalls(deps, depRegistry));
-        calls.push(...onchainUriLegs);
-        // Reserve mints: one `mint(to, id, amount)` per premint id — the edition twin of the 721 lane's
-        // N identical `mint(owner)` calls, one id finer (a specific amount of copies, not just "one").
-        for (let id = 0; id < mintCount; id++) {
-            calls.push(encodeFunctionData({ abi: oneOfOneEditionAbi, functionName: 'mint', args: [owner, BigInt(id), mintAmount] }));
-        }
-        return calls;
-    };
+    // Gas-bounded setup-transaction legs — script chunks, schemas, deps, on-chain-URI wiring are all
+    // OWNER-INDEPENDENT (only a mint call's calldata embeds the owner+id+amount; its gas is a flat
+    // constant regardless), so they're built once, up front, and reused both to size
+    // `approvals`/`planSetupLegs` now and to build the real transactions in `preparedFor` below —
+    // identical `.gas` sequence ⇒ identical split (see `planCodeSetupBatches`'s own doc for why that
+    // can never drift).
+    const chunkLegs = scriptChunks.map((chunk, i) => chunkSetupLeg(i, chunk, encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), chunk] })));
+    const depCallsForEdition = dependencySetupCalls(deps, depRegistry);
+    const configLegs = [
+        ...schemas.map((s) => schemaSetupLeg(s.key, encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setParamSchema', args: [encodeTag(s.key), s.paramType, s.auth, s.authAddress, s.lockAfter, s.min, s.max, s.selectOptions] }))),
+        ...(depCallsForEdition.length ? [depsSetupLeg(depCallsForEdition)] : []),
+        ...(onchainUriLegs.length ? [uriSetupLeg(onchainUriLegs)] : []),
+    ];
+    // Reserve mints: one `mint(to, id, amount)` per premint id — the edition twin of the 721 lane's N
+    // identical `mint(owner)` calls, one id finer (a specific amount of copies, not just "one").
+    const mintLegsFor = (owner) => Array.from({ length: mintCount }, (_, id) => mintSetupLeg(encodeFunctionData({ abi: oneOfOneEditionAbi, functionName: 'mint', args: [owner, BigInt(id), mintAmount] })));
+    // `owner` is irrelevant to the batch SHAPE (see the comment above), so `zeroAddress` here is a
+    // placeholder used purely to size `approvals` before a deployer is known — never sent.
+    const editionSetupBatches = planCodeSetupBatches({ chunks: chunkLegs, config: configLegs, mints: mintLegsFor(zeroAddress) });
     const preparedFor = async (owner) => {
         const salt = explicitSalt ?? saltFor(owner);
         const clone = await predictClone(publicClient, { factory, salt });
-        const calls = setupCallsFor(owner);
-        const txs = [prepareDeployEditionCode({ factory, params: initParamsFor(owner), salt, chainId, clone })];
-        if (calls.length) {
-            txs.push(prepareCodeSetup({
-                contract: clone,
-                calls,
-                chainId,
-                chunkCount: scriptChunks.length,
-                chunkBytes: scriptChunks.map((h) => (h.length - 2) / 2),
-                schemaKeys: schemas.map((s) => s.key),
-                onchainUri: onChainUri,
-            }));
-        }
+        const setupTxs = codeSetupTxsFromBatches(planCodeSetupBatches({ chunks: chunkLegs, config: configLegs, mints: mintLegsFor(owner) }), { contract: clone, chainId, deps: deps.map((d) => d.display) });
+        const txs = [prepareDeployEditionCode({ factory, params: initParamsFor(owner), salt, chainId, clone }), ...setupTxs];
         return { clone, txs };
     };
-    // deps ride the same single setup multicall as chunks/schemas/mints, so they don't add an approval —
-    // but they must be COUNTED in the "is there a setup multicall at all" test, or a deps-only project
-    // (a script with no schemas and no premints) would report 1 approval and send 2 transactions.
-    const depLegCount = dependencySetupCalls(deps, depRegistry).length;
-    const approvals = 1 + (scriptChunks.length + schemas.length + depLegCount + onchainUriLegs.length + mintCount > 0 ? 1 : 0);
+    // deps ride the same setup batch as chunks/schemas/mints when everything fits one transaction, so
+    // they don't add an approval on their own — but they must be COUNTED in the "is there a setup
+    // transaction at all" test, or a deps-only project (a script with no schemas and no premints) would
+    // report 1 approval and send 2 transactions.
+    const depLegCount = depCallsForEdition.length;
+    const approvals = 1 + editionSetupBatches.length; // deploy tx + however many gas-bounded setup batches
+    // Ordered legs riding the setup (if any) — GROUP names, not a literal per-transaction count (see
+    // deploy-plan.ts's own doc comment on `legs`); same booleans `approvals` above is built from, so the
+    // plan object's `transactions.legs` can never drift from the tx(es) the wallet actually signs.
+    // Always ends with `'deploy'` when non-null.
+    const planSetupLegs = approvals > 1
+        ? [
+            scriptChunks.length ? 'chunks' : null,
+            schemas.length ? 'param-schemas' : null,
+            depLegCount ? 'dependencies' : null,
+            onchainUriLegs.length ? 'onchain-uri' : null,
+            mintCount ? 'mints' : null,
+            'deploy',
+        ].filter((leg) => leg !== null)
+        : null;
     if (!dryRun) {
         await confirmSend(
         // Second site of the same missing binding as the plan line above — and the worse one: this is
@@ -4551,18 +5294,70 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
         printSeedSourcePlan(seedSource, chainId);
         info(`PostParam schema(s): ${schemas.length ? schemas.map((s) => describeSchema(s)).join(', ') : 'none'}`);
         info(`mint: ${mintCount > 0 ? `${mintCount} id(s) × ${mintAmount} cop${mintAmount === 1n ? 'y' : 'ies'} → ${deployer ?? 'your wallet'} at deploy` : 'deferred (mint later / external minter)'}`);
-        info(`transactions: 2 — deploy + setup multicall (${[scriptChunks.length ? 'script chunks' : null, schemas.length ? 'schemas' : null, onChainUri ? 'on-chain URI wiring' : null, mintCount > 0 ? 'reserve mints' : null].filter(Boolean).join(' + ') || 'nothing else'})`);
+        info(`transactions: ${approvals} — deploy + ${editionSetupBatches.length} setup ${editionSetupBatches.length === 1 ? 'transaction' : 'transactions (gas-bounded)'} ` +
+            `(${[scriptChunks.length ? 'script chunks' : null, schemas.length ? 'schemas' : null, onChainUri ? 'on-chain URI wiring' : null, mintCount > 0 ? 'reserve mints' : null].filter(Boolean).join(' + ') || 'nothing else'})`);
         info(`approvals   ${approvals} wallet approval(s)`); // parity with the 721 code twin — it had this only in the --confirm sentence
         if (!explicitSalt && deployer) {
             console.log(`\n  ${bold('salt')}  ${g(salt)}`);
             info(`address: pinned by salt — re-run with ${bold(`--salt ${salt}`)} (same address).`);
         }
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent.')}\n`);
-        emit(jsonSafe({ command: 'deploy-code', kind: 'edition-code', copies: editionSize.toString(), dryRun: true, sent: false, address: shownAddr, chain: CHAIN, chainId, factory, name, symbol }));
+        emit(jsonSafe({
+            command: 'deploy-code', kind: 'edition-code', copies: editionSize.toString(), dryRun: true, sent: false, address: shownAddr, chain: CHAIN, chainId, factory, name, symbol,
+            plan: {
+                schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+                family: 'code-edition',
+                lane,
+                transactions: { approvals, legs: planSetupLegs },
+                roles: {
+                    signer: deployer, owner: deployer, royaltyReceiver: deployer,
+                    primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                    minter: minter !== zeroAddress ? minter : null,
+                },
+                royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+                custody: {
+                    onChainUri,
+                    imageOnChain: null, // this lane has no surfaces block (see deploy-plan.ts); a field-renderer image is still `hasFieldRenderers` in the prose, not tracked here
+                    backend: dirUpload ? dirUpload.backend.id : null,
+                    tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                    contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                    renderer: onChainUri ? metadataRenderer : null,
+                    image: null, // no single --image file on this lane (see custody.image's own doc comment)
+                },
+                mint: {
+                    deferred: mintCount === 0,
+                    count: mintCount,
+                    amountPerId: mintAmount.toString(),
+                    recipient: mintCount > 0 ? deployer : null,
+                },
+                estimate: { ethApprox: null, gasApprox: null }, // this lane computes no cost estimate
+                warnings: planWarnings.slice(),
+                surfaces: null, // only the fresh 721 code lane computes the per-surface disposition today
+                dependencies: { count: deps.length, registry: depRegistry ?? null },
+                resume: null,
+            },
+        }));
         return;
     }
+    // Real deploy: perform the deferred directory upload now (past the confirm gate). `contractFields`
+    // is captured by reference in `initParamsFor` above — pushing to it here still lands in the CREATE
+    // tx's init params, since that closure isn't actually CALLED until the signing lane below runs.
+    if (dirUpload) {
+        const { base } = await dirUpload.backend.putDirectory(dirUpload.entries);
+        // Store the BARE locator (CID / arweave txid), never a full gateway URL — the resolver applies
+        // the gateway at serve time per `representation`.
+        const ipfsCid = base.match(/\/ipfs\/([^/]+)/)?.[1];
+        const arTxid = base.match(/arweave\.net\/([^/?#]+)/i)?.[1];
+        const rep = ipfsCid ? 'ipfs' : dirUpload.backend.id === 'arweave' ? 'arweave' : 'url';
+        const value = ipfsCid ?? (rep === 'arweave' ? (arTxid ?? base) : base);
+        contractFields.push({ field: encodeTag('code'), representation: encodeTag(rep), value: toHex(value) });
+        ok(`uploaded ${dirUpload.entries.length} file(s) → code field (${rep}): ${value}`);
+    }
     let clone;
     let deployBlock;
+    // See the 1/1 lane's identical local for why this is hoisted (feeds the sent plan's `roles`). The
+    // 'unsigned' branch below returns before the sent `emit()`, so it never needs to set this.
+    let deployerAddr;
     if (lane === 'unsigned') {
         const signer = flags.for;
         if (!signer)
@@ -4577,6 +5372,7 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
         const session = await openWalletSession({ chainKey: CHAIN, expectedSigner: flags.for, total: approvals, port: flags.port ? Number(flags.port) : undefined, signUrlFile: flags['sign-url-file'] });
         try {
             const signer = await session.connect();
+            deployerAddr = signer;
             const { clone: predicted, txs } = await preparedFor(signer);
             let first;
             for (const tx of txs) {
@@ -4593,6 +5389,7 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     }
     else {
         const { account } = makeWalletClient({ chainKey: CHAIN });
+        deployerAddr = account.address;
         const { clone: predicted, txs } = await preparedFor(account.address);
         const results = await signHotSequence(txs, { chainKey: CHAIN, yes: !!flags.yes });
         clone = predicted;
@@ -4606,7 +5403,41 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     info(`permanent: max ${max} id(s) · royalty ${royaltyBps / 100}%${flags['royalty-bps'] === undefined ? ' ⚠ default' : ''} → the deploying wallet` +
         ` · cap ${maxRoyaltyBps / 100}%${burnable ? ' · burnable' : ''}` +
         dim('  (rate is changeable with `abx set-royalty`; the CAP only ever goes down)'));
-    emit(jsonSafe({ command: 'deploy-code', kind: 'edition-code', copies: editionSize.toString(), address: clone, chain: CHAIN, chainId, factory, deployBlock, name, symbol, onChainUri }));
+    emit(jsonSafe({
+        command: 'deploy-code', kind: 'edition-code', copies: editionSize.toString(), address: clone, chain: CHAIN, chainId, factory, deployBlock, name, symbol, onChainUri,
+        plan: {
+            schemaVersion: DEPLOY_PLAN_SCHEMA_VERSION,
+            family: 'code-edition',
+            lane,
+            transactions: { approvals, legs: planSetupLegs },
+            roles: {
+                signer: deployerAddr ?? null, owner: deployerAddr ?? null, royaltyReceiver: deployerAddr ?? null,
+                primaryPayee: primaryPayee !== zeroAddress ? primaryPayee : null,
+                minter: minter !== zeroAddress ? minter : null,
+            },
+            royalty: { bps: royaltyBps, capBps: maxRoyaltyBps, burnable },
+            custody: {
+                onChainUri,
+                imageOnChain: null,
+                backend: dirUpload ? dirUpload.backend.id : null,
+                tokenUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/t`,
+                contractUriBase: onChainUri && !hasPublicUrl ? null : `${baseUrl}/c`,
+                renderer: onChainUri ? metadataRenderer : null,
+                image: null,
+            },
+            mint: {
+                deferred: mintCount === 0,
+                count: mintCount,
+                amountPerId: mintAmount.toString(),
+                recipient: mintCount > 0 ? deployerAddr ?? null : null,
+            },
+            estimate: { ethApprox: null, gasApprox: null },
+            warnings: planWarnings.slice(),
+            surfaces: null,
+            dependencies: { count: deps.length, registry: depRegistry ?? null },
+            resume: null,
+        },
+    }));
     step('Index');
     await registerAndIndexLocally(clone, { 'from-block': deployBlock.toString(), factory, label: name });
     if (onChainUri) {
@@ -4634,6 +5465,11 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     console.log(`  ${bold(`abx mint ${clone} --token-id <id> --amount <n>`)}  ${dim('# mint more copies of an id')}`);
     console.log(`  ${bold(`abx minter configure ${clone} --token-id <id> --price <eth> --allocation <n>`)}  ${dim('# set up a priced sale for one id')}`);
     console.log(`  ${bold(`abx refresh ${clone}`)}  ${dim('# nudge marketplaces once metadata is live')}\n`);
+    // Same Arweave-propagation caveat as the 721 twin (see its own comment): the gateway 404s until
+    // Turbo settles the bundle, so a render run right after deploy correctly finds nothing servable yet.
+    if (dirUpload?.backend.id === 'arweave') {
+        console.log(`\n  ${c.orange}⚠${c.reset} ${bold('Arweave upload propagates with a delay.')} ${dim('Turbo settles the bundle over minutes (sometimes longer); until then the gateway 404s, so the live view and a render will fail. A render run now correctly reports the content is not servable yet and stores NOTHING (not a garbage 404 thumbnail) — this is expected. Re-run the render once the content is live (the effects service will pick it up on its next sweep).')}`);
+    }
 }
 /**
  * Resolve `--721c` into the InitParams `transferValidator`. Absent → `zeroAddress`: a plain