@artblocks/abx-cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/main.js

@@ -58,11 +58,12 @@ import { encodeFunctionData } from 'viem';
 import { DEP_RESOLUTION, deploySeedSource, deploySeriesCodeFactory, 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 { declinesSkillInstall } from './prompt.js';
 import { pinGas, waitForCodeAt } from './gas.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
@@ -74,11 +75,11 @@ const SCHEMA_CATALOG = 'Types: Bool·Select·Uint256Range·Int256Range·DecimalR
     'Select needs options — key:Select[A|B|C]:Auth; a Range takes bounds — key:Uint256Range[0..100]:Auth. ' +
     'A palette collectors set = palette:HexColor:TokenOwner';
 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, METADATA_FIELD as F, METADATA_REPRESENTATION as R, indexProgress, isAccepted, AbxIndexTimeoutError, AbxServiceError, } from '@artblocks/abx-sdk';
+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 { cmdTransfer, cmdMint, cmdSetMinter, cmdSetMaxInvocations, cmdConfigureParam, cmdSetSchema, cmdRetireParam, cmdSetParamHooks, cmdSetDependency, cmdRemoveLastDependency, cmdSetDependencyRegistry, cmdLockDependencies, cmdSetPrimaryPayee, cmdPause, cmdUnpause, cmdRefresh, cmdSetTokenUri, cmdSetContractUri, cmdSetRoyalty, cmdSetField, cmdAttach, 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 { 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';
 import { buildMigrationPlan, repinNodeCustody, verifyParity } from './migrate.js';
@@ -161,9 +162,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 +220,14 @@ 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 'contracturi': return cmdContractUri(rest[0], flags);
         case 'serve': return cmdServe(flags);
         // owner operations — write + sign (hot/wallet/cold lane), then re-index
@@ -245,6 +254,7 @@ async function main() {
         case 'deploy-effects': return cmdDeployEffects(flags);
         case 'mint-page': return cmdMintPage(rest[0], flags);
         case 'set-royalty': return cmdSetRoyalty(rest[0], flags);
+        case 'set-transfer-validator': return cmdSetTransferValidator(rest[0], rest.slice(1), flags);
         case 'set-field': return cmdSetField(rest[0], flags);
         case 'attach': return cmdAttach(rest, flags);
         case 'lock-field': return cmdLockField(rest[0], flags);
@@ -445,6 +455,7 @@ function deployCommandLine(flags, salt) {
     str('compress', flags.compress);
     str('royalty-bps', flags['royalty-bps']);
     bool('no-mint');
+    str('721c', flags['721c'] === 'true' ? 'recommended' : flags['721c']); // bare --721c ≡ recommended
     str('backend', flags.backend);
     str('gateway', flags.gateway);
     str('bucket', flags.bucket);
@@ -488,6 +499,7 @@ function deploySeriesCommandLine(flags, salt) {
     str('minter', flags.minter);
     str('primary-payee', flags['primary-payee']);
     str('royalty-bps', flags['royalty-bps']);
+    str('721c', flags['721c'] === 'true' ? 'recommended' : flags['721c']); // bare --721c ≡ recommended
     if (flags.sign !== undefined)
         parts.push('--sign');
     if (flags.unsigned !== undefined)
@@ -528,6 +540,7 @@ function deployCodeCommandLine(flags, salt) {
     str('minter', flags.minter);
     str('primary-payee', flags['primary-payee']);
     str('royalty-bps', flags['royalty-bps']);
+    str('721c', flags['721c'] === 'true' ? 'recommended' : flags['721c']); // bare --721c ≡ recommended
     str('backend', flags.backend);
     str('gateway', flags.gateway);
     str('public-base-url', flags['public-base-url']);
@@ -1198,6 +1211,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
@@ -1210,6 +1225,8 @@ async function cmdDeploy(flags, serveAfter) {
     // a wrong-network RPC must still be caught with the clear mismatch message rather than failing
     // opaquely inside predict; `allowUnreachable` keeps a genuinely offline dry-run previewable.
     await assertChainId(CHAIN, { allowUnreachable: dryRun });
+    // --721c (opt-in ERC-721C): absent → zeroAddress, a plain ERC-721 exactly as before.
+    const transferValidator = await resolveTransferValidatorFlag(flags, publicClient, dryRun);
     // `demo` is exempt: its whole job is a zero-argument first token.
     if (!serveAfter)
         assertRealIdentity(flags, { name, symbol, dryRun });
@@ -1458,6 +1475,7 @@ async function cmdDeploy(flags, serveAfter) {
             contractURIRenderer: renderer,
             royaltyReceiver: deployer,
             royaltyBps,
+            transferValidator,
             tokenFields,
             // authorship + rights (artist / license / …) are collection-scope on-chain fields.
             contractFields: authorshipContractFields(flags),
@@ -1512,7 +1530,8 @@ async function cmdDeploy(flags, serveAfter) {
         return;
     }
     // opt-in --confirm: a final y/N before the real send (no-op without --confirm; never blocks scripts)
-    await confirmSend(`About to deploy 1/1 "${name}" (${symbol})${flags.image ? ' with your image' : ' (generative demo art)'}; mint: ${noMint ? 'deferred' : 'token #0 at deploy'}; owner+royalty: your wallet @ ${royaltyBps / 100}%.`, flags);
+    await confirmSend(`About to deploy 1/1 "${name}" (${symbol})${flags.image ? ' with your image' : ' (generative demo art)'}; mint: ${noMint ? 'deferred' : 'token #0 at deploy'}; owner+royalty: your wallet @ ${royaltyBps / 100}%.` +
+        (transferValidator !== zeroAddress ? ` ERC-721C: enrolled at deploy, permanently (validator ${transferValidator}).` : ''), flags);
     if (lane === 'send') {
         // hot lane: the env key is the deployer, known up front.
         const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
@@ -1767,7 +1786,7 @@ async function cmdDeploySeries(flags) {
     if (!flags.dir) {
         throw new Error('abx deploy-series --dir <media-dir> [--count N] [--mint-all | --mint-count N | --no-mint] ' +
             '[--onchain-image [--compress fastlz] | --onchain-uri --backend ipfs|arweave|cloud (image off-chain, JSON on-chain; cloud needs --public-base) | --onchain-uri (inline SVG) | --public-base-url https://… (hosted resolver)] ' +
-            '[--minter 0x..] [--primary-payee 0x..] [--unpaused] --name "Title" --symbol SYM');
+            '[--minter 0x..] [--primary-payee 0x..] [--unpaused] [--721c recommended|0x..] --name "Title" --symbol SYM');
     }
     const dirPath = resolvePath(flags.dir);
     const files = readdirSync(dirPath)
@@ -1790,6 +1809,8 @@ async function cmdDeploySeries(flags) {
     // Catch a wrong-network RPC with the clear mismatch message even on dry-run (which still reads
     // the chain to predict the address); tolerate an unreachable RPC so an offline preview still works.
     await assertChainId(CHAIN, { allowUnreachable: dryRun });
+    // --721c (opt-in ERC-721C): absent → zeroAddress, a plain ERC-721 exactly as before.
+    const transferValidator = await resolveTransferValidatorFlag(flags, publicClient, dryRun);
     // (identity guard already ran above, via the shared assertRealIdentity — before any RPC)
     // Mint timing: mint-all → the whole series; mint-count N → the first N; else deferred.
     const mintCount = flags['mint-all'] !== undefined ? count : flags['mint-count'] ? Number(flags['mint-count']) : 0;
@@ -2004,7 +2025,8 @@ async function cmdDeploySeries(flags) {
                 : onChainUri
                     ? 'inline SVG on-chain'
                     : `off-chain custody → ${baseUrl}`;
-        await confirmSend(`About to deploy Series "${name}" (${symbol}) — ${count} token(s); ${custody}; mint: ${mintCount > 0 ? `${mintCount} at deploy` : 'deferred'}; owner+royalty: your wallet @ ${royaltyBps / 100}%.`, flags);
+        await confirmSend(`About to deploy Series "${name}" (${symbol}) — ${count} token(s); ${custody}; mint: ${mintCount > 0 ? `${mintCount} at deploy` : 'deferred'}; owner+royalty: your wallet @ ${royaltyBps / 100}%.` +
+            (transferValidator !== zeroAddress ? ` ERC-721C: enrolled at deploy, permanently (validator ${transferValidator}).` : ''), flags);
     }
     if (!onchainImage && !remoteEthUpload)
         await buildFields();
@@ -2023,6 +2045,7 @@ async function cmdDeploySeries(flags) {
             contractURIRenderer: renderer,
             royaltyReceiver: deployer,
             royaltyBps,
+            transferValidator,
             maxInvocations: count,
             primaryPayee,
             minter,
@@ -2869,6 +2892,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');
@@ -2945,7 +2983,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 {
@@ -3092,7 +3134,7 @@ const DEPLOY_CODE_FLAGS = new Set([
     ...AUTHORSHIP_DEPLOY_FIELDS.map(([flag]) => flag), // artist · display-notes · artist-links · license
     'image-base', 'attributes-renderer', 'image-renderer',
     // supply + mint + economics
-    'max', 'mint-count', 'mint-all', 'no-mint', 'unpaused', 'minter', 'primary-payee', 'royalty-bps',
+    'max', 'mint-count', 'mint-all', 'no-mint', 'unpaused', 'minter', 'primary-payee', 'royalty-bps', '721c',
     // params + dependencies
     'schema', 'no-seed', 'no-delegation', 'dep', 'dep-registry',
     // serving lane
@@ -3108,6 +3150,7 @@ const DEPLOY_CODE_FLAGS = new Set([
 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
 ];
 // A 1/1 `abx deploy` accepts these (see `abx help deploy`). Anything else warns (typo'd/unsupported).
 const DEPLOY_FLAGS = new Set([
@@ -3188,7 +3231,7 @@ async function cmdDeployCode(flags) {
         '[--description "<s>"] [--external-url <url>] [--image-base <url> | --image-renderer 0x..] [--attributes-renderer 0x..] ' +
         '[--max N] [--mint-count N | --mint-all] [--schema key:Type:Auth,…] [--no-seed] ' +
         '[--dep <name@version|0x..>[,…]] [--dep-registry 0x..] ' +
-        '[--unpaused] [--minter 0x..] [--primary-payee 0x..] [--royalty-bps N] [--backend ipfs|arweave] [--dry-run] [--confirm] [--bootstrap-factory]';
+        '[--unpaused] [--minter 0x..] [--primary-payee 0x..] [--royalty-bps N] [--721c recommended|0x..] [--backend ipfs|arweave] [--dry-run] [--confirm] [--bootstrap-factory]';
     const scriptPath = flags.script;
     const codeDir = flags['code-dir'];
     const hasProgram = !!(scriptPath || codeDir); // a JS program (script or built dir)
@@ -3261,6 +3304,8 @@ async function cmdDeployCode(flags) {
     // chain to resolve the factory/renderer and predict the address); tolerate an offline preview.
     await assertChainId(CHAIN, { allowUnreachable: dryRun });
     const chainId = dryRun ? resolveChain(CHAIN).id : (await publicClient.getChainId());
+    // --721c (opt-in ERC-721C): absent → zeroAddress, a plain ERC-721 exactly as before.
+    const transferValidator = await resolveTransferValidatorFlag(flags, publicClient, dryRun);
     step('Trust anchor');
     let factory;
     if (dryRun) {
@@ -3666,7 +3711,8 @@ async function cmdDeployCode(flags) {
             `dependencies: ${deps.length ? deps.map((d) => d.display).join(', ') + (depRegistry ? ` (registry ${depRegistry})` : '') : 'none'}; ` +
             `mint: ${mintCount > 0 ? `${mintCount} at deploy${foldIntoInit ? ' (in the deploy tx)' : ''}` : 'deferred'}; ` +
             `tx count: ${foldIntoInit ? (schemas.length ? '2 (deploy + enable your params)' : '1 (everything in the deploy tx)') : '2 (deploy + setup)'}; ` +
-            `owner+royalty: ${flags.for ? `pinned to ${String(flags.for)}` : flags.sign !== undefined ? '⚠ the wallet you connect (NOT pinned — pass --for to enforce)' : 'your wallet'} @ ${royaltyBps / 100}%.\n` +
+            `owner+royalty: ${flags.for ? `pinned to ${String(flags.for)}` : flags.sign !== undefined ? '⚠ the wallet you connect (NOT pinned — pass --for to enforce)' : 'your wallet'} @ ${royaltyBps / 100}%.` +
+            (transferValidator !== zeroAddress ? ` ERC-721C: enrolled at deploy, permanently (validator ${transferValidator}).` : '') + `\n` +
             `  Surfaces — thumbnail: ${imageDisposition}. traits: ${traitsDisposition}. postparams: ${paramsDisposition}.` +
             ((imageOrphaned || traitsBroken || undeclaredParams.length)
                 ? `\n  ⚠ One or more surfaces resolve to NOTHING marketplaces can see — these are DEPLOY-TIME decisions, not backfillable. Re-run --dry-run after fixing, or pass --yes to ship as-is.`
@@ -3784,7 +3830,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
@@ -3802,12 +3854,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>'))}`);
@@ -3863,6 +3928,7 @@ async function cmdDeployCode(flags) {
         contractURIRenderer: foldIntoInit ? metadataRenderer : zeroAddress,
         royaltyReceiver: owner,
         royaltyBps,
+        transferValidator,
         maxInvocations: BigInt(max),
         primaryPayee: flags['primary-payee'] ?? zeroAddress,
         minter: flags.minter ?? zeroAddress,
@@ -4132,6 +4198,31 @@ 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 publish topology's one hard prerequisite, checked BEFORE any capture.
@@ -4344,14 +4435,27 @@ 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));
+        }
+        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
@@ -4625,7 +4729,7 @@ 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');
         process.exit(1);
@@ -4634,6 +4738,19 @@ async function cmdTokenUri(address, flags) {
         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>] [--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
@@ -4776,6 +4893,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
@@ -5045,6 +5163,9 @@ const STATE_ABI = [
     { type: 'function', name: 'primaryPayee', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
     { type: 'function', name: 'tokenURIRenderer', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
     { type: 'function', name: 'royaltyInfo', stateMutability: 'view', inputs: [{ type: 'uint256' }, { type: 'uint256' }], outputs: [{ type: 'address' }, { type: 'uint256' }] },
+    // ERC-721C (creator token) — ERC-165 advertises ICreatorToken ONLY when enrolled at deploy.
+    { type: 'function', name: 'supportsInterface', stateMutability: 'view', inputs: [{ type: 'bytes4' }], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'getTransferValidator', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
 ];
 async function cmdState(address, flags) {
     if (!address || address.startsWith('--')) {
@@ -5061,7 +5182,7 @@ async function cmdState(address, flags) {
             return undefined; // getter absent (extension not composed) or contract has no code
         }
     };
-    const [owner, totalSupply, nextTokenId, maxInvocations, paused, minter, primaryPayee, renderer, royalty] = await Promise.all([
+    const [owner, totalSupply, nextTokenId, maxInvocations, paused, minter, primaryPayee, renderer, royalty, creatorToken, transferValidator] = await Promise.all([
         read('owner'),
         read('totalSupply'),
         read('nextTokenId'),
@@ -5071,6 +5192,8 @@ async function cmdState(address, flags) {
         read('primaryPayee'),
         read('tokenURIRenderer'),
         read('royaltyInfo', [0n, 10000n]),
+        read('supportsInterface', [CREATOR_TOKEN_INTERFACE_ID]),
+        read('getTransferValidator'),
     ]);
     if (owner === undefined && totalSupply === undefined) {
         throw new Error(`no ABX contract state at ${address} on ${CHAIN} (no code, or not an ABX token).`);
@@ -5095,6 +5218,11 @@ async function cmdState(address, flags) {
     if (royalty)
         info(`royalty        ${Number(royalty[1]) / 100}% → ${royalty[0]}`);
     info(`renderer       ${renderer && renderer !== zeroAddress ? `on-chain (${renderer})` : dim('off-chain (stored URI base / override)')}`);
+    // ERC-721C: shown ONLY for an enrolled collection — an unenrolled token is a plain ERC-721
+    // (indistinguishable from a pre-721C token) and shows nothing new here.
+    if (creatorToken) {
+        info(`721C validator ${transferValidator && transferValidator !== zeroAddress ? transferValidator : `${c.orange}suspended${c.reset} ${dim('(zero — enforcement off; re-enable with `abx set-transfer-validator`)')}`}`);
+    }
     // The PostParam surface, read straight from chain: `paramSchemaKeys()` is the DECLARED (governed)
     // set — append-only, and it includes keys declared but never yet written, which nothing off-chain
     // could otherwise discover — and `contractParamKeys()` is the collection-scope set values. Both
@@ -6041,6 +6169,10 @@ const COMMAND_HELP = {
     ${g('--compress')} none|fastlz|gzip   for --onchain-image (default none): ${g('fastlz')} = on-chain decode (stays renderable);
                             ${g('gzip')} = smaller but off-chain decode only
     --royalty-bps <0-10000>   default 500 (5%)
+    ${g('--721c')} [recommended|0x..]   opt-in ERC-721C: enroll at deploy, PERMANENTLY, with that transfer validator
+                            (${g('recommended')} = OpenSea's validator for creator-fee enforcement — only owner-initiated
+                            transfers + authorized sales move the token). Absent = plain ERC-721, forever (the default).
+                            Manage later with ${g('abx set-transfer-validator')} (re-point or suspend; never un-enroll).
     ${g('--no-mint')}             deploy without minting (warm the resolver, then ${g('abx mint')})
     --salt 0x..<64hex>    deploy to a reserved / vanity address (see ${g('abx predict')})
     --public-base-url <url>   bake a public resolver URL on-chain (off-chain custody REQUIRES a public URL; localhost is refused)
@@ -6070,6 +6202,8 @@ const COMMAND_HELP = {
                           a huge collection should set traits post-deploy via ${g('abx set-field')} under a gas budget.
     --minter 0x..         authorize a single minting contract   --primary-payee 0x..   primary-sale payout
     --unpaused            open the mint at deploy (default: paused ⇒ owner-only until ${g('abx unpause')})
+    ${g('--721c')} [recommended|0x..]   opt-in ERC-721C: enroll at deploy, PERMANENTLY, with that transfer validator (absent = plain
+                          ERC-721 forever). ${g('recommended')} = OpenSea's creator-fee-enforcement validator. Manage: ${g('abx set-transfer-validator')}
     --salt 0x.. · --backend … (storage override) · ${g('--storage-signer')} arweave|eth (who pays Turbo uploads) · signing: ${g('--send')} · ${g('--sign')} · ${g('--unsigned')}
     ${g('--dry-run')}             preview (address · per-token plan · custody · mint plan) WITHOUT sending or storing
                             ${dim('(a dry-run needs a deployer to compute the address — pass --for 0x.. if no signing key is set)')}
@@ -6151,6 +6285,8 @@ const COMMAND_HELP = {
                           a CDN-served record is the normal production path, on-chain bytes are the durability floor).
     --max N               supply cap (default 16)   mint timing: ${g('--mint-all')} · ${g('--mint-count')} N · (default: defer, then ${g('abx mint')})
     --no-seed             opt out of the canonical mint-time seed (seeds settle once assigned; curated pre-set seeds win)
+    ${g('--721c')} [recommended|0x..]   opt-in ERC-721C: enroll at deploy, PERMANENTLY, with that transfer validator (absent = plain
+                          ERC-721 forever). ${g('recommended')} = OpenSea's creator-fee-enforcement validator. Manage: ${g('abx set-transfer-validator')}
     --backend ipfs|arweave   directory-mode custody for the build upload   ${g('--unpaused')} · --minter 0x.. · --primary-payee 0x..
     ${dim('a fixed-price PRIMARY SALE is set up AFTER deploy, not by these flags: ')}${g('abx minter configure <addr> --price <eth>')}${dim(' → ')}${g('set-minter')}${dim(' → ')}${g('set-primary-payee')}${dim(' → ')}${g('unpause')}${dim(' (see `abx minter --help`). --minter/--primary-payee here only pre-authorize an already-known minter.')}
     signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')} ${dim('(needs --for 0x..)')}   ${g('--bootstrap-factory')} ${dim('(private chains/sandboxes only)')}
@@ -6220,6 +6356,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)
@@ -6255,7 +6394,8 @@ const COMMAND_HELP = {
     signing: ${g('--send')} (default) · ${g('--sign')} · ${g('--unsigned')}`,
     state: `
   ${bold('abx state')} <address> ${dim('— read-only, on-chain operational snapshot (no tx, no local index).')}
-    Shows owner · supply (minted / max, nextTokenId) · paused · minter · primary payee · royalty · renderer.
+    Shows owner · supply (minted / max, nextTokenId) · paused · minter · primary payee · royalty · renderer
+    (+ 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).
     ${dim('state = what the CHAIN says. For who is SERVING it and how fresh that is, see `abx status`.')}`,
@@ -6310,6 +6450,14 @@ const COMMAND_HELP = {
     deploy to Vercel). ${dim('Offer this after a sale is live (configure → set-minter → set-primary-payee → unpause).')}`,
     'set-royalty': `
   ${bold('abx set-royalty')} <address> --bps <0-10000> [--receiver 0x..] ${dim('— change the royalty. Sends a tx.')}`,
+    'set-transfer-validator': `
+  ${bold('abx set-transfer-validator')} <address> <0x..|none|recommended> ${dim('— manage an ERC-721C collection\'s transfer validator. Owner-only. Sends a tx.')}
+    <0x..>                re-point enforcement at that validator (must be a DEPLOYED contract — checked before any gas)
+    ${g('none')}                  suspend enforcement (validator → address(0); the collection STAYS enrolled)
+    ${g('recommended')}           the chain's recommended validator (OpenSea's, for creator-fee enforcement)
+    ${dim('Only for a collection that enrolled AT DEPLOY (--721c on the deploy commands) — a plain ERC-721 is refused')}
+    ${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}.')}
@@ -6339,8 +6487,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
@@ -6470,6 +6622,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]) {
@@ -6543,6 +6700,7 @@ function help() {
     ${g('abx set-contract-uri')} <addr> re-point the collection URI        --uri <url>
     ${g('abx migrate')} <addr>       move off-chain state to a NEW resolver (verifies parity; no cutover)   --from <old> --to <new>
     ${g('abx set-royalty')} <addr>  change royalty   --bps <0-10000> [--receiver 0x..]
+    ${g('abx set-transfer-validator')} <addr> <0x..|none|recommended>   manage an ERC-721C collection's validator (enrolled-at-deploy only)
     ${g('abx attach')} <addr> <key> <ipfs://…|ar://…|https://…>   attach a named file → the token's ${bold('artifacts')} manifest (data plane)
     ${g('abx set-field')} <addr>    set an on-chain metadata field (low-level)   --field <name> (--text "…" | --value 0x..) [--collection]
     ${g('abx lock-field')} <addr>   freeze a field forever   --field <name> [--collection]
@@ -6571,11 +6729,54 @@ 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('.')}
 `);
 }
+/**
+ * Resolve `--721c` into the InitParams `transferValidator`. Absent → `zeroAddress`: a plain
+ * ERC-721, byte-for-byte the pre-721C deploy — no prompts, no output, no mention of 721C.
+ * `--721c` / `--721c recommended` → the per-chain recommended validator (refused, naming the
+ * chains that have one, when the manifest has no entry); `--721c 0x…` → checksum-validated AND
+ * pre-checked for code on this chain (the factory would revert `InvalidTransferValidator()` —
+ * surface it before any upload/staging/gas). When enrolling, prints the one plain statement of
+ * what enforcement means — once, adapted to the chosen validator.
+ */
+async function resolveTransferValidatorFlag(flags, publicClient, dryRun) {
+    const raw = flags['721c'];
+    if (raw === undefined)
+        return zeroAddress;
+    const chainId = resolveChain(CHAIN).id;
+    const validator = parseTransferValidatorValue(raw, { chainId, chainLabel: CHAIN });
+    // Has-code precheck — for the recommended constant too (presence on THIS chain is the fact that
+    // matters; a sandbox/private chain won't have it). A dry run tolerates an unreachable RPC (it
+    // sends nothing); a real deploy refuses to enroll blind.
+    let code;
+    try {
+        code = await publicClient.getCode({ address: validator });
+    }
+    catch (err) {
+        if (!dryRun)
+            throw new Error(`--721c: couldn't verify the validator has code at ${validator} (${err.message}) — refusing to enroll blind; retry when the RPC answers.`);
+        code = null; // offline preview — note it below
+    }
+    if (code === null) {
+        info(dim(`--721c: RPC unreachable, so the validator code check is deferred — a real deploy verifies ${validator} has code first.`));
+    }
+    else if (!code || code === '0x') {
+        const rec = resolveRecommendedTransferValidator(chainId);
+        throw new Error(`--721c: no contract code at ${validator} on ${CHAIN} — the deploy would revert InvalidTransferValidator(). ` +
+            `A transfer validator must be a DEPLOYED contract on this chain` +
+            (rec && rec !== validator ? ` (the known-good one: --721c recommended → ${rec})` : '') + `.`);
+    }
+    // The one plain statement — printed once, only when enrolling. Never appears un-enrolled.
+    info(validator === resolveRecommendedTransferValidator(chainId)
+        ? `ERC-721C enforcement: only owner-initiated transfers and OpenSea-authorized sales will transfer; other marketplaces/operators are blocked. Manage with \`abx set-transfer-validator\`.`
+        : `ERC-721C enforcement: every non-mint transfer is checked by validator ${validator} — its policy decides which operators may transfer. Manage with \`abx set-transfer-validator\`.`);
+    return validator;
+}
 /** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
 function parseSaltFlag(raw) {
     if (!raw || raw === 'true')
@@ -6622,6 +6823,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() {
@@ -6650,12 +6885,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).`);