@artblocks/abx-cli 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/main.js

@@ -17,12 +17,14 @@
  *   abx preview              run a code project on localhost while it's still being made (no chain)
  *   abx deploy-code          deploy a code project (SeriesCode): --script <file> (on-chain template)
  *                            or --code-dir <dir> (build directory → ipfs/arweave `code` field)
+ *                            --resume <addr>: finish one whose setup tx failed (sends only what's missing)
  *   abx add <address>        register + index a project (--remote <name|url>: on a remote resolver, not this machine)
  *   abx remote [<name|url>]  inspect a remote service (descriptor · chains · managed rendering · your projects there)
  *   abx index [<address>]    re-index a project from chain (replay; --remote to nudge a remote resolver)
  *   abx verify <address>     re-hash served bytes vs the on-chain commitment (no server)
  *   abx tokenuri <address>   read tokenURI(id) from the contract + decode  ·  contracturi: the ERC-7572 collection JSON
  *                            (the contract holds the URL — never hand-build a resolver path)
+ *   abx tokens <address>     every token's owner + seed + params, from chain alone (--json for the machine path)
  *   abx configure-param <addr> <id> <key> <value>  set a governed PostParam (typed encode; any lane)
  *   abx set-param-hooks <addr>  wire/clear a SeriesCode's configure/augment/transfer param hooks
  *   abx render <addr> [id…]  effect-runner repair lane: render missing stills/traits
@@ -34,6 +36,7 @@
  *   abx migrate <addr>       move a contract's off-chain state to another resolver (--from/--to)
  *   abx set-token-uri <addr> · set-contract-uri · set-royalty · set-field · lock-field
  *   abx storage show         show byte custody (fs | cloud | ipfs | arweave); stateless — choose per command with flags
+ *   abx storage status <loc>  is a locator RETRIEVABLE yet, not just accepted? (Arweave propagation is minutes)
  *   abx storage balance|topup  Turbo (arweave) upload credits — view / buy by card (credits attach to the signing identity)
  *   abx storage backup-key   copy the managed Turbo/Arweave key (holds credits) to a safe path
  *   abx status               list indexed projects + node info
@@ -55,14 +58,18 @@ import { effectsArtifact, resolverArtifact } from './provision.js';
 import { mintPageArtifact, PUBLIC_RPC } from './mintpage.js';
 import { formatEther, toHex, zeroAddress } from 'viem';
 import { encodeFunctionData } from 'viem';
-import { DEP_RESOLUTION, deploySeedSource, deploySeriesCodeFactory, prepareCodeSetup, prepareDeploySeriesCode, resolveGenerator, resolveSeedSource, resolveSeriesCodeFactory, seriesCodeAbi, readParamSchema, seriesCodeFactoryAbi, } from '@artblocks/abx-sdk';
+import { AUTH_OPTIONS, DEP_RESOLUTION, PARAM_TYPES, deploySeedSource, deploySeriesCodeFactory, listTokens, prepareCodeSetup, prepareDeploySeriesCode, resolveGenerator, resolveSeedSource, resolveSeriesCodeFactory, seriesCodeAbi, readParamSchema, seriesCodeFactoryAbi, } from '@artblocks/abx-sdk';
 import { checkRegistryDeps, dependencySetupCalls, parseDepFlag, resolveDepRegistryPointer } from './deps.js';
 import { expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport, readLegacyParamsKeys, readParamSchemaKeys, readSetParamKeys, } from './onchain-uri.js';
-import { parseFlags, unknownFlags } from './flags.js';
+import { parseFlags, positionalArgs, unknownFlags } from './flags.js';
 import { AGENT_SKILL_PARENTS, checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, readSkillVersion, SKILL_DIR_NAME, } from './update-check.js';
 import { analyzeScript, recommendLane } from './inspect.js';
 import { previewConfigFromFlags, previewDepTags, parsePreviewParams, shootPreview, startPreviewServer, DEFAULT_PREVIEW_PORT, PREVIEW_FLAGS } from './preview.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
+import { copyRendererScaffold } from './scaffold.js';
+import { jsonSafe, withJson } from './jsonout.js';
+import { fetchServedTokenUri, prettyBody, servedOk } from './served.js';
+import { planResume } from './resume.js';
 import { declinesSkillInstall } from './prompt.js';
 import { pinGas, waitForCodeAt } from './gas.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
@@ -77,7 +84,7 @@ import { uploadAndLocate } from './upload.js';
 import { assertChainId, discoverDeployBlock, deployFactory, deploySeriesFactory, deploySeries, deployOneOfOne, deployRenderer, predictRenderer, predictSeedSource, encodeTag, encodeFieldRenderer, isCodeProject, loadDotEnv, makePublicClient, makeWalletClient, oneOfOneImageAbi, oneOfOneImageFactoryAbi, seriesImageAbi, seriesImageFactoryAbi, abxMetadataRendererAbi, predictClone, probeRpcEndpoints, prepareDeployOneOfOne, prepareDeploySeries, reconstructProject, saltFor, saltGuard, resolveChain, resolveRpcUrl, redactRpcUrl, explorerUrl, DEFAULT_CHAIN_KEY, KNOWN_CHAIN_KEYS, normalizeAttributes, parseTraitPairs, resolveRecommendedTransferValidator, CREATOR_TOKEN_INTERFACE_ID, METADATA_FIELD as F, METADATA_REPRESENTATION as R, indexProgress, isAccepted, AbxIndexTimeoutError, AbxServiceError, } from '@artblocks/abx-sdk';
 import { SelfHostIndexer, SqliteStore } from '@artblocks/abx-indexer';
 import { artContentHash, currentRenderArtifact, generateArt, resolveBaseUrl, startChainWatcher, startTokenApiServer, verifyProject, watchIntervalMs, DEFAULT_PORT, } from '@artblocks/abx-token-api';
-import { ARWEAVE_FREE_UPLOAD_LIMIT, arweaveAddress, arweaveFunding, contentTypeFromPath, hashContent, resolveBackend, turboBalanceForAddress, turboUploadCostUsd, turboUploadWinc } from '@artblocks/abx-storage';
+import { ARWEAVE_FREE_UPLOAD_LIMIT, arweaveAddress, arweaveFunding, contentTypeFromPath, hashContent, locatorStatus, resolveBackend, turboBalanceForAddress, turboUploadCostUsd, turboUploadWinc } from '@artblocks/abx-storage';
 import { cmdTransfer, cmdMint, cmdSetMinter, cmdSetMaxInvocations, cmdConfigureParam, cmdSetSchema, cmdRetireParam, cmdSetParamHooks, cmdSetDependency, cmdRemoveLastDependency, cmdSetDependencyRegistry, cmdLockDependencies, cmdSetPrimaryPayee, cmdPause, cmdUnpause, cmdRefresh, cmdSetTokenUri, cmdSetContractUri, cmdSetRoyalty, cmdSetTransferValidator, cmdSetField, cmdAttach, parseTransferValidatorValue, cmdLockField, cmdSetRenderer, cmdLockUri, cmdSetAdmin, cmdMinterConfigure, cmdMinterShow, cmdMinterBuy, computeContentPlan, envStagingSender, laneFromFlags, ONCHAIN_PROJECT_SOFT_LIMIT, parseCompress, previewImageStaging, sessionStagingSender, stageImageField, stageImageFieldsBatch, authorshipContractFields, AUTHORSHIP_DEPLOY_FIELDS, } from './ownerops.js';
 import { openWalletSession, signTx } from './signer.js';
 import { describeRemoteError, listConfiguredRemotes, misnamedRemoteVars, requireRemoteToken, resolveRemote, serviceClient, tokenSourceLabel } from './remote.js';
@@ -161,9 +168,16 @@ async function maybeNotifyUpdate(flags) {
         }
         const latest = await checkForCliUpdate(current);
         if (latest) {
+            // The notes pointer must RESOLVE. This printed github.com/ArtBlocks/abx/releases, which 404s
+            // for everyone outside the org (the repo is private) — so a tester reconstructed the diff by
+            // running the same dry run on both versions, which is how they discovered the canonical
+            // singletons had moved and then had no way to tell whether that needed them to act. The
+            // packaged CHANGELOG.md ships with every install (see package.json `files`) and carries the
+            // real per-release notes, so it's readable offline and always matches the version you have.
             console.error(`\n    ${c.orange}⚠${c.reset}  update available: ${bold('abx')} ${dim(current)} → ${g(latest)}\n` +
                 `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx @artblocks/abx-cli@latest <command>')}\n` +
-                `       release notes: https://github.com/ArtBlocks/abx/releases ${dim('· silence: ABX_NO_UPDATE_CHECK=1')}\n`);
+                `       release notes: ${g('abx changelog')} ${dim('(ships with the CLI) · all versions: https://www.npmjs.com/package/@artblocks/abx-cli?activeTab=versions')}\n` +
+                `       ${dim('silence: ABX_NO_UPDATE_CHECK=1')}\n`);
         }
     }
     catch {
@@ -212,13 +226,15 @@ async function main() {
         case 'inspect': return cmdInspect(rest[0], flags);
         case 'preview': return cmdPreview(flags);
         case 'scaffold-renderer': return cmdScaffoldRenderer(rest, flags);
+        case 'changelog': return cmdChangelog(flags);
         case 'predict': return cmdPredict(flags);
         case 'add': return cmdAdd(rest[0], flags);
         case 'index': return cmdIndex(rest[0], flags);
         case 'verify': return cmdVerify(rest[0], flags);
         case 'render': return cmdRender(rest[0], rest.slice(1), flags);
         case 'effects': return cmdEffects(flags);
-        case 'tokenuri': return cmdTokenUri(rest[0], flags);
+        case 'tokenuri': return cmdTokenUri(rest[0], flags, rest.slice(1));
+        case 'tokens': return cmdTokens(rest[0], flags);
         case 'contracturi': return cmdContractUri(rest[0], flags);
         case 'serve': return cmdServe(flags);
         // owner operations — write + sign (hot/wallet/cold lane), then re-index
@@ -1152,6 +1168,11 @@ async function remoteLocators(address, stored, flags) {
 }
 // ── deploy (+ optionally serve) ──────────────────────────────────────────────
 async function cmdDeploy(flags, serveAfter) {
+    // `--json`: the deployed ADDRESS is the value a program came for (B19). Narration goes to stderr,
+    // so `ADDR=$(abx deploy … --json | jq -r .address)` works without parsing a success banner.
+    return withJson(flags, async (emit) => cmdDeployBody(flags, serveAfter, emit));
+}
+async function cmdDeployBody(flags, serveAfter, emit) {
     refuseStrayFlags(flags, DEPLOY_FLAGS, 'deploy');
     warnSignWithoutFor(flags);
     const dimension = resolveDimension(flags.type ?? '1of1');
@@ -1202,6 +1223,8 @@ async function cmdDeploy(flags, serveAfter) {
                 `  Nothing was deployed. Stop that one (Ctrl-C), or run this on another port: \`abx demo --port ${wanted + 1}\`.`);
         }
     }
+    // (demo keeps its own message: "Nothing was deployed" is the load-bearing part here, and it must
+    // be true — this check runs before anything irreversible. assertPortFree covers serve/preview.)
     const dryRun = !serveAfter && !!flags['dry-run']; // preview only — no send, no custody, no factory deploy
     // A keyless preview needs `--for` (the address is a pure function of factory+salt+deployer). Check
     // it HERE, before the trust-anchor/content/plan steps print — hitting this after a wall of output
@@ -1516,6 +1539,10 @@ async function cmdDeploy(flags, serveAfter) {
         // values — nothing is added, inferred, or substituted between here and the on-chain tx.
         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`);
+        // A dry run DOES know the address (it is a pure function of factory+salt), so --json reports it
+        // with `sent: false` rather than nothing. Note `saltPinned`: without --salt a real re-run
+        // reserves a fresh salt and lands elsewhere, so a caller must not treat this as reserved.
+        emit(jsonSafe({ command: 'deploy', dryRun: true, sent: false, address: predicted, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
         return;
     }
     // opt-in --confirm: a final y/N before the real send (no-op without --confirm; never blocks scripts)
@@ -1629,6 +1656,9 @@ async function cmdDeploy(flags, serveAfter) {
         blockNumber = result.blockNumber;
         ok(`deployed ${clone}`);
     }
+    // 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 }));
     step(serveAfter ? 'What the chain knows now' : 'Index it — replay the event spine from chain');
     const indexer = new SelfHostIndexer();
     // Off-chain traits ride in the registration (on-chain ones are already in the contract fields).
@@ -1764,6 +1794,9 @@ const tokenFieldOf = (tokenId, f) => ({
     value: f.value,
 });
 async function cmdDeploySeries(flags) {
+    return withJson(flags, async (emit) => cmdDeploySeriesBody(flags, emit));
+}
+async function cmdDeploySeriesBody(flags, emit) {
     refuseStrayFlags(flags, DEPLOY_SERIES_FLAGS, 'deploy-series');
     warnSignWithoutFor(flags);
     const name = flags.name ?? 'ABX Series';
@@ -2104,6 +2137,7 @@ async function cmdDeploySeries(flags) {
             console.log(`      ${bold(deploySeriesCommandLine(flags, salt))}`);
         }
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent, no bytes stored.')}\n`);
+        emit(jsonSafe({ command: 'deploy-series', dryRun: true, sent: false, address: predicted, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt, saltPinned: !!explicitSalt, name, symbol }));
         return;
     }
     let clone;
@@ -2198,6 +2232,7 @@ async function cmdDeploySeries(flags) {
         blockNumber = result.blockNumber;
         ok(`deployed ${clone}`);
     }
+    emit(jsonSafe({ command: 'deploy-series', address: clone, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, deployBlock: blockNumber, name, symbol }));
     step('Index it — replay the event spine from chain');
     const indexer = new SelfHostIndexer();
     const baseReg = {
@@ -2881,6 +2916,21 @@ async function walkthroughReadBack(state, baseUrl, onChainUri) {
     }
     console.log(`    ${dim('prove the bytes match the chain:')} ${bold(`abx verify ${state.address}`)}`);
 }
+/**
+ * Refuse a port that's already bound, with a formatted one-liner naming the port and the fix.
+ *
+ * Without this, `listen()` has no `'error'` handler and EADDRINUSE reaches Node's default handler:
+ * the creator gets a raw stack trace through `node:net` and our own `dist/` paths, which reads as a
+ * crash inside abx rather than "something else is on this port" — and it's the one unformatted error
+ * surface in a CLI where every other error is formatted. `preview`'s default port colliding with a
+ * studio left running in another terminal was reported as especially hard to diagnose.
+ */
+async function assertPortFree(port, cmd) {
+    if (!(await portInUse(port)))
+        return;
+    throw new Error(`port ${port} is already in use — most likely an \`abx ${cmd}\`/\`abx serve\`/\`abx preview\` still running in another terminal.\n` +
+        `  Stop that one (Ctrl-C), or run this on a different port: \`abx ${cmd} --port ${port + 1}\`.`);
+}
 /** Is a TCP port already bound on localhost? Used to preflight a serve BEFORE spending a tx. */
 async function portInUse(port) {
     const { createServer } = await import('node:net');
@@ -2957,7 +3007,11 @@ async function cmdPreview(flags) {
     if (cfg.deps.some((d) => d.display.startsWith('0x'))) {
         warn('an on-chain data-contract dep is NOT loaded in preview — the sketch will run without it here. Use a name@version ref to preview against the CDN copy.');
     }
-    const server = await startPreviewServer(cfg, shootDir ? 0 : Number(flags.port ?? DEFAULT_PREVIEW_PORT));
+    // `--shoot` takes an ephemeral port (0), so only the studio lane can collide.
+    const previewPort = shootDir ? 0 : Number(flags.port ?? DEFAULT_PREVIEW_PORT);
+    if (previewPort !== 0)
+        await assertPortFree(previewPort, 'preview');
+    const server = await startPreviewServer(cfg, previewPort);
     if (shootDir) {
         step(`Render ${count} seeds headlessly`);
         try {
@@ -3115,12 +3169,15 @@ const DEPLOY_CODE_FLAGS = new Set([
     'sign', 'unsigned', 'for', 'salt', 'factory', 'bootstrap-factory', 'sign-url-file',
     // preview / confirm
     'dry-run', 'confirm', 'yes',
+    'json', // B19: the deployed ADDRESS as data, narration to stderr
+    'resume', // B15: finish an EXISTING contract whose setup tx never landed (no deploy)
 ]);
 // Storage + signing + preview flags shared by every deploy path (mirrors storageOverrides() + the lanes).
 const SHARED_DEPLOY_FLAGS = [
     'backend', 'endpoint', 'bucket', 'region', 'prefix', 'public-base', 'gateway', 'mode', 'api-url', 'upload-url', 'provider', 'storage-signer',
     'sign', 'unsigned', 'for', 'sign-url-file', 'dry-run', 'confirm', 'yes', 'salt', 'factory', 'bootstrap-factory', 'port', 'renderer', 'public-base-url',
     '721c', // opt-in ERC-721C enrollment (recommended | 0x…) — every deploy path takes it
+    'json', // B19: the deployed ADDRESS as data, narration to stderr — every deploy path takes it
 ];
 // A 1/1 `abx deploy` accepts these (see `abx help deploy`). Anything else warns (typo'd/unsupported).
 const DEPLOY_FLAGS = new Set([
@@ -3196,6 +3253,9 @@ function warnSignWithoutFor(flags) {
     }
 }
 async function cmdDeployCode(flags) {
+    return withJson(flags, async (emit) => cmdDeployCodeBody(flags, emit));
+}
+async function cmdDeployCodeBody(flags, emit) {
     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..] ' +
@@ -3690,7 +3750,11 @@ async function cmdDeployCode(flags) {
     }
     // --dry-run: emit the full plan (the on-chain values the skill formats into its confirm table),
     // then stop — no upload, no factory/seed deploy, no send.
-    if (dryRun) {
+    //
+    // `--resume` skips this preview entirely and previews its OWN plan further down. Without the guard,
+    // `--resume 0xLive --dry-run` printed a fresh-deploy plan complete with a newly-reserved salt and a
+    // different predicted address — a preview of the exact thing the flag exists not to do.
+    if (dryRun && flags.resume === undefined) {
         // The deployer is needed ONLY to derive the CREATE2 salt → the deterministic address (and the
         // pinned-salt re-run line). Everything else in the plan — content, deps, chain-complete
         // expectation, tx count, cost — is deployer-independent, so a wallet-less creator (the common
@@ -3800,7 +3864,13 @@ async function cmdDeployCode(flags) {
         catch { /* gas pricing unavailable — cost guidance is a bonus, skip silently */ }
         // ── Surfaces — every marketplace-facing dimension, resolved NOW (none is backfillable) ──────
         const renderHome = process.env.ABX_STORAGE_BACKEND || 'fs'; // empty string counts as unset (=fs)
-        const anySurfaceBroken = imageOrphaned || traitsBroken || undeclaredParams.length > 0;
+        // A surface is BROKEN only when it resolves to nothing a marketplace can see. A dropped param is
+        // NOT that: the token still renders, the param just takes its default. Folding it in here made
+        // the block contradict itself two lines apart — "thumbnail: ON-CHAIN ✓ / traits: on-chain ✓"
+        // followed by "one or more surfaces resolve to NOTHING", re-recommending the very flags that
+        // were already set. The alarm now covers only the surfaces it can honestly speak for, and names
+        // only the remedies for what is actually broken.
+        const anySurfaceBroken = imageOrphaned || traitsBroken;
         step('Surfaces — what marketplaces will see (all DEPLOY-TIME; not backfillable)');
         (imageOrphaned ? warn : info)(`thumbnail: ${imageDisposition}`);
         // Render-mode / render-home guidance is for the RENDERED-still lanes only. The in-chain
@@ -3818,12 +3888,25 @@ async function cmdDeployCode(flags) {
         (traitsBroken ? warn : info)(`traits: ${traitsDisposition}`);
         const paramsNudge = !scriptAnalysis && !schemas.length && (hasImageRenderer || hasAttributesRenderer);
         ((undeclaredParams.length || paramsNudge ? warn : info))(`postparams: ${paramsDisposition}`);
-        if (anySurfaceBroken)
-            warn(`${bold('one or more surfaces resolve to NOTHING a marketplace can see')} — fix before deploy (these are on-chain decisions you can't add later without a re-point tx): thumbnail ⇒ ${bold('--image-renderer <Solidity SVG>')} / ${bold('--image-base <public bucket>')} / a resolver · traits ⇒ ${bold('--attributes-renderer')} or a resolver · dropped params ⇒ ${bold('--schema')}.`);
-        // The runner/verify line is for rendered-still lanes. Fully in-chain (image on-chain, no program)
-        // has nothing to run — point at the from-chain check instead.
-        if (hasImageRenderer && !hasProgram)
-            info(`  ${g('nothing to run')} — verify from chain: ${bold('abx tokenuri ' + (predicted ?? '<address>'))} ${dim('(decodes name + on-chain SVG + traits)')}`);
+        if (anySurfaceBroken) {
+            const remedies = [
+                imageOrphaned && `thumbnail ⇒ ${bold('--image-renderer <Solidity SVG>')} / ${bold('--image-base <public bucket>')} / a resolver`,
+                traitsBroken && `traits ⇒ ${bold('--attributes-renderer')} or a resolver`,
+            ].filter(Boolean).join(' · ');
+            const which = imageOrphaned && traitsBroken ? 'the thumbnail and traits surfaces resolve' : `the ${imageOrphaned ? 'thumbnail' : 'traits'} surface resolves`;
+            warn(`${bold(`${which} to NOTHING a marketplace can see`)} — fix before deploy (a deploy-time decision you can't add later without a re-point tx): ${remedies}.`);
+        }
+        // A dropped param is its own, milder problem: the piece renders, that input just takes its
+        // default. Kept separate from the broken-surface alarm above (see the note there).
+        if (undeclaredParams.length)
+            info(`  ${dim('dropped params render with their defaults — declare them to make them real:')} ${bold('--schema <key>:<Type>:<Auth>')}`);
+        // The runner/verify line is for lanes that need an off-chain STILL. An on-chain image renderer has
+        // no still to render, host, or refresh — whether or not there's also a program driving
+        // animation_url — so pointing at a runner and a bucket backend there is simply wrong.
+        if (hasImageRenderer) {
+            info(`  ${g('nothing to render')} — the thumbnail is computed on-chain${hasProgram ? ' and the animation assembles on-chain from your script' : ''}; no runner, no bucket, no refresh. ` +
+                `verify from chain: ${bold('abx tokenuri ' + (predicted ?? '<address>'))} ${dim('(decodes name + on-chain SVG + traits)')}`);
+        }
         else {
             const remoteRender = !(onChainUri && hasImageBase);
             info(`  ${dim('stand up the runner:')} ${bold('abx deploy-effects --resolver-url ' + baseUrl)} · one-shot: ${bold('abx render ' + (predicted ?? '<address>') + (remoteRender ? ' --remote ' + baseUrl : ''))} · verify: ${bold('abx verify ' + (predicted ?? '<address>'))}`);
@@ -3844,6 +3927,9 @@ async function cmdDeployCode(flags) {
             info(`pass ${bold('--for 0x..')} to see the exact deterministic address + a pinned-salt re-run command.`);
         }
         console.log(`\n  ${g('dry run')} ${dim('— nothing sent, no bytes stored. Re-run without --dry-run to deploy.')}\n`);
+        // `address` is null 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: predicted ?? null, chain: CHAIN, chainId: resolveChain(CHAIN).id, factory, salt: salt ?? null, saltPinned: !!parseSaltFlag(flags.salt), name, symbol, onChainUri }));
         return;
     }
     // Real deploy: perform the deferred directory upload now (past the confirm gate).
@@ -3892,12 +3978,39 @@ async function cmdDeployCode(flags) {
         tokenFields: [],
         contractFields,
     });
-    const setupCalls = (owner) => [
-        ...scriptChunks.map((chunk, i) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), chunk] })),
-        ...schemas.map(({ key, paramType, auth, authAddress, lockAfter, min, max, selectOptions }) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setParamSchema', args: [encodeTag(key), paramType, auth, authAddress, lockAfter, min, max, selectOptions] })),
-        ...dependencySetupCalls(deps, depRegistry), // setDependency legs in index order (+ the soft registry pointer)
-        ...(onchainUriLegs ?? []), // program lane only: animation_url field · the URI renderers (before the mints)
-    ].concat(Array.from({ length: setupMintCount }, () => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'mint', args: [owner] }))); // folded mints ride init, not here
+    // 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),
+        ];
+    };
     const cid = resolveChain(CHAIN).id;
     const preparedFor = async (owner) => {
         const salt = parseSaltFlag(flags.salt) ?? saltFor(owner);
@@ -3908,6 +4021,139 @@ async function cmdDeployCode(flags) {
             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 }));
         return { clone, txs };
     };
+    // ── --resume: finish an EXISTING contract, deploy nothing (backlog B15) ─────────────────────
+    // A code deploy is two transactions. When the second fails you own a live-but-unusable contract and
+    // the salt reserved for its address is spent, so the dry run's pinned-salt reproduce command can
+    // never be run again. The contract is recoverable, not lost — a tester proved that by resending the
+    // setup by hand with `cast`. This is that, as a verb: read what is missing, send only that.
+    const resumeAddr = flags.resume;
+    if (resumeAddr !== undefined) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(resumeAddr)) {
+            throw new Error(`--resume wants the address of the contract to finish; '${resumeAddr}' isn't a 0x address.`);
+        }
+        const target = resumeAddr;
+        const code = await publicClient.getCode({ address: target }).catch(() => undefined);
+        if (!code || code === '0x') {
+            throw new Error(`--resume ${target}: no contract at that address on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}). ` +
+                `There is nothing to finish — if the DEPLOY tx is what failed, run a normal deploy instead. ` +
+                `If you JUST deployed, give the tx a block or two to mine.`);
+        }
+        // Deploy-time-only flags are refused rather than ignored: --salt/--721c/--bootstrap-factory all
+        // describe how a contract is CREATED, and this creates nothing. 721C especially — enrollment is
+        // permanent and deploy-time-only, so accepting the flag here would imply it can be added later.
+        for (const [flag, why] of [
+            ['salt', 'the address already exists, so no salt is used'],
+            ['721c', 'ERC-721C enrollment is deploy-time-only and PERMANENT — it cannot be added to an existing collection'],
+            ['bootstrap-factory', 'no factory is involved: nothing is being created'],
+            ['mint-all', 'use --mint-count <n> on a resume; --mint-all is resolved against the cap at deploy time'],
+        ]) {
+            if (flags[flag] !== undefined)
+                throw new Error(`--resume cannot be combined with --${flag}: ${why}.`);
+        }
+        const owner = await publicClient
+            .readContract({ address: target, abi: seriesCodeAbi, functionName: 'owner' })
+            .catch(() => undefined);
+        if (!owner)
+            throw new Error(`--resume ${target}: could not read owner() — is this an ABX SeriesCode contract?`);
+        step('Resume — read what is missing, send only that');
+        info(`target ${bold(target)} ${dim(`· owner ${owner}`)}`);
+        // 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.
+        const legs = setupLegGroups(owner);
+        const readAt = async (functionName, args = []) => {
+            try {
+                return (await publicClient.readContract({ address: target, abi: seriesCodeAbi, functionName, args }));
+            }
+            catch {
+                return null;
+            }
+        };
+        const nonZero = (a) => (a && a !== zeroAddress ? a : null);
+        const reader = {
+            scriptChunkCount: async () => Number((await readAt('scriptChunkCount')) ?? 0n),
+            scriptChunk: (index) => readAt('scriptChunk', [BigInt(index)]),
+            schemaExists: async (key) => {
+                const r = await readAt('paramSchema', [encodeTag(key)]);
+                return !!r?.[0];
+            },
+            dependencyCount: async () => Number((await readAt('dependencyCount')) ?? 0n),
+            dependencyRegistry: async () => nonZero(await readAt('dependencyRegistry')),
+            tokenURIRenderer: async () => nonZero(await readAt('tokenURIRenderer')),
+            contractURIRenderer: async () => nonZero(await readAt('contractURIRenderer')),
+            contractFieldSet: async (field) => {
+                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);
+        for (const line of plan.done)
+            ok(line);
+        for (const line of plan.todo)
+            info(`will send — ${line}`);
+        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 }));
+            console.log('');
+            return;
+        }
+        const tx = prepareCodeSetup({
+            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,
+        });
+        if (flags['dry-run']) {
+            console.log(`\n  ${bold('\u25c6 ' + tx.summary)}  ${dim('(dry run — nothing sent)')}`);
+            for (const [k, v] of Object.entries(tx.fields))
+                console.log(`    ${dim(k.padEnd(14))} ${v}`);
+            console.log(dim(`\n  Re-run without --dry-run to send (lane: ${lane}).\n`));
+            emit(jsonSafe({ command: 'deploy-code', resumed: target, chain: CHAIN, chainId: resolveChain(CHAIN).id, dryRun: true, sent: false, complete: false, sentLegs: plan.calls.length }));
+            return;
+        }
+        await confirmSend(`finish setup on ${target} (${plan.calls.length} call(s), one transaction)`, flags);
+        // Signed through the same choke point as every other write, so --sign / --unsigned / the owner
+        // check / the chain-id guard all apply exactly as they do to a deploy.
+        const result = await signTx(() => tx, {
+            lane,
+            chainKey: CHAIN,
+            yes: !!flags.yes,
+            expectedSigner: owner,
+            port: flags.port ? Number(flags.port) : undefined,
+            signUrlFile: flags['sign-url-file'],
+        });
+        if (!result) {
+            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 }));
+            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;
+        emit(jsonSafe({
+            command: 'deploy-code',
+            resumed: target,
+            address: target,
+            chain: CHAIN,
+            chainId: resolveChain(CHAIN).id,
+            deployBlock: resumedFloor,
+            sent: true,
+            complete: true,
+            sentLegs: plan.calls.length,
+            txHash: result.txHash,
+        }));
+        step('Index');
+        await cmdAdd(target, { 'from-block': resumedFloor.toString(), 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;
     if (lane === 'unsigned') {
@@ -3990,6 +4236,20 @@ async function cmdDeployCode(flags) {
     if (discovered !== null)
         deployBlock = discovered;
     ok(`SeriesCode live: ${clone} ${dim(`(from block ${deployBlock})`)}`);
+    // Emitted here rather than at the end: a code deploy is TWO transactions, and if the second (setup)
+    // fails, the address of the live-but-incomplete contract is the single most valuable thing a caller
+    // can be told — it is exactly the input `--resume <address>` takes to finish the job.
+    emit(jsonSafe({
+        command: 'deploy-code',
+        address: clone,
+        chain: CHAIN,
+        chainId: resolveChain(CHAIN).id,
+        factory,
+        deployBlock,
+        name,
+        symbol,
+        onChainUri,
+    }));
     step('Index');
     await cmdAdd(clone, { 'from-block': deployBlock.toString(), factory, label: name });
     if (onChainUri) {
@@ -4149,6 +4409,34 @@ async function cmdRender(address, tokenIds, flags) {
         warn(`${summary}\n  ${dim(stats.errors[0] ?? 'see error above')}`);
     else
         ok(summary);
+    if (stats.ran)
+        noteArweavePropagation(flags);
+}
+/**
+ * After an Arweave publish, say that a fresh 404 at the gateway is PROPAGATION, not a failed render.
+ *
+ * `arweave.net` lags Turbo uploads by minutes: a tester found 32/32 of their renders 404ing there
+ * while Turbo reported CONFIRMED and 22/32 already served fine from other ar.io gateways. The bytes
+ * were never in doubt — only the gateway was behind. Unexplained, a "broken" thumbnail on a fresh
+ * drop reads as a failed render, and the natural next move is `abx render --force` on all of them:
+ * a full re-upload that fixes nothing.
+ *
+ * Note this is advisory only, and deliberately so — the locator is baked into what the resolver
+ * registers at publish time, so it cannot be repaired by a redirect later. Choosing the gateway is
+ * the operator's call (`ABX_ARWEAVE_GATEWAY`), which is why this names it.
+ */
+function noteArweavePropagation(flags) {
+    const opts = storageOptions(storageOverrides(flags));
+    if (resolveBackend(opts).id !== 'arweave')
+        return;
+    const gateway = opts.arweave?.gateway ?? 'https://arweave.net';
+    if (!/(^|\/\/)([^/]*\.)?arweave\.net/.test(gateway))
+        return; // a gateway they chose — don't lecture
+    info(`${dim('arweave: the locator points at')} ${gateway}${dim(', which can 404 for several minutes after upload while it catches up. That is PROPAGATION, not a failed render — the bytes are already confirmed. Do NOT re-run with')} ${bold('--force')}${dim('; the URL starts working on its own.')}`);
+    info(`  ${dim('to bake a different gateway into the locator instead (it is fixed at publish time):')} ${bold('ABX_ARWEAVE_GATEWAY=https://<gateway>')} ${dim('before you render.')}`);
+    // The note is advisory; this is the answer. Naming it here is the difference between "wait and
+    // hope" and a check a script can gate on — which is what both reporters ended up building.
+    info(`  ${dim('to KNOW rather than wait:')} ${bold('abx storage status <locator>')} ${dim('— ready vs propagating vs unreachable, exits non-zero until it serves.')}`);
 }
 /**
  * The publish topology's one hard prerequisite, checked BEFORE any capture.
@@ -4283,13 +4571,19 @@ async function cmdIndex(address, flags) {
 // so an agent can confirm integrity right after deploy/mint without curling.
 async function cmdVerify(address, flags) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx verify <address>\n');
+        console.error('usage: abx verify <address> [--json] [--remote <name|url>]\n');
         process.exit(1);
     }
     allowLargeScan(flags);
     const remote = remoteFlag(flags);
     if (remote)
         return cmdVerifyRemote(address, remote);
+    // `--json` matters most here of all the read commands: verify already exits non-zero on a byte
+    // mismatch, so it is the one command a CI job would gate on — and gating on prose is what B19 is
+    // about. The payload's `ok` is the same boolean the exit code carries.
+    return withJson(flags, async (emit) => cmdVerifyBody(address, flags, emit));
+}
+async function cmdVerifyBody(address, flags, emit) {
     const indexer = new SelfHostIndexer();
     let state = indexer.getProject(address);
     if (indexer.store.getRegistration(address)) {
@@ -4300,6 +4594,20 @@ async function cmdVerify(address, flags) {
     }
     if (!state)
         throw new Error(`could not load state for ${address}`);
+    // Accumulated as the checks run, re-emitted at each stage so a payload survives an early return.
+    const verifyReport = {
+        address,
+        chain: CHAIN,
+        name: state.name ?? null,
+        canonical: state.isCanonical, // TRUE tri-state: true | false | null (couldn't check)
+        owner: state.owner ?? null,
+        contentChecks: [],
+        contentIntegrity: 'no-commitments',
+        renders: null,
+        onChainUri: null,
+        ok: true,
+    };
+    emit(verifyReport);
     console.log(bold(`\n  verify ${state.name ?? address}`));
     // isCanonical is a TRUE TRI-STATE (true | false | null) and collapsing it lost the only
     // distinction that matters: "the chain says this is NOT a clone of the configured factory" is a
@@ -4315,6 +4623,15 @@ async function cmdVerify(address, flags) {
         const tok = state.tokens.find((s) => s.tokenId === t.tokenId);
         info(`token #${t.tokenId}: ${tok?.minted ? 'minted' : 'not yet minted'}`);
         for (const ch of t.checks) {
+            verifyReport.contentChecks.push({
+                tokenId: t.tokenId,
+                minted: !!tok?.minted,
+                kind: ch.kind,
+                // tri-state again: true (re-hashed, matched) · false (MISMATCH) · null (pointer-only,
+                // nothing local to recompute). Collapsing null into false would report a normal state as a
+                // failure, which is the bug this command exists to not have.
+                verified: ch.verified,
+            });
             anyCheck = true;
             if (ch.verified === true)
                 ok(`${ch.kind} matches on-chain commitment — content is authentic`);
@@ -4328,6 +4645,9 @@ async function cmdVerify(address, flags) {
     }
     if (!anyCheck && !isCodeProject(state))
         info('no content commitments on this project');
+    verifyReport.contentIntegrity = !anyCheck ? 'no-commitments' : allGood ? 'ok' : 'mismatch';
+    verifyReport.ok = !anyCheck || allGood;
+    emit(verifyReport);
     // Code projects have no on-chain `image` commitment (the still is rendered off-chain by the
     // effect runner), so the hash checks above are silent for them. Instead report what actually
     // matters after mint: does a REAL thumbnail exist yet, or is the marketplace image still the
@@ -4361,14 +4681,36 @@ async function cmdVerify(address, flags) {
         // `abx verify <addr> --remote <resolver>` probes what the resolver actually serves (the truthful check).
         if (minted.length)
             info(dim(`render check is against THIS node's store; for a HOSTED drop use \`abx verify ${address} --remote <resolver>\``));
+        // ONE line per outcome, not per token. This printed the same full-sentence advisory 32 times on a
+        // 32-token project (~4KB of identical text) and pushed the four lines that answer "did my deploy
+        // work" off the top of the screen; at a 1000-token supply it is unreadable. The per-token detail
+        // that survives is the token LIST, which is the only part that differs.
+        const missing = [];
+        let present = 0;
         for (const token of minted) {
             const { found } = await currentRenderArtifact(client, state, token, storageForRender, 'image');
             if (found)
-                ok(`token #${token.tokenId} image: real render present (in this node's store)`);
-            else {
-                renderGap = true;
-                console.log(`    ${c.orange}⚠${c.reset} token #${token.tokenId} image: no render in THIS node's store — if you published to a hosted resolver, check it with \`abx verify ${address} --remote <resolver>\`; else render it: \`abx render ${address}\` (once) or \`abx effects\` (continuous)`);
-            }
+                present++;
+            else
+                missing.push(String(token.tokenId));
+        }
+        verifyReport.renders = {
+            minted: minted.length,
+            present,
+            missing, // token ids, so a caller can re-render exactly these
+            // Named for what it IS: this node's store. A render PUBLISHED to a hosted resolver lives
+            // there, not here, so `missing` is a false negative for a hosted drop — hence the scope.
+            scope: "this node's store",
+        };
+        emit(verifyReport);
+        if (present)
+            ok(`${present}/${minted.length} minted token(s): real render present (in this node's store)`);
+        if (missing.length) {
+            renderGap = true;
+            const ids = missing.length > 12 ? `${missing.slice(0, 12).join(', ')}, …+${missing.length - 12} more` : missing.join(', ');
+            console.log(`    ${c.orange}⚠${c.reset} ${missing.length}/${minted.length} token(s) have no render in THIS node's store ${dim(`(#${ids})`)}`);
+            console.log(`      ${dim('published to a hosted resolver? check there:')} ${bold(`abx verify ${address} --remote <resolver>`)}`);
+            console.log(`      ${dim('else render them:')} ${bold(`abx render ${address}`)} ${dim('(once) ·')} ${bold('abx effects')} ${dim('(continuous)')}`);
         }
     }
     // The on-chain URI lane (a non-zero tokenURIRenderer, or an animation field pointing at the
@@ -4380,6 +4722,18 @@ async function cmdVerify(address, flags) {
         try {
             const report = await onChainUriReport(client, state, flags.generator);
             const { status, probe } = report;
+            verifyReport.onChainUri = jsonSafe({
+                generator: report.generator,
+                tokenURIRenderer: state.tokenURIRenderer ?? null,
+                branch: status.branchName,
+                chainComplete: !!status.chainComplete,
+                unresolvedRefs: [...status.unresolvedRefs],
+                urlOverBudget: !!status.urlOverBudget,
+                probe: probe
+                    ? { tokenId: probe.tokenId, onChainJson: !!probe.onChainJson, animation: probe.animation }
+                    : null,
+            });
+            emit(verifyReport);
             info(`on-chain URI lane: generator ${report.generator}${state.tokenURIRenderer ? ` · tokenURI renderer ${state.tokenURIRenderer}` : ' · tokenURIRenderer NOT set (animation field only — tokenURI still resolves off-chain)'}`);
             if (status.branchName === 'template') {
                 ok(`generator branch: template — the document assembles from the on-chain script chunks`);
@@ -4642,15 +4996,28 @@ function decodeOnChainJson(uri, verbatim = false) {
         return verbatim ? raw : raw.slice(0, 600);
     }
 }
-async function cmdTokenUri(address, flags) {
+async function cmdTokenUri(address, flags, extra = []) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx tokenuri <address> [--token <id>] [--json]\n');
+        console.error('usage: abx tokenuri <address> [--token <id>] [--fetch] [--json]\n');
         process.exit(1);
     }
     if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
         console.error(`abx tokenuri: '${address}' isn't a 0x contract address.\n`);
         process.exit(1);
     }
+    // `abx tokenuri <addr> 0` silently ignored the `0` and printed token 0 — a COINCIDENTALLY correct
+    // answer, which is the dangerous kind: `… <addr> 7` would have printed token 0 just as confidently
+    // and exited 0. The token id is a flag here, so name it rather than guessing at intent.
+    const strayPositionals = positionalArgs(extra);
+    if (strayPositionals.length) {
+        const first = strayPositionals[0];
+        const looksLikeTokenId = /^\d+$/.test(first);
+        console.error(`abx tokenuri: unexpected extra argument '${first}'.` +
+            (looksLikeTokenId
+                ? ` The token id is a flag — did you mean:\n    abx tokenuri ${address} --token ${first}\n`
+                : `\n  usage: abx tokenuri <address> [--token <id>] [--fetch] [--json]\n`));
+        process.exit(1);
+    }
     const tokenId = BigInt(flags.token ?? '0');
     const publicClient = makePublicClient({ chainKey: CHAIN });
     // A creator verifying their work often runs this on a wrong / not-yet-mined address — turn viem's
@@ -4679,10 +5046,33 @@ async function cmdTokenUri(address, flags) {
         }
         process.exit(1);
     }
+    // --fetch: FOLLOW the URL the contract commits to and print what is actually served (backlog B14).
+    // The gap this closes: `tokenuri` read the chain, `verify` re-hashed bytes, `status` reported the
+    // lifecycle — none of them showed the served JSON body, so an agent in a cold sweep fell back to raw
+    // `curl`. It also makes a provider mismatch self-evident without a warning that cries wolf: if you
+    // registered with one provider while a different base is baked on-chain, the fetch shows you what
+    // the BAKED base returns (often a 404, or another project's document entirely).
+    const served = flags.fetch !== undefined ? await fetchServedTokenUri(uri) : null;
     // --json: the verbatim document, nothing else on stdout — no banner, no ANSI, no truncation, so
     // `abx tokenuri <addr> --json | jq` is a supported read path rather than something to regex.
     if (flags.json !== undefined) {
-        process.stdout.write((decodeOnChainJson(uri, true) ?? uri) + '\n');
+        const onChain = decodeOnChainJson(uri, true);
+        if (served === null) {
+            process.stdout.write((onChain ?? uri) + '\n');
+            return;
+        }
+        // With --fetch the payload has to say WHICH answer is which: a marketplace reads the served body,
+        // and conflating it with the on-chain URI is the confusion the flag exists to remove.
+        process.stdout.write(JSON.stringify({
+            tokenId: tokenId.toString(),
+            contract: address,
+            chain: CHAIN,
+            tokenURI: uri,
+            onChain: onChain !== null,
+            served,
+        }, null, 2) + '\n');
+        if (served.status !== null && (served.status < 200 || served.status >= 300))
+            process.exitCode = 1;
         return;
     }
     console.log(`\n  ${bold(`tokenURI(${tokenId})`)} ${dim(`— read directly from ${address} on ${CHAIN}, no server`)}`);
@@ -4694,6 +5084,36 @@ async function cmdTokenUri(address, flags) {
     else {
         console.log(`    ${uri.slice(0, 240)}${uri.length > 240 ? dim(`… (${uri.length} chars)`) : ''}\n`);
     }
+    if (served)
+        reportServedTokenUri(served, address);
+}
+/** The human readout for `--fetch`. */
+function reportServedTokenUri(served, address) {
+    if (served.skipped) {
+        info(`--fetch: ${served.skipped}`);
+        return;
+    }
+    console.log(`  ${bold('served')} ${dim(`— GET ${served.url}`)}`);
+    if (served.status === null) {
+        warn(`the baked URL did not respond: ${served.error}. That host is what a marketplace will ask, so this is what they see too.`);
+        return;
+    }
+    const line = `HTTP ${served.status}${served.contentType ? dim(` · ${served.contentType.split(';')[0]}`) : ''}`;
+    if (servedOk(served))
+        ok(line);
+    else
+        console.log(`    ${c.orange}\u26a0${c.reset} ${line}`);
+    const pretty = prettyBody(served.body);
+    const clipped = pretty.length > 1200 ? `${pretty.slice(0, 1200)}\n    \u2026 (${pretty.length} chars \u2014 --json for the full body)` : pretty;
+    console.log(clipped.split('\n').map((l) => '    ' + l).join('\n'));
+    if (!servedOk(served)) {
+        // The mismatch case, stated where it is actionable rather than as a standing warning that would
+        // cry wolf on the common custom-domain setup.
+        console.log(`\n    ${dim('the contract commits to that URL, so a non-2xx is about the SERVICE, never a mistyped path:')} ` +
+            `${dim('the project may not be registered there, the service may serve a different chain, or the base baked on-chain may point at a provider you never registered with.')}\n` +
+            `    ${dim('check the lifecycle:')} ${bold(`abx status ${address} --remote <name|url>`)}`);
+    }
+    console.log('');
 }
 // ── contracturi ──────────────────────────────────────────────────────────────
 /**
@@ -4793,6 +5213,7 @@ async function cmdContractUri(address, _flags) {
 // ── serve ──────────────────────────────────────────────────────────────────--
 async function cmdServe(flags) {
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
+    await assertPortFree(port, 'serve');
     const baseUrl = resolveBaseUrl(port);
     const indexer = new SelfHostIndexer();
     // Surface the most-recently-reconstructed project (what you just deployed), not
@@ -4896,6 +5317,9 @@ async function cmdStorage(rest) {
     if (sub === 'backup-key') {
         return cmdStorageBackupKey(flags);
     }
+    if (sub === 'status') {
+        return cmdStorageStatus(args[0], flags);
+    }
     // show (default) — the RESOLVED effective config + where each value came from. No persisted state.
     const { backend, source } = backendResolution();
     const opts = storageOptions(); // resolved from env → default (no per-command flags here)
@@ -4919,6 +5343,91 @@ async function cmdStorage(rest) {
     console.log(dim('\n    choose per command: --backend <fs|cloud|ipfs|arweave> [--gateway/--bucket/--region/…]  ·  or declare in .env'));
     console.log(dim('    secrets from env only: ABX_S3_ACCESS_KEY_ID · ABX_S3_SECRET_ACCESS_KEY · PINATA_JWT · ARWEAVE_UPLOAD_TOKEN · ARWEAVE_JWK\n'));
 }
+/**
+ * `abx storage status <locator>` — is it **retrievable** yet, not just accepted?
+ *
+ * The gap this closes: an upload service answers "accepted" the moment it holds your bytes, a gateway
+ * answers "serving" only once they reach it, and on Arweave that runs to minutes. Two independent
+ * integrators built their own version of this check eight days apart; the second saw 32/32 renders
+ * 404 on `arweave.net` while 22/32 already served elsewhere and the uploader said `CONFIRMED`. The
+ * expensive part is what a creator does next: a placeholder on a fresh drop reads as a failed render,
+ * so you re-run `abx render --force` and re-upload everything for nothing.
+ */
+const STORAGE_STATUS_FLAGS = new Set(['json', 'gateway', 'backend', 'primary-only', 'timeout']);
+async function cmdStorageStatus(locator, flags) {
+    if (!locator || locator.startsWith('--')) {
+        console.error('usage: abx storage status <locator> [--json] [--gateway <url>] [--primary-only]\n' +
+            '  <locator> — ar://<txid> · ipfs://<cid> · an https:// gateway URL · or a bare txid/CID\n');
+        process.exit(1);
+    }
+    warnStrayFlags(flags, STORAGE_STATUS_FLAGS, 'storage status');
+    const jsonMode = flags.json !== undefined;
+    // The gateway that matters is the one a baked locator resolves through, so default to the active
+    // backend's configured gateway rather than a hardcoded host — otherwise the verdict is about a
+    // gateway this project will never use.
+    const opts = storageOptions(storageOverrides(flags));
+    const configured = flags.gateway ?? opts.arweave?.gateway ?? opts.ipfs?.gateway ?? undefined;
+    const status = await locatorStatus(locator, {
+        gateway: configured,
+        primaryOnly: flags['primary-only'] !== undefined,
+        timeoutMs: flags.timeout === undefined ? undefined : Number(flags.timeout),
+    });
+    if (jsonMode) {
+        process.stdout.write(JSON.stringify(status, null, 2) + '\n');
+        // A program's whole reason to call this is to gate on it, so the verdict is also the exit code:
+        // 0 = ready, 1 = not yet. `until abx storage status <loc> --json; do sleep 10; done` just works.
+        if (status.readiness !== 'ready')
+            process.exitCode = 1;
+        return;
+    }
+    const probeLine = (p, label) => {
+        const verdict = p.serving
+            ? `${g('serving')}`
+            : p.status !== null
+                ? `${c.orange}${p.status}${c.reset}`
+                : `${c.orange}no response${c.reset}`;
+        const size = p.bytes !== null ? dim(` · ${p.bytes < 1024 ? `${p.bytes} B` : `${(p.bytes / 1024).toFixed(1)} KB`}`) : '';
+        const type = p.contentType ? dim(` · ${p.contentType.split(';')[0]}`) : '';
+        const why = p.error ? dim(` · ${p.error}`) : '';
+        console.log(`    ${label} ${bold(p.gateway)} → ${verdict}${size}${type} ${dim(`${p.ms}ms`)}${why}`);
+    };
+    console.log(`\n  ${bold('storage status')} ${dim(`— ${status.network} · ${status.id.length > 60 ? status.id.slice(0, 60) + '…' : status.id}`)}`);
+    probeLine(status.primary, dim('your gateway '));
+    for (const a of status.alternates)
+        probeLine(a, dim('also         '));
+    console.log('');
+    if (status.readiness === 'ready') {
+        ok(`${bold('ready')} — your gateway serves these bytes. Safe to reference in a token.`);
+    }
+    else if (status.readiness === 'propagating') {
+        const where = status.alternates.filter((a) => a.serving).map((a) => a.gateway).join(', ');
+        warn(`${bold('propagating')} — the data is provably on the network (${where} serves it) but ${bold(status.primary.gateway)} hasn't caught up.`);
+        info('Waiting is the fix. Do NOT re-render or re-upload — the bytes are already stored, and a second upload just pays twice.');
+        if (status.network === 'arweave') {
+            info(`To serve sooner from a gateway that already has it, set ${bold('ABX_ARWEAVE_GATEWAY')} before the upload that bakes the locator ${dim('(it cannot be repaired afterwards — the gateway is part of the stored value).')}`);
+        }
+    }
+    else {
+        // Never call this "propagating": from outside, a settling locator and a wrong one look the same.
+        warn(`${bold('not retrievable')} — no gateway probed is serving it.`);
+        // One exception worth reading the statuses for. Gateways answer 404 for "I don't have these
+        // bytes" (settling and wrong are identical there) but 400 for "that isn't a valid id at all".
+        // Every probe agreeing on a non-404 client error is real evidence, and it matters because the
+        // inverse mistake — waiting out a typo — costs more than a needless re-upload.
+        const probes = [status.primary, ...status.alternates];
+        const answered = probes.filter((p) => p.status !== null);
+        const allInvalid = answered.length > 0 && answered.every((p) => p.status >= 400 && p.status < 500 && p.status !== 404);
+        if (allInvalid) {
+            info(`every gateway rejected the id itself (${answered.map((p) => p.status).join(', ')}), not merely "don't have it" — so this is very likely a ${bold('malformed locator')} (truncated txid/CID, or a stray character), not propagation. Re-check the value you stored; waiting will not fix it.`);
+        }
+        else {
+            info('Two causes, and this check cannot tell them apart: it is still settling (wait and re-run — minutes on Arweave), or the locator is wrong (a truncated txid/CID, or the upload never completed).');
+        }
+    }
+    console.log(`\n  ${dim('gate a script on this:')} ${bold(`abx storage status ${locator} --json`)} ${dim('(exit 0 only when ready)')}\n`);
+    if (status.readiness !== 'ready')
+        process.exitCode = 1;
+}
 /**
  * `abx storage upload <path> [--backend ipfs|arweave|cloud]` — upload one file to a durable
  * backend and print the **locator** to point at. This is the missing first half of the data-plane
@@ -5049,6 +5558,106 @@ async function cmdStorageFunding(sub, flags) {
     info('  Credits land on the address above and persist for future uploads. Re-check with `abx storage balance`.');
 }
 // ── status ────────────────────────────────────────────────────────────────--
+// ── tokens: every token's seed + params, read straight from chain ────────────────────────────
+// For a generative collection the seed list IS the collection — it's the first thing you want after
+// a drop ("what did the seeds actually deal?") and, before this existed, the one thing no command
+// could answer. An agent's workaround was: start `abx serve`, GET the project API, base64-decode
+// each tokenURI, base64-decode the animation_url inside it, then regex `0x[0-9a-f]{64}` out of the
+// resulting HTML — 32 times. Every input to that was already a plain contract read.
+const TOKENS_FLAGS = new Set(['json', 'limit', 'from']);
+/** An owner address abbreviated for a human table. Abbreviating for eyes is fine; abbreviating for a
+ *  PROGRAM is not — which is why every value here is also reachable verbatim via `--json`. */
+function shortAddr(a) {
+    return `${a.slice(0, 6)}…${a.slice(-4)}`;
+}
+async function cmdTokens(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx tokens <address> [--json] [--from <id>] [--limit <n>]  — every token\'s owner, seed, and params, from chain\n');
+        process.exit(1);
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        console.error(`abx tokens: '${address}' isn't a 0x contract address.\n`);
+        process.exit(1);
+    }
+    warnStrayFlags(flags, TOKENS_FLAGS, 'tokens');
+    const jsonMode = flags.json !== undefined;
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const code = await publicClient.getCode({ address }).catch(() => undefined);
+    if (!code || code === '0x') {
+        // Name the endpoint we actually asked — "no contract here" and "wrong node" are otherwise
+        // indistinguishable (same reasoning as `tokenuri` / `contracturi`).
+        console.error(`abx tokens: no contract at ${address} on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}) — ` +
+            `double-check the address, and that this endpoint is the network you deployed to. ` +
+            `If you JUST deployed, give the tx a block or two to mine.\n`);
+        process.exit(1);
+    }
+    const listing = await listTokens(publicClient, address, {
+        from: flags.from === undefined ? undefined : Number(flags.from),
+        limit: flags.limit === undefined ? undefined : Number(flags.limit),
+        // Progress on stderr only — stdout must stay pure JSON in --json mode (the ANSI-in-a-locator
+        // lesson: a program's channel is not a place to narrate).
+        onProgress: (done, total) => total > 50 && done % 25 === 0 ? process.stderr.write(`  reading ${done}/${total}…\r`) : undefined,
+    });
+    if (listing.tokens.length > 50)
+        process.stderr.write('                          \r');
+    if (jsonMode) {
+        process.stdout.write(JSON.stringify(listing, null, 2) + '\n');
+        return;
+    }
+    const supply = listing.totalSupply ?? listing.tokens.length;
+    const cap = listing.maxInvocations !== null && listing.maxInvocations > 0 ? ` of ${listing.maxInvocations} max` : '';
+    console.log(`\n  ${bold(`tokens ${address}`)} ${dim(`— ${supply} minted${cap} on ${CHAIN}`)}`);
+    info('read straight from the contract — no indexer, no resolver, no server in the loop');
+    if (!listing.hasParams) {
+        info('this token type has no params extension — so no seeds or params to list (that is correct, not a failed read). Owners below.');
+    }
+    else if (!listing.hasParamEnumeration) {
+        warn('this contract predates on-chain param enumeration — seeds still read, but params cannot be listed. Redeploy on a current implementation to enumerate them.');
+    }
+    const contractKeys = Object.keys(listing.contractParams);
+    if (contractKeys.length) {
+        info(`contract-scope params ${dim('(every token inherits these; a token-scope value of the same key wins)')}`);
+        for (const k of contractKeys.sort())
+            console.log(`      ${g(k)}=${listing.contractParams[k]}`);
+    }
+    if (!listing.tokens.length) {
+        console.log(`\n  ${dim('no tokens in range — nothing minted yet, or --from is past the mint frontier.')}\n`);
+        return;
+    }
+    const anySeed = listing.tokens.some((t) => t.seed !== null);
+    console.log(`\n    ${dim('id'.padStart(4))}  ${anySeed ? dim('seed'.padEnd(66)) + '  ' : ''}${dim('owner')}`);
+    for (const t of listing.tokens) {
+        // A seed is the whole reason this command exists, so it prints in FULL. The owner truncates —
+        // an address stays recognizable abbreviated, and `--json` carries both verbatim either way.
+        const seedCell = anySeed ? `${t.seed ?? dim('—'.padEnd(66))}  ` : '';
+        const owner = t.owner ? shortAddr(t.owner) : dim('— unminted or burned');
+        console.log(`    ${bold(('#' + t.tokenId).padStart(4))}  ${seedCell}${owner}`);
+        const keys = Object.keys(t.params).sort();
+        if (keys.length)
+            console.log(`          ${keys.map((k) => `${g(k)}=${t.params[k]}`).join(dim(' · '))}`);
+    }
+    // The token-scope param SPREAD — what collectors actually chose, which is the question a param
+    // dump is usually a step toward. Deliberately NOT called a trait spread: traits come from running
+    // the script against the seed (that's `abx render`), not from params.
+    const spread = new Map();
+    for (const t of listing.tokens) {
+        for (const [k, v] of Object.entries(t.params)) {
+            const counts = spread.get(k) ?? new Map();
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+            spread.set(k, counts);
+        }
+    }
+    if (spread.size && listing.tokens.length > 1) {
+        console.log(`\n  ${bold('token-scope param spread')} ${dim('(what has actually been set — not the trait spread, which comes from running the script)')}`);
+        for (const key of [...spread.keys()].sort()) {
+            const counts = [...spread.get(key).entries()].sort((a, b) => b[1] - a[1]);
+            const shown = counts.slice(0, 8).map(([v, n]) => `${v} ${dim('×' + n)}`).join(dim(' · '));
+            const rest = counts.length > 8 ? dim(` …+${counts.length - 8} more values`) : '';
+            console.log(`      ${g(key)}: ${shown}${rest}`);
+        }
+    }
+    console.log(`\n  ${dim('every value above verbatim + machine-readable:')} ${bold(`abx tokens ${address} --json`)}\n`);
+}
 // ── state: a one-glance operational snapshot of a deployed contract, read straight from chain ──
 // Read-only (no tx, no local index). Series-only getters revert on a 1/1, so each read is defensive
 // → the same command works for both. The agent-friendly "what's the state before/after an op" call.
@@ -5071,6 +5680,11 @@ async function cmdState(address, flags) {
         console.error('usage: abx state <address>  — a read-only, on-chain operational snapshot\n');
         process.exit(1);
     }
+    // `--json` emits the same facts as data (B19: a value a program needs must be obtainable without
+    // parsing prose). The human narration below is unchanged and rides stderr under --json.
+    return withJson(flags, async (emit) => cmdStateBody(address, flags, emit));
+}
+async function cmdStateBody(address, flags, emit) {
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const read = async (functionName, args = []) => {
         try {
@@ -5099,6 +5713,29 @@ async function cmdState(address, flags) {
     }
     const isSeries = maxInvocations !== undefined; // series-only getter
     const addrOrNone = (a) => (a && a !== zeroAddress ? a : dim('none'));
+    // The payload mirrors what is printed, with `undefined` (getter absent) kept distinct from a zero
+    // address (present and deliberately unset) — collapsing those is what makes a readout lie.
+    const zeroToNull = (a) => (a === undefined ? null : a === zeroAddress ? null : a);
+    const payload = jsonSafe({
+        address,
+        chain: CHAIN,
+        chainId: resolveChain(CHAIN).id,
+        type: isSeries ? 'series' : '1of1',
+        owner: owner ?? null,
+        totalSupply: totalSupply ?? null,
+        nextTokenId: nextTokenId ?? null,
+        maxInvocations: maxInvocations ?? null,
+        paused: paused ?? null,
+        minter: zeroToNull(minter),
+        primaryPayee: zeroToNull(primaryPayee),
+        tokenURIRenderer: zeroToNull(renderer),
+        onChainTokenUri: !!(renderer && renderer !== zeroAddress),
+        royalty: royalty ? { receiver: royalty[0], bps: Number(royalty[1]) } : null,
+        creatorToken: !!creatorToken,
+        transferValidator: creatorToken ? zeroToNull(transferValidator) : null,
+        params: { governed: [], contractScopeSet: [], legacy: false },
+    });
+    emit(payload);
     console.log(bold(`\n  ${isSeries ? 'Series' : '1/1'} state`) + dim(`  ${address} · ${CHAIN}`));
     info(`owner          ${owner ?? dim('?')}`);
     if (isSeries) {
@@ -5142,6 +5779,21 @@ async function cmdState(address, flags) {
             : [];
         const governed = rows.filter((r) => r.s.exists);
         const now = Math.floor(Date.now() / 1000);
+        payload.params.legacy = legacy;
+        payload.params.governed = jsonSafe(governed.map(({ key, s }) => ({
+            key,
+            // Canonical NAMES, not the raw enum indices — a caller must not have to know the Solidity
+            // enum's ordering to read this (the same reason `retired` is a boolean below).
+            paramType: PARAM_TYPES[s.paramType] ?? String(s.paramType),
+            auth: AUTH_OPTIONS[s.auth] ?? String(s.auth),
+            authAddress: s.authAddress === zeroAddress ? null : s.authAddress,
+            lockAfter: s.lockAfter,
+            // A past lockAfter IS how a param is retired — surfaced as a boolean so a caller doesn't
+            // have to re-derive the convention from a timestamp.
+            retired: s.lockAfter !== 0 && s.lockAfter < now,
+            selectOptions: s.selectOptions,
+        })));
+        emit(payload);
         if (governed.length) {
             console.log(`\n  ${bold('PostParams')}  ${dim(`${governed.length} governed · collectors/artist set these; the generator injects them`)}` +
                 (legacy ? dim('  (legacy project — read from its params.keys list)') : ''));
@@ -5161,6 +5813,8 @@ async function cmdState(address, flags) {
         // it is a tokenData coordinate, read directly.
         const set = legacy ? null : await readSetParamKeys(publicClient, address);
         if (set?.contract.length) {
+            payload.params.contractScopeSet = [...set.contract].sort();
+            emit(payload);
             info(`${dim('contract-scope params set:')} ${[...set.contract].sort().join(', ')} ${dim('(apply to every token)')}`);
         }
     }
@@ -5441,6 +6095,16 @@ async function cmdRemote(spec, flags) {
 // SOURCE resolver's PUBLIC api. The two resolvers never talk: we read public endpoints + chain
 // and write through the admin control plane. It does NOT cut over — after a clean migration the
 // operator re-points DNS (custom domain) or the on-chain base URI (provider endpoint).
+//
+// ⚠ IF YOU EVER ADD A REDEPLOY-STYLE MIGRATION HERE — anything that deploys a NEW contract and
+// re-points identity to it (plausible under the greenfield-redeploy stance) — it MUST read the
+// source collection's creator-token status (`readCreatorTokenStatus`) and carry the enrollment +
+// active validator into the new deploy's `transferValidator` InitParam. ERC-721C enrollment is
+// deploy-time-only and PERMANENT, so a migration that forgets it silently converts an enforced
+// collection into a plain ERC-721 — unrecoverable except by yet another redeploy. Corollary: a
+// plain source collection must stay plain; do not "helpfully" enroll on migration. Today's
+// migrate moves off-chain state only, so enrollment lives on the untouched contract and none of
+// this applies — which is exactly why the trap is easy to walk into later.
 async function cmdMigrate(address, flags) {
     // Both sides accept a named remote or a URL. Only the DESTINATION needs a credential — the
     // source is read via its PUBLIC api (the exit ramp works with zero provider cooperation).
@@ -6153,6 +6817,15 @@ const COMMAND_HELP = {
                           The live view 302s to the gateway, so the gateway ${bold('MUST serve HTML')} (a dedicated Pinata gateway or Arweave — never the shared public one)
     --name <s> --symbol <s>   ERC-721 identity   --royalty-bps <0-10000> (default 500)
     ${bold('--public-base-url <url>')}   the resolver you run (${bold('REQUIRED')} unless --onchain-uri — a code project resolves live on-chain state; localhost/missing is refused)
+    ${g('--resume')} <address>    ${bold('FINISH an existing contract whose setup transaction failed')} — deploys nothing. A code deploy is TWO
+                          txns (create the clone, then one atomic setup multicall); when the second fails you own a
+                          live-but-unusable contract AND the salt for its address is spent, so the pinned-salt re-run can
+                          never work. Pass the SAME content flags the original deploy used: it reads what is already
+                          on-chain and sends only what is missing, in one transaction. Chunks compare by CONTENT (so a
+                          hand repair is respected), schemas are left alone if present (re-writing one is an upsert that
+                          can strand values), and mints are a SHORTFALL against current supply — never a re-send, since a
+                          token cannot be un-minted. Nothing missing ⇒ it sends nothing and says so.
+                          ${dim('Refuses --salt / --721c / --bootstrap-factory / --mint-all: those describe how a contract is CREATED.')}
     ${g('--onchain-uri')}         the CHAIN-COMPLETE lane: tokenURI/contractURI resolve ON-CHAIN via the canonical metadata renderer, and
                           animation_url is COMPUTED on-chain by the canonical ${bold('AbxGenerator')} (template: the full HTML document;
                           directory: a parameterized gateway URL — 8KB URL budget, gateway liveness applies). No resolver base is baked
@@ -6255,6 +6928,9 @@ const COMMAND_HELP = {
                           like ${g('display.gateway')}. ≤31 printable-ASCII chars ride as a literal bytes32; longer takes the data path.
                           A contract-scope param applies to every token, and enumerates on-chain like any other.
     --file <path>         read the value from a file (String / Bytes payloads)
+    ${dim('PAYLOAD TYPES:')} ${g('String')} ${dim('takes literal text (UTF-8).')} ${g('Bytes')} ${dim('takes')} ${bold('0x-prefixed hex')} ${dim(`or ${g('--file')} — a bare`)}
+    ${dim('string is refused, because there is no safe guess between "these characters" and "these bytes".')}
+    ${dim(`(The docs' "Bytes becomes base64" describes how your ${bold('program')} receives the value, not how you write it.)`)}
     ${g('--remote [name|url]')}  nudge a REMOTE resolver to re-index IMMEDIATELY after the change (else ABX_PUBLIC_BASE_URL) — it pings
                           the resolver's effect runner, so the thumbnail re-renders without waiting. Usually OPTIONAL now: a
                           resolver running the chain watcher (the ${g('abx serve')} default) sees the change on its next poll (~12s)
@@ -6294,6 +6970,7 @@ const COMMAND_HELP = {
     (+ the 721C transfer validator, for a collection that enrolled at deploy — plain ERC-721s show nothing new).
     Series-only fields are shown for a Series; a 1/1 shows just supply + royalty + renderer.
     Handy before/after owner ops (mint · pause/unpause · set-minter · set-primary-payee).
+    ${g('--json')}               the same facts as data (uncoloured, untruncated) — the machine path; narration moves to stderr.
     ${dim('state = what the CHAIN says. For who is SERVING it and how fresh that is, see `abx status`.')}`,
     predict: `
   ${bold('abx predict')} ${dim('— pre-compute a deploy address (read-only).')}
@@ -6302,6 +6979,8 @@ const COMMAND_HELP = {
   ${bold('abx mint')} <address> ${dim('— mint the NEXT token (a 1/1\'s #0, or a Series\' next-in-order). Owner-only. Sends a tx.')}
     --to 0x..             recipient (default: the owner — pre-mint; a buyer = primary sale)
     ${g('--count')} <n>           mint N tokens in order in ONE tx (Series) — e.g. reserves/airdrops (do them BEFORE you unpause the sale)
+    ${g('--json')}               ${g('{tokenIds, txHash, blockNumber, sent}')} on stdout — the TOKEN ID as data, read from the mint's own
+                          Transfer logs (not by re-reading nextTokenId, which a concurrent mint would make wrong).
     ${dim('minting is sequential (by token id); repeat with different --to for an airdrop to N wallets.')}
     signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')} · ${g('--dry-run')} preview`,
     refresh: `
@@ -6355,10 +7034,13 @@ const COMMAND_HELP = {
     ${dim('up front: enrollment is a deploy-time decision and can never be added (or fully removed) later.')}
     signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')} · ${g('--dry-run')} preview (encodes + shows the tx, sends nothing)`,
     attach: `
-  ${bold('abx attach')} <address> <key> <ipfs://… | ar://… | https://…> ${dim('— attach a named file to a token. Sends a tx.')}
-    ${dim('The data-plane verb: the file joins the token\'s served')} ${bold('artifacts')} ${dim('manifest as {key, mimeType, uri}.')}
+  ${bold('abx attach')} <address> <key> <uri> [<key> <uri> …] ${dim('— attach named file(s) to a token. Sends ONE tx.')}
+    ${dim('The data-plane verb: each file joins the token\'s served')} ${bold('artifacts')} ${dim('manifest as {key, mimeType, uri}.')}
     <key>                 any name YOU choose (print · certificate · stems · readme · source) — how it appears in the manifest
     <uri>                 the file's locator; representation is ${bold('auto-detected')} from the scheme (ipfs → ipfs, ar → arweave, https → url)
+    ${bold('Several pairs in one invocation become ONE transaction')} ${dim('— all-or-nothing, so a revert lands NONE of them. Attaching')}
+    ${dim('artifacts one command at a time is what leaves a half-written token on a failure partway through, and a mint')}
+    ${dim('cannot be undone. Every pair is validated before anything is sent, and a key repeated in one batch is refused.')}
     ${g('--file')} <path>          instead of a URI: store TINY bytes on-chain (SSTORE2, ≈200 gas/byte) — locators are the norm otherwise
     --collection          attach to the collection scope · else --token <id> (default 0)
     ${g('--dry-run')}             preview the tx, send nothing   ·   signing: ${g('--send')} (default, needs a hot key) · ${g('--sign')} (browser wallet, no key) · ${g('--unsigned')}
@@ -6383,8 +7065,12 @@ const COMMAND_HELP = {
     ${g('--dry-run')}             preview the tx, send nothing
     --collection          target collection (ERC-7572) scope · else --token <id> (default 0)`,
     'lock-field': `
-  ${bold('abx lock-field')} <address> --field <name> ${dim('— freeze a field FOREVER (irreversible). Sends a tx.')}
-    --collection | --token <id>`,
+  ${bold('abx lock-field')} <address> --field <name> ${dim('— freeze a metadata FIELD forever (irreversible). Sends a tx.')}
+    --collection | --token <id>
+    --force-field         proceed even if a PostParam shares this name (you mean the field)
+    ${dim('FIELDS AND PARAMS ARE DIFFERENT NAMESPACES and may share a name. This locks the field only —')}
+    ${dim(`to weld a PostParam use ${g('abx set-schema <addr> --schema <key>:<Type>:<Auth>:lock=now')}. Passing a`)}
+    ${dim('declared param key here is refused, because locking the field leaves the param writable.')}`,
     'set-renderer': `
   ${bold('abx set-renderer')} <address> ${dim('— toggle URI resolution between off-chain and on-chain. Sends a tx.')}
     (default)             point at the chain's canonical renderer (deploys it if needed) → resolve ON-CHAIN
@@ -6433,9 +7119,15 @@ const COMMAND_HELP = {
     lifecycle: ${dim('queued')} → ${dim('backfilling')} → ${g('live')}  ·  ${c.orange}stale${c.reset} ${dim('(was live, now lagging — still serving)')}  ·  ${c.orange}failed${c.reset} ${dim('(carries a cause; retried with backoff)')}
     ${dim('status = who is SERVING it and how fresh. For what the CHAIN says (owner, royalty, locks), see `abx state`.')}`,
     storage: `
-  ${bold('abx storage')} <show|upload|balance|topup|backup-key> ${dim('— inspect / operate byte custody. Mostly read-only.')}
+  ${bold('abx storage')} <show|upload|status|balance|topup|backup-key> ${dim('— inspect / operate byte custody. Mostly read-only.')}
     ${g('show')}                  the resolved backend (fs | cloud | ipfs | arweave) + where each value came from
     ${g('upload')} <path>         upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend …] [--dry-run] [${g('--json')}]
+    ${g('status')} <locator>      is it ${bold('RETRIEVABLE')} yet, not just accepted?   [${g('--json')}] [--gateway <url>] [--primary-only]
+                          An upload service says "accepted" the moment it holds your bytes; a gateway serves them only once
+                          they propagate — minutes, on Arweave. Probes YOUR gateway plus two others, because propagation is
+                          per-gateway: ${g('ready')} (yours serves it) · ${g('propagating')} (another does, so the data provably exists —
+                          ${bold('wait, do NOT re-upload')}) · ${g('unreachable')} (nothing does — still settling, or a bad locator).
+                          Exits non-zero unless ready, so ${g('until abx storage status <loc>; do sleep 10; done')} is the whole wait.
     ${g('balance')} · ${g('topup')} --usd <n>   Turbo (arweave) upload credits   ·   ${g('backup-key')} --out <path>   copy the managed key`,
     demo: `
   ${bold('abx demo')} <${dim('no args')}> ${dim('— deploy a throwaway 1/1 to the testnet, index it, and serve it — a guided first run. Sends a tx.')}
@@ -6451,7 +7143,8 @@ const COMMAND_HELP = {
     ${g('buy')} <token> [--to 0x..]   buy ONE token (public; any funded signer). ETH sales attach the price.
     ${dim('the full go-live: deploy-series → minter configure → set-minter <token> --minter <printed> → set-primary-payee → unpause')}
     --minter-contract 0x..   override the shared minter address (else ABX_FIXED_PRICE_MINTER → manifest)
-    signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')} · ${g('--dry-run')} preview (safe — sends nothing)`,
+    signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')} · ${g('--dry-run')} preview (safe — sends nothing)
+    ${g('--json')} the deployed ADDRESS as data on stdout (narration → stderr). With ${g('--dry-run')}: the PREDICTED address + saltPinned.`,
     add: `
   ${bold('abx add')} <address> ${dim('— register + index a project. Also edits off-chain display metadata + traits.')}
     --from-block <n> --factory 0x.. --label "<s>" --description "<s>" --external-url <url> [--full] [--yes]
@@ -6473,12 +7166,29 @@ const COMMAND_HELP = {
                           or 200 bytes), so it accounts for a render PUBLISHED to that resolver. ${bold('Use this for a code project whose')}
                           ${bold('renders were published to a hosted resolver')} — a plain \`abx verify\` only checks THIS machine's store and will
                           report a false placeholder for a render that lives on the resolver.
+    ${g('--json')}               the findings as data, with ${g('ok')} matching the exit code — so CI can gate on a byte mismatch
+                          without parsing prose (a mismatch exits non-zero either way).
     ${dim('On-chain URI lane (a non-zero tokenURIRenderer / a generator-backed animation field): also eth_calls the generator')}
     ${dim(`${g('onChainStatus')} (branch · chain-complete · unresolved refs · URL budget) and decodes ${g('tokenURI')} straight from the contract.`)}`,
     tokenuri: `
   ${bold('abx tokenuri')} <address> [--token <id>] ${dim('— read tokenURI(id) straight from the contract on-chain + decode the JSON (read-only; no server).')}
     ${dim('The proof a fully on-chain token self-resolves: any RPC returns the renderer-assembled metadata. Default token 0.')}
-    ${dim('Collection-level (ERC-7572) counterpart:')} ${g('abx contracturi <address>')}`,
+    ${g('--fetch')}              FOLLOW the URL the contract commits to and print ${bold('what is actually served')} — the body a marketplace reads.
+                          On a fully on-chain token there is nothing to fetch (the tokenURI IS the document) and it says so.
+                          ${dim('This is also how you catch a provider mismatch: it shows what the BAKED base returns, so registering with')}
+                          ${dim('one provider while another is baked on-chain shows up as their 404 rather than as a warning that guesses.')}
+                          ${dim('A non-2xx exits non-zero under --json. A bad status here is about the SERVICE, never a mistyped path —')}
+                          ${dim('the URL came from the chain, so it is right by construction.')}
+    ${dim('Collection-level (ERC-7572) counterpart:')} ${g('abx contracturi <address>')}${dim('. Whole-collection counterpart:')} ${g('abx tokens <address>')}`,
+    tokens: `
+  ${bold('abx tokens')} <address> ${dim('— every token’s owner, seed, and params, read straight from the contract (read-only; no server).')}
+    ${g('--json')}              the listing as data: ${g('{chainId, address, contractParams, tokens: [{tokenId, owner, seed, params}]}')} — verbatim,
+                          uncoloured, untruncated. The machine path; the human table abbreviates owners only.
+    ${g('--from <id>')}         first token id to read (default 0)      ${g('--limit <n>')}  read only n ids from there
+    ${dim('For a generative collection the seed list IS the collection — this is the "what did the seeds actually deal?" read,')}
+    ${dim('and the input to any distribution check before a real launch. Chain-only: no indexer projection and no running')}
+    ${dim('resolver, because the params store enumerates its own keys on-chain and')} ${g('seed')} ${dim('is a reserved param read by name.')}
+    ${dim('Traits are NOT here: a trait comes from running the script against the seed —')} ${g('abx render')}${dim(' does that.')}`,
     contracturi: `
   ${bold('abx contracturi')} <address> ${dim('— read contractURI() (ERC-7572 collection metadata) from the contract, FOLLOW it, and decode (read-only).')}
     ${dim('The collection-level counterpart of')} ${g('tokenuri')}${dim('. On-chain lane: decodes the data: URI. Off-chain lane: fetches the')}
@@ -6514,6 +7224,11 @@ const COMMAND_HELP = {
     project to the effects layer (${g('ABX_EFFECTS_URL')} + ${g('ABX_EFFECTS_TOKEN')}) → thumbnails auto-re-render.
     ${g('ABX_WATCH_INTERVAL_MS')} tunes the cadence; ${g('0')} disables (state then updates only on explicit add/index).
     ${dim('Reorg note: no lookback (post-PoS reorgs are rare); the repair is the deterministic full replay — `abx index <addr> --full`.')}`,
+    changelog: `
+  ${bold('abx changelog')} ${dim('— what changed in this and recent releases. Reads nothing from the network. No tx.')}
+    ${g('--all')}                 the full history (default: the 3 most recent releases)
+    ${dim('The notes ship INSIDE the package, so they always match the version you have and work offline.')}
+    ${dim('Every published version is listed at https://www.npmjs.com/package/@artblocks/abx-cli?activeTab=versions')}`,
 };
 function printCommandHelp(cmd) {
     if (cmd && COMMAND_HELP[cmd]) {
@@ -6556,6 +7271,7 @@ function help() {
     ${g('abx verify')} <addr>       re-hash served bytes vs the on-chain commitment (no server needed)
     ${g('abx tokenuri')} <addr>     read tokenURI(0) on-chain + decode the JSON (proof a self-resolving token works)
     ${g('abx contracturi')} <addr>  read contractURI() (ERC-7572 collection metadata) on-chain, follow it, decode — never hand-build the URL
+    ${g('abx tokens')} <addr>       EVERY token's owner + seed + params, from chain  flags: [--json] [--from <id>] [--limit <n>]
     ${g('abx state')} <addr>        one-glance on-chain snapshot: owner · supply · paused · minter · payee · royalty · renderer
     ${g('abx serve')} [--port ..]   serve the token API + dashboard — and WATCH the chain: auto-index every registered
                             project + notify the effects layer on change (${g('ABX_WATCH_INTERVAL_MS')}; 0 = off)
@@ -6608,6 +7324,7 @@ function help() {
                             ${dim('storage is stateless — no config file. Pick a backend PER COMMAND with flags')}
                             ${dim('(--backend ipfs --gateway … · --backend cloud --bucket … --public-base … · --backend arweave), or set defaults in .env.')}
     ${g('abx storage')} upload <path>   upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend ipfs|arweave|cloud] [--dry-run]
+    ${g('abx storage')} status <locator>  is that locator RETRIEVABLE yet (not just accepted)? — ready | propagating | unreachable   [--json]
     ${g('abx storage')} balance     show Turbo (arweave) upload credits + the funded address
     ${g('abx storage')} topup       buy Turbo credits by card   --usd <n>   (one-time; <100 KB is always free)
     ${g('abx storage')} backup-key  copy the managed Turbo/Arweave key (holds credits) to a safe path   --out <path>
@@ -6616,6 +7333,7 @@ function help() {
     ${g('abx doctor')}              check environment (key, RPC, balance, factory, storage)
     ${g('abx skill install')}       install the version-locked abx skill into your agent(s)   [--agent <name>] [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
     ${g('abx version')}             print the installed CLI version
+    ${g('abx changelog')}           what changed in this and recent releases (ships with the CLI; offline)   [--all]
 
   ${dim('Run')} ${g('abx <command> --help')} ${dim('for per-command usage. --help / -h never executes — it only prints usage.')}
   ${dim('abx checks npm for a newer release (every 6h, notify-only). Silence with')} ${g('ABX_NO_UPDATE_CHECK=1')} ${dim('or')} ${g('--no-update-check')}${dim('.')}
@@ -6709,6 +7427,40 @@ function resolveBundledSkill() {
         return canonical;
     return null;
 }
+/**
+ * `abx changelog [--all]` — print the release notes that ship with THIS install.
+ *
+ * The update banner used to point at `github.com/ArtBlocks/abx/releases`, which 404s for anyone
+ * outside the org, and no changelog shipped in the package — so "what changed?" was unanswerable
+ * without diffing two versions' dry-run output by hand. `CHANGELOG.md` now ships (package.json
+ * `files`), which makes the notes offline, version-matched, and readable by an agent.
+ *
+ * Default: the most recent few entries (what an upgrade needs). `--all`: the whole file.
+ */
+function cmdChangelog(flags) {
+    const pkgDir = resolvePath(fileURLToPath(import.meta.url), '..', '..');
+    const candidates = [joinPath(pkgDir, 'CHANGELOG.md')];
+    const root = findRepoRoot();
+    if (root)
+        candidates.push(joinPath(root, 'packages', 'cli', 'CHANGELOG.md')); // dev checkout
+    const path = candidates.find((p) => existsSync(p));
+    if (!path) {
+        throw new Error(`no CHANGELOG.md found beside this install (looked in ${candidates.join(', ')}). ` +
+            'Version history: https://www.npmjs.com/package/@artblocks/abx-cli?activeTab=versions');
+    }
+    const text = readFileSync(path, 'utf8');
+    if (flags.all !== undefined) {
+        console.log(text);
+        return;
+    }
+    // Entries are `## <version>` sections; show the newest few and say how to see the rest.
+    const lines = text.split('\n');
+    const heads = lines.map((l, i) => (/^## /.test(l) ? i : -1)).filter((i) => i >= 0);
+    const end = heads.length > 3 ? heads[3] : lines.length;
+    console.log(`\n${lines.slice(0, end).join('\n').trimEnd()}\n`);
+    if (heads.length > 3)
+        info(`showing the ${3} most recent releases — ${bold('abx changelog --all')} for the full history ${dim(`(${path})`)}`);
+}
 /** Locate the in-chain renderer Foundry scaffold: bundled beside the CLI (published), else the
  *  repo copy (dev). Same layout in both — it lives under the CLI package's `assets/`. */
 function resolveRendererScaffold() {
@@ -6737,12 +7489,9 @@ function cmdScaffoldRenderer(rest, flags) {
     if (existsSync(dir) && readdirSync(dir).length > 0 && flags.force === undefined) {
         throw new Error(`${dir} already exists and is not empty — pass a fresh path, or --force to write into it.`);
     }
-    mkdirSync(dir, { recursive: true });
-    // Copy the committed scaffold; never carry a stale build/deps dir if one somehow exists.
-    cpSync(src, dir, {
-        recursive: true,
-        filter: (s) => !/(^|\/)(out|cache|dependencies|broadcast|node_modules)(\/|$)/.test(s),
-    });
+    // Copy + assert it landed. Throws rather than printing a success banner over an empty directory —
+    // the alpha.9→alpha.14 failure mode. See src/scaffold.ts for why this is not inline.
+    copyRendererScaffold(src, dir);
     ok(`in-chain renderer scaffold → ${dir}`);
     step('The in-chain Solidity art lane — nothing to run after deploy, tokenURI resolves from chain forever');
     info(`${bold('src/MyRenderer.sol')} draws an SVG from the token ${bold('seed')} + a ${bold('palette')} HexColor PostParam; ${bold('src/MyTraits.sol')} reads the SAME seed for coherent on-chain traits. Fork the art; keep the invariants in ${bold('src/interfaces/IAbxFieldRenderer.sol')} (above all: render() must NEVER revert).`);