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

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, 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');
@@ -978,6 +998,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 +1059,39 @@ 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'] : 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,
+                },
+                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 +1100,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 +1138,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 +1171,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 +1196,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 +1210,32 @@ 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'] : 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`,
+            },
+            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 +1369,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
@@ -1487,6 +1573,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 +1619,41 @@ 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'] : 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,
+                },
+                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 +1684,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 +1704,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 +1716,34 @@ 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'] : 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`,
+            },
+            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 +1813,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 +2216,46 @@ 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)'] : 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,
+                },
+                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 +2282,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 +2308,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 +2331,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 +2349,34 @@ 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)'] : 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`,
+            },
+            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 +2452,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 +2772,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 +2813,44 @@ 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)'] : 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,
+                },
+                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 +2879,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 +2897,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 +2909,39 @@ 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)'] : 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`,
+            },
+            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 +3197,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 = [
@@ -2981,6 +3263,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 +3287,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';
@@ -3458,6 +3751,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.
@@ -3494,6 +3791,18 @@ export async function cmdDeployCodeBody(flags, emit) {
     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)
+    // Ordered legs riding that setup multicall (if any), for the plan object's `transactions.legs` —
+    // the SAME booleans `setupLen`/`setupBits` (the dry-run's own `transactions:` line, below) already
+    // use, so this can't drift from the tx the wallet actually signs.
+    const planSetupLegs = setupLen > 0
+        ? [
+            scriptChunks.length ? 'chunks' : null,
+            schemas.length ? 'param-schemas' : null,
+            depLegs ? 'dependencies' : null,
+            onchainUriLegs ? 'onchain-uri' : null,
+            setupMintCount ? 'mints' : null,
+        ].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)
@@ -3616,6 +3925,9 @@ export async function cmdDeployCodeBody(flags, emit) {
         // 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 +3944,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 +3988,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 +4081,43 @@ 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`,
+                },
+                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).
@@ -3894,36 +4242,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,16 +4289,78 @@ 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,
+            custody: { onChainUri, imageOnChain: null, backend: null, tokenUriBase: null, contractUriBase: 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;
         }
@@ -3961,6 +4374,15 @@ export async function cmdDeployCodeBody(flags, emit) {
             deps: plan.sending.deps ? deps.map((d) => d.display) : [],
             onchainUri: plan.sending.uri,
         });
+        // A resume always sends its missing legs as ONE setup-multicall tx — one wallet approval — so
+        // `transactions.legs` names WHICH groups ride it, from the same `plan.sending` flags that build
+        // the tx above (never re-derived).
+        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
@@ -3968,14 +4390,30 @@ export async function cmdDeployCodeBody(flags, emit) {
         // any other, so it takes the identical gate (the preview also gains the `to`/`owner` lines
         // `runWrite`'s preview always printed).
         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: 1, 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 }));
+            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: 1, legs: resumeLegs },
+                    estimate: { ethApprox: null, gasApprox: null },
+                    resume: { target, sentLegs: plan.calls.length, complete: false },
+                },
+            }));
             return;
         }
         ok(`${tx.summary}`);
@@ -3985,6 +4423,7 @@ export async function cmdDeployCodeBody(flags, emit) {
         const resumedFloor = (await discoverDeployBlock(publicClient, target)) ?? result.blockNumber;
         emit(jsonSafe({
             command: 'deploy-code',
+            kind: isEdition ? 'edition-code' : 'code',
             resumed: target,
             address: target,
             chain: CHAIN,
@@ -3994,15 +4433,33 @@ export async function cmdDeployCodeBody(flags, emit) {
             complete: true,
             sentLegs: plan.calls.length,
             txHash: result.txHash,
+            plan: {
+                ...resumePlanBase,
+                transactions: { approvals: 1, 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 +4484,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 +4510,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 +4546,37 @@ 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`,
+            },
+            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 +4665,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 +4871,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,6 +4948,56 @@ 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);
@@ -4513,6 +5080,17 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     // (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);
+    // Ordered legs riding the setup multicall (if any) — same booleans `approvals` above uses, so the
+    // plan object's `transactions.legs` can never drift from the tx the wallet actually signs.
+    const planSetupLegs = approvals > 1
+        ? [
+            scriptChunks.length ? 'chunks' : null,
+            schemas.length ? 'param-schemas' : null,
+            depLegCount ? 'dependencies' : null,
+            onchainUriLegs.length ? 'onchain-uri' : null,
+            mintCount ? 'mints' : null,
+        ].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
@@ -4558,11 +5136,60 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
             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`,
+                },
+                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 +5204,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 +5221,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 +5235,39 @@ 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`,
+            },
+            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 +5295,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