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

package/assets/renderer-scaffold/src/interfaces/IAbxParams.sol

@@ -10,6 +10,13 @@ pragma solidity ^0.8.20;
 ///         The tokenData merge rule: a token-scope value overrides the contract-scope one. The
 ///         common pattern is `tokenParam` first, then `contractParam` as a fallback (see the
 ///         `_param` helper in MyRenderer.sol).
+///
+///         TWO READERS, PICK BY TYPE. Scalar types (`Bool`, `Select`, the ranges, `HexColor`,
+///         `Timestamp`) live entirely in the `bytes32` — read them with `tokenParam` /
+///         `contractParam`. The two payload types, **`Bytes` and `String`**, do NOT: their
+///         `bytes32` is a keccak COMMITMENT (`valueIsHash == true`) and the content is fetched with
+///         `tokenParamData` / `contractParamData` below. Reading a `Bytes` param with `tokenParam`
+///         hands you a hash, not the artwork — that is the tell you want the data reader.
 interface IAbxParams {
     /// Returns the token-scope param: its bytes32 `value`, `valueIsHash` (true if it commits to
     /// off-chain bytes — a literal scalar like a seed/HexColor is false), and `isSet` (does it exist).
@@ -23,4 +30,14 @@ interface IAbxParams {
         external
         view
         returns (bytes32 value, bool valueIsHash, bool isSet);
+
+    /// @notice A `Bytes`/`String` token param's FULL content — the payload types' real reader.
+    ///         Returns empty bytes for a literal scalar or an unset key, so an empty return is your
+    ///         "fall back to a default" signal. When non-empty, `keccak256(returned bytes)` equals
+    ///         the `value` that `tokenParam` reports — verify it if you want the commitment proof.
+    ///         Up to ~24KB per key: enough to carry an actual artwork payload on-chain.
+    function tokenParamData(uint256 tokenId, bytes32 key) external view returns (bytes memory);
+
+    /// @notice The contract-scope (collection-wide) blob — the fallback when a token has none.
+    function contractParamData(bytes32 key) external view returns (bytes memory);
 }

package/assets/renderer-scaffold/test/MyRenderer.t.sol

@@ -13,15 +13,38 @@ contract MockParams is IAbxParams {
     mapping(uint256 => mapping(bytes32 => bool)) private ts;
     mapping(bytes32 => bytes32) private cv;
     mapping(bytes32 => bool) private cs;
+    // `Bytes`/`String` params: the bytes32 holds keccak(content), the content lives here.
+    mapping(uint256 => mapping(bytes32 => bytes)) private td;
+    mapping(bytes32 => bytes) private cd;
 
     function setToken(uint256 id, bytes32 key, bytes32 val) external { tv[id][key] = val; ts[id][key] = true; }
     function setContract(bytes32 key, bytes32 val) external { cv[key] = val; cs[key] = true; }
 
+    /// Set a payload-typed (`Bytes`/`String`) param the way the real contract does: the scalar slot
+    /// carries the keccak COMMITMENT and `valueIsHash` is true, so a renderer that reads the bytes32
+    /// gets a hash — the data reader is the only way to the content.
+    function setTokenData(uint256 id, bytes32 key, bytes memory content) external {
+        td[id][key] = content;
+        tv[id][key] = keccak256(content);
+        ts[id][key] = true;
+    }
+    function setContractData(bytes32 key, bytes memory content) external {
+        cd[key] = content;
+        cv[key] = keccak256(content);
+        cs[key] = true;
+    }
+
     function tokenParam(uint256 id, bytes32 key) external view returns (bytes32, bool, bool) {
-        return (tv[id][key], false, ts[id][key]);
+        return (tv[id][key], td[id][key].length > 0, ts[id][key]);
     }
     function contractParam(bytes32 key) external view returns (bytes32, bool, bool) {
-        return (cv[key], false, cs[key]);
+        return (cv[key], cd[key].length > 0, cs[key]);
+    }
+    function tokenParamData(uint256 id, bytes32 key) external view returns (bytes memory) {
+        return td[id][key];
+    }
+    function contractParamData(bytes32 key) external view returns (bytes memory) {
+        return cd[key];
     }
 }
 
@@ -107,4 +130,30 @@ contract MyRendererTest is Test {
         (, bytes memory data) = img.render(address(params), tokenId, IMAGE);
         assertTrue(data.length > 0);
     }
+
+    /// READING A PAYLOAD PARAM (`Bytes`/`String`) — the pattern for carrying an actual artwork
+    /// payload on-chain. The scalar reader hands you a keccak COMMITMENT with `valueIsHash == true`;
+    /// the content only comes from `tokenParamData`. If your renderer reads a `Bytes` param through
+    /// `tokenParam` it will draw from a hash and produce garbage, silently — hence this test.
+    function test_bytesParam_readViaDataReader() public {
+        bytes memory grid = hex"00112233445566778899aabbccddeeff";
+        params.setTokenData(0, "grid", grid);
+
+        // The scalar surface: a commitment, explicitly flagged as one — NOT the content.
+        (bytes32 value, bool valueIsHash, bool isSet) = IAbxParams(address(params)).tokenParam(0, "grid");
+        assertTrue(isSet);
+        assertTrue(valueIsHash, "a Bytes param reports valueIsHash: read the data instead");
+        assertEq(value, keccak256(grid));
+
+        // The data surface: the real bytes, verifiable against that commitment.
+        bytes memory got = IAbxParams(address(params)).tokenParamData(0, "grid");
+        assertEq(got, grid);
+        assertEq(keccak256(got), value, "content must match the on-chain commitment");
+    }
+
+    /// An unset payload param returns empty bytes — your "use a default" signal, never a revert.
+    function test_bytesParam_unsetIsEmpty() public view {
+        assertEq(IAbxParams(address(params)).tokenParamData(0, "grid").length, 0);
+        assertEq(IAbxParams(address(params)).contractParamData("grid").length, 0);
+    }
 }

package/dist/flags.d.ts

@@ -19,6 +19,13 @@ export declare const REPEATABLE_FLAGS: ReadonlySet<string>;
  */
 export declare const GLOBAL_FLAGS: ReadonlySet<string>;
 export declare function parseFlags(args: string[]): Flags;
+/**
+ * The bare (non-flag) arguments, with flag VALUES removed — the mirror of {@link parseFlags}, and
+ * deliberately next to it: the two must consume argv by the same rule or a flag's value looks like a
+ * positional. (Hand-rolling `args.filter(a => !a.startsWith('-'))` reads `--token 0` as a stray
+ * positional `0`, which is exactly the bug a stray-positional check is meant to catch.)
+ */
+export declare function positionalArgs(args: string[]): string[];
 /**
  * The flag keys in `flags` that are NOT in `allowed` — for a non-fatal "unrecognized flag"
  * notice at a command's entry. {@link parseFlags} keeps any `--k` it sees, so a typo'd or

package/dist/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAuC,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAE9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAuC,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAE9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAWvD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E"}

package/dist/flags.js

@@ -25,6 +25,25 @@ export function parseFlags(args) {
     }
     return out;
 }
+/**
+ * The bare (non-flag) arguments, with flag VALUES removed — the mirror of {@link parseFlags}, and
+ * deliberately next to it: the two must consume argv by the same rule or a flag's value looks like a
+ * positional. (Hand-rolling `args.filter(a => !a.startsWith('-'))` reads `--token 0` as a stray
+ * positional `0`, which is exactly the bug a stray-positional check is meant to catch.)
+ */
+export function positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (a.indexOf('=') === -1 && args[i + 1] && !args[i + 1].startsWith('--'))
+                i++; // this flag consumes the next token
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
 /**
  * The flag keys in `flags` that are NOT in `allowed` — for a non-fatal "unrecognized flag"
  * notice at a command's entry. {@link parseFlags} keeps any `--k` it sees, so a typo'd or

package/dist/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAaA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAE9E,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE;QACnC,GAAG,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;aAC/C,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;YAC7E,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,OAAyB;IAClE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"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"}

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';
@@ -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
@@ -1202,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
@@ -2881,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');
@@ -2957,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 {
@@ -3800,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
@@ -3818,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>'))}`);
@@ -4149,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.
@@ -4361,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
@@ -4642,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);
@@ -4651,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
@@ -4793,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
@@ -6255,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)
@@ -6383,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
@@ -6514,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]) {
@@ -6616,6 +6729,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 +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() {
@@ -6737,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).`);