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

package/dist/main.js

@@ -55,15 +55,16 @@ 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, seriesCodeFactoryAbi, } from '@artblocks/abx-sdk';
+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 { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport } from './onchain-uri.js';
+import { expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport, readLegacyParamsKeys, readParamSchemaKeys, readSetParamKeys, } from './onchain-uri.js';
 import { parseFlags, 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, shootPreview, startPreviewServer, DEFAULT_PREVIEW_PORT, PREVIEW_FLAGS } from './preview.js';
+import { previewConfigFromFlags, previewDepTags, parsePreviewParams, shootPreview, startPreviewServer, DEFAULT_PREVIEW_PORT, PREVIEW_FLAGS } from './preview.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 import { declinesSkillInstall } from './prompt.js';
+import { pinGas, waitForCodeAt } from './gas.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
 /** The `--schema` type/auth/format catalog, shown wherever the CLI nudges `--schema`. Kept accurate
  *  to the on-chain enums (PARAM_TYPES / AUTH_OPTIONS) + the Select-options / Range-bounds format —
@@ -73,15 +74,38 @@ 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, 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, 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, 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, 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 { openWalletSession, signTx } from './signer.js';
 import { describeRemoteError, listConfiguredRemotes, misnamedRemoteVars, requireRemoteToken, resolveRemote, serviceClient, tokenSourceLabel } from './remote.js';
 import { buildMigrationPlan, repinNodeCustody, verifyParity } from './migrate.js';
 import { activeBackendId, arweaveKeyFilePath, backendResolution, ensureArweaveJwk, factoryAddress, seriesFactoryAddress, fixedPriceMinterAddress, loadArweaveJwk, loopbackBaseUrl, faucetHint, rendererAddress, storageOptions, storageSignerChoice, } from './config.js';
+/**
+ * Validate `ABX_CHAIN` at module load, BEFORE anything derives from it.
+ *
+ * This has to run here, not inside `main()`. Chain-derived constants are evaluated during module
+ * evaluation (the `EXPLORER` line right below, and — until they were made lazy — several in the
+ * token-api package the CLI imports), so an unknown value threw before `main()` ever ran. The result
+ * was a raw Node stack trace quoting an internal source path, for EVERY command, including `doctor`
+ * — whose entire job is telling you what is wrong with your environment. A cold agent hit exactly
+ * this and reported the tool as broken. A typo should get an answer, not a crash.
+ */
+function assertKnownChainEnv() {
+    const key = process.env.ABX_CHAIN;
+    if (!key || KNOWN_CHAIN_KEYS.includes(key))
+        return;
+    const mainnetish = /^(mainnet|ethereum|homestead|base|eth|1|8453)$/i.test(key.trim());
+    process.stderr.write(`\n\u001b[31m\u2717\u001b[0m ABX_CHAIN="${key}" is not a chain this toolkit ships. Known: ${KNOWN_CHAIN_KEYS.join(', ')}.\n` +
+        (mainnetish
+            ? `  Mainnet is not supported yet \u2014 ABX is testnet-only today. Use base-sepolia (the default) or sepolia;\n` +
+                `  a testnet launch exercises the real thing end to end, just without real money.\n\n`
+            : `  Unset it to use the default (${DEFAULT_CHAIN_KEY}), or set one of the above.\n\n`));
+    process.exit(1);
+}
+assertKnownChainEnv();
 const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY;
 // Block explorer base for the tx/address links the CLI prints. Derived from viem's chain metadata via
 // the SDK (see explorerUrl) rather than a local table — this used to be a hand-maintained map, which is
@@ -150,6 +174,22 @@ async function main() {
     loadDotEnv();
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    // `--chain` is the flag people reach for, and it does not exist: chain selection is the ABX_CHAIN
+    // env var. It used to be swallowed by the generic stray-flag WARNING and the command then acted on
+    // the DEFAULT chain — `abx deploy-code … --chain sepolia` deployed to base-sepolia. On a dry run
+    // that costs a confused minute; on a funded send it is a wrong-chain deploy with real artifacts at
+    // the wrong address. Prose that was ignored once will be ignored again, so this refuses instead,
+    // on EVERY command (a read-only command that quietly ignored it would still teach the wrong model).
+    if (flags.chain !== undefined) {
+        const asked = typeof flags.chain === 'string' && flags.chain !== 'true' ? flags.chain : '';
+        process.stderr.write(`\n${c.red}✗${c.reset} there is no ${bold('--chain')} flag — the chain is chosen by the ${bold('ABX_CHAIN')} environment variable.\n` +
+            `  active now: ${bold(CHAIN)}${asked && asked !== CHAIN ? `  ${dim(`(you asked for '${asked}')`)}` : ''}\n` +
+            `  known chains: ${KNOWN_CHAIN_KEYS.join(', ')}\n\n` +
+            `  run it on ${asked && KNOWN_CHAIN_KEYS.includes(asked) ? asked : '<chain>'} like this:\n` +
+            `      ${bold(`ABX_CHAIN=${asked && KNOWN_CHAIN_KEYS.includes(asked) ? asked : '<chain>'} abx ${cmd ?? '<command>'} …`)}\n` +
+            `  ${dim('(the CLI is deliberately stateless — every run resolves its chain from the environment, so nothing a previous command set can leak into this one.)')}\n\n`);
+        process.exit(1);
+    }
     // `version` / --version / -v is a crisp query — print and exit, no update nag around it.
     if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
         console.log(readCliVersion());
@@ -186,6 +226,8 @@ async function main() {
         case 'set-minter': return cmdSetMinter(rest[0], flags);
         case 'set-max-invocations': return cmdSetMaxInvocations(rest[0], flags);
         case 'configure-param': return cmdConfigureParam(rest[0], rest.slice(1), flags);
+        case 'set-schema': return cmdSetSchema(rest[0], flags);
+        case 'retire-param': return cmdRetireParam(rest[0], rest.slice(1), flags);
         case 'set-param-hooks': return cmdSetParamHooks(rest[0], flags);
         case 'set-dependency': return cmdSetDependency(rest[0], rest.slice(1), flags);
         case 'remove-last-dependency': return cmdRemoveLastDependency(rest[0], flags);
@@ -662,10 +704,12 @@ async function cmdSetRendererCli(address, flags) {
         flags.renderer = await ensureRenderer();
     return cmdSetRenderer(address, flags);
 }
-/** Is the configured renderer the spec version this build expects (v3 — the `artifacts` manifest
- *  plus the authorship/rights collection fields)? A behind-spec renderer is treated as stale so
- *  {ensureRenderer} deploys a fresh one (greenfield redeploy-freely: this number is what tells the
- *  CLI a deployed renderer predates a projection the current build emits). Bump in lockstep with
+/** Is the configured renderer the spec version this build expects (v4 — the computed `abx_params`
+ *  object, enumerated from chain, plus `animation_url` wrapped as `data:text/html;base64` for the
+ *  inline/reader representations)? A behind-spec renderer is treated as stale so {ensureRenderer}
+ *  deploys a fresh one (greenfield redeploy-freely: this number is what tells the CLI a deployed
+ *  renderer predates a projection the current build emits). A v4 renderer is safe on ANY token —
+ *  pointed at a legacy implementation it simply emits no params block. Bump in lockstep with
  *  `AbxMetadataRenderer.SPEC_VERSION`. */
 async function isCurrentRenderer(publicClient, renderer) {
     try {
@@ -674,7 +718,7 @@ async function isCurrentRenderer(publicClient, renderer) {
             abi: abxMetadataRendererAbi,
             functionName: 'specVersion',
         }));
-        return v === 3n;
+        return v === 4n;
     }
     catch {
         return false;
@@ -708,7 +752,51 @@ const imageUrlTemplateField = (template) => ({
     representation: encodeTag(R.urlTemplate),
     value: toHex(template),
 });
+/** Backends that can hand out a publicly-readable URL for uploaded bytes — the ones that make
+ *  "image off-chain, JSON on-chain, no server" possible. `fs` serves only from this machine. */
+const DIRECT_URL_BACKENDS = new Set(['ipfs', 'arweave', 'cloud']);
 const looksLikeSvg = (s) => /^\s*<(\?xml|svg)/i.test(s);
+/**
+ * Does the IMAGE itself end up on-chain for this deploy? Two ways it can:
+ *   • `--onchain-image` — the bytes are staged in the chunk store and read back via a `reader` field.
+ *   • `--onchain-uri` with an SVG — v1 inlines SVG directly as a data: URI (raster cannot be).
+ * Anything else falls through to keccak256 custody, and the on-chain renderer serves its PLACEHOLDER
+ * image. This distinction is the difference between a token that is durable and one that only looks
+ * durable, so it must be computed from the actual file — never inferred from the flag alone (the
+ * success banner used to claim "fully on-chain, no hosting needed" for a keccak-anchored raster).
+ */
+/**
+ * Will `tokenURI` resolve to the creator's REAL image, with nothing to keep running?
+ *
+ * Three ways yes, and they are not the same promise: the bytes are on-chain
+ * ({@link imageEndsUpOnChain}), or they sit at a durable public URL that the on-chain JSON points at
+ * (a direct-URL backend — the "no server" pattern). Only `fs` custody under `--onchain-uri` fails,
+ * because the renderer then holds a hash and nothing can serve it. Keep this separate from
+ * "fully on-chain": conflating them is what let a keccak-anchored raster ship under a permanence
+ * banner it did not earn.
+ */
+function imageResolvesWithoutServer(flags, onchainImage) {
+    if (imageEndsUpOnChain(flags, onchainImage))
+        return true;
+    return !!flags.image && DIRECT_URL_BACKENDS.has(backendResolution(storageOverrides(flags)).backend);
+}
+function imageEndsUpOnChain(flags, onchainImage) {
+    if (onchainImage)
+        return true;
+    const image = typeof flags.image === 'string' ? flags.image : undefined;
+    if (!image)
+        return false;
+    try {
+        const p = resolvePath(image);
+        if (!statSync(p).isFile())
+            return false;
+        // Only the head matters — looksLikeSvg tests the leading tag.
+        return looksLikeSvg(readFileSync(p).subarray(0, 256).toString('utf8'));
+    }
+    catch {
+        return false;
+    }
+}
 async function prepareContent(imagePath, clone, overrides, store = true, // false for --dry-run: compute the hash but don't custody bytes
 onChain = false, // true (--onchain-uri): put the image ON-CHAIN (inline SVG) so it self-resolves
 remoteEth, // wallet-lane Turbo uploads: sign+pay with the connected browser wallet
@@ -730,9 +818,8 @@ walletAddr) {
     const path = resolvePath(imagePath);
     const bytes = new Uint8Array(readFileSync(path));
     const contentType = contentTypeFromPath(path);
-    // On-chain mode can inline SVG directly (the renderer emits it as a data: URI). Raster
-    // can't be inlined cheaply in v1 (a future `reader` is the path) — fall through to
-    // custody + keccak, and the on-chain renderer will show its placeholder for the image.
+    // On-chain mode can inline SVG directly (the renderer emits it as a data: URI).
+    let onchainUrlLane = false;
     if (onChain) {
         const text = Buffer.from(bytes).toString('utf8');
         if (looksLikeSvg(text)) {
@@ -741,7 +828,18 @@ walletAddr) {
                 contentNote: `content: ${basename(path)} (${bytes.length} bytes SVG) INLINE on-chain`,
             };
         }
-        warn(`--onchain-uri can't inline ${contentType} on-chain (v1 inlines SVG only) — storing in custody; the on-chain image will show a placeholder until a reader is set.`);
+        // A raster can't be inlined in v1. That used to mean "fall through to keccak custody and let the
+        // renderer show a placeholder" — which quietly made the documented pattern-2 recipe (image
+        // off-chain, JSON on-chain, no server) impossible for a 1/1 even though `deploy-series` did it
+        // fine. Now the 1/1 takes the same route the Series takes: upload to a durable, publicly-readable
+        // backend and bake the resulting URL on-chain as the image field, so `tokenURI` resolves from the
+        // chain to a real image with nothing to keep running. Only a backend that can hand out a public
+        // read URL qualifies; `fs` (this machine only) still falls through to custody.
+        onchainUrlLane = DIRECT_URL_BACKENDS.has(backendResolution(overrides).backend);
+        if (!onchainUrlLane) {
+            warn(`--onchain-uri can't inline ${contentType} on-chain (v1 inlines SVG only), and '${backendResolution(overrides).backend}' can't serve a public URL — ` +
+                `storing in custody, so the on-chain image will be a placeholder. Add ${bold('--backend arweave')} (or ipfs/cloud) to bake a real image URL, or ${bold('--onchain-image')} to put the bytes themselves on-chain.`);
+        }
     }
     const hash = hashContent(bytes);
     const opts = storageOptions(overrides); // flags override config/env
@@ -750,6 +848,13 @@ walletAddr) {
         opts.arweave = { ...opts.arweave, remoteEth, jwk: undefined, ethSignerKey: undefined };
     noteArweavePlan(opts, bytes.length); // free-vs-credit readout (Turbo) — shown for dry-run too
     if (!store) {
+        const backendId = backendResolution(overrides).backend;
+        if (onchainUrlLane) {
+            return {
+                tokenFields: [imageUrlField(`<${backendId}-url>`)],
+                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) → would upload to ${backendId}; its public URL becomes the ON-CHAIN image field (no server)`,
+            };
+        }
         return {
             tokenFields: [imageKeccakField(hash)],
             contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) · image keccak256 ${hash} (would be stored on deploy)`,
@@ -761,6 +866,26 @@ walletAddr) {
     if (!opts.arweave?.remoteEth)
         await assertTurboFundsForUpload(opts, [bytes.length], walletAddr);
     const backend = resolveBackend(opts);
+    if (onchainUrlLane) {
+        // One file, uploaded as a one-entry directory — the same call `deploy-series` uses for its
+        // uniform-extension folder, so both commands produce the same URL shape from the same code path.
+        // Named `0.<ext>` because a 1/1 is token 0. Falls back to custody if the backend turns out not to
+        // support directories, rather than silently producing a token whose image never resolves.
+        const ext = extname(path).toLowerCase() || '.bin';
+        if (backend.putDirectory) {
+            const { base } = await backend.putDirectory([{ name: `0${ext}`, bytes, contentType }]);
+            const url = `${base}/0${ext}`;
+            // Keep the bytes under their hash too: `abx verify` can then still prove the served image
+            // matches what was uploaded, even though the on-chain field addresses it by URL.
+            await backend.put(hash, { bytes, contentType });
+            ok(`image → ${url}  ${dim(`(${backend.id}; baked on-chain, no server)`)}`);
+            return {
+                tokenFields: [imageUrlField(url)],
+                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) on ${backend.id} · ON-CHAIN image url ${url}`,
+            };
+        }
+        warn(`'${backend.id}' cannot upload a directory, so no public image URL could be baked — falling back to custody (the on-chain image will be a placeholder).`);
+    }
     await backend.put(hash, { bytes, contentType });
     return {
         tokenFields: [imageKeccakField(hash)],
@@ -1023,7 +1148,7 @@ async function remoteLocators(address, stored, flags) {
 }
 // ── deploy (+ optionally serve) ──────────────────────────────────────────────
 async function cmdDeploy(flags, serveAfter) {
-    warnStrayFlags(flags, DEPLOY_FLAGS, 'deploy');
+    refuseStrayFlags(flags, DEPLOY_FLAGS, 'deploy');
     warnSignWithoutFor(flags);
     const dimension = resolveDimension(flags.type ?? '1of1');
     // A multi-token collection is its OWN command; `abx deploy` is the single-token (1/1) path.
@@ -1222,6 +1347,23 @@ async function cmdDeploy(flags, serveAfter) {
         if (!hasPublicUrl)
             info('off-chain fallback pointer left empty (the renderer is authoritative); set --public-base-url to bake one anyway.');
     }
+    // `--onchain-uri` puts the tokenURI JSON on-chain; it does NOT put the IMAGE on-chain. Without
+    // `--onchain-image` the image is committed as a keccak256 anchor, which the on-chain renderer
+    // cannot serve bytes for — so `tokenURI` returns a PLACEHOLDER image. Say that here, before the
+    // spend (this runs in `--dry-run` too), because the success banner used to claim "fully on-chain,
+    // no hosting needed" for exactly this config and a creator would believe they had permanence they
+    // don't. The code lane's dry run already warns about this case; the 1/1 lane shipped it silently.
+    if (onChainUri && !imageResolvesWithoutServer(flags, onchainImage)) {
+        warn(`${bold('--onchain-uri puts the metadata JSON on-chain, not the image.')} With '${backendResolution(storageOverrides(flags)).backend}' custody the image is only ` +
+            `a keccak256 anchor, so ${bold('tokenURI')} will serve a PLACEHOLDER — nothing can fetch the bytes.`);
+        info(`two ways to get a real image with no server: ${bold('--backend arweave')} (or ipfs/cloud) uploads it and bakes the URL on-chain, or ${bold('--onchain-image --compress fastlz')} puts the bytes themselves on-chain (best under ~24KB).`);
+    }
+    else if (onChainUri && !imageEndsUpOnChain(flags, onchainImage)) {
+        // Resolves, durably, with no server — but the IMAGE is not on-chain, and that distinction is
+        // exactly what a creator asking for permanence is buying. Say which one they are getting.
+        info(`${bold('image off-chain, JSON on-chain')} — the image uploads to ${bold(backendResolution(storageOverrides(flags)).backend)} and its URL is baked into the on-chain metadata. ` +
+            `No server to run; permanence is the backend's (Arweave is pay-once-forever, IPFS lasts as long as it stays pinned). For the image itself on-chain, use ${bold('--onchain-image')}.`);
+    }
     // IPFS/Arweave custody serves the image from the gateway URL. A LOCAL gateway produces an image
     // URL only this machine can load — the image equivalent of the localhost-tokenURI footgun above.
     if (!onChainUri && !onchainImage) {
@@ -1524,7 +1666,23 @@ async function cmdDeploy(flags, serveAfter) {
     if (!serveAfter) {
         if (onChainUri) {
             // Fully on-chain → it self-resolves. Prove it from the chain, no server/localhost.
-            console.log(`\n${g('Done — fully on-chain.')} ${dim('The token self-resolves; no server or hosting needed.')}`);
+            // BUT only claim "fully on-chain" when the IMAGE is on-chain too. With `--onchain-uri` alone
+            // the image is a keccak256 anchor the renderer can't serve, so tokenURI yields a placeholder —
+            // and this banner previously said "no server or hosting needed" over exactly that, which is a
+            // promise of permanence the token does not have. Truthful, per-config wording instead.
+            if (imageEndsUpOnChain(flags, onchainImage)) {
+                console.log(`\n${g('Done — fully on-chain.')} ${dim('The token self-resolves; no server or hosting needed.')}`);
+            }
+            else if (imageResolvesWithoutServer(flags, onchainImage)) {
+                const bk = backendResolution(storageOverrides(flags)).backend;
+                console.log(`\n${g('Done — metadata on-chain, image on ' + bk + '.')} ${dim('No server to run: the on-chain JSON points straight at the image.')}`);
+                console.log(`  ${dim(`the image is addressed by URL rather than stored on-chain — its permanence is ${bk}'s (Arweave: paid once, kept forever · IPFS: kept while pinned).`)}`);
+            }
+            else {
+                console.log(`\n${g('Done — metadata on-chain.')} ${dim('tokenURI/contractURI resolve from the chain with no server.')}`);
+                console.log(`  ${c.orange}The IMAGE is not on-chain${c.reset} ${dim('— it is a keccak256 anchor, so tokenURI serves a placeholder image.')}`);
+                console.log(`  ${dim(`prove it: ${bold(`abx tokenuri ${clone}`)} reports the image field's provenance. To fix it, redeploy with ${bold('--backend arweave')} (URL baked on-chain) or ${bold('--onchain-image')} (bytes on-chain).`)}`);
+            }
             console.log(`  ${bold(`abx tokenuri ${clone}`)}  ${dim('# read tokenURI(0) straight from the contract + decode the JSON')}`);
             if (noMint)
                 console.log(`  ${bold(`abx mint ${clone}`)}  ${dim('# issue token #0')}`);
@@ -1598,7 +1756,7 @@ const tokenFieldOf = (tokenId, f) => ({
     value: f.value,
 });
 async function cmdDeploySeries(flags) {
-    warnStrayFlags(flags, DEPLOY_SERIES_FLAGS, 'deploy-series');
+    refuseStrayFlags(flags, DEPLOY_SERIES_FLAGS, 'deploy-series');
     warnSignWithoutFor(flags);
     const name = flags.name ?? 'ABX Series';
     const symbol = flags.symbol ?? 'ABXS';
@@ -2791,22 +2949,38 @@ async function cmdPreview(flags) {
     if (shootDir) {
         step(`Render ${count} seeds headlessly`);
         try {
+            const shotParams = parsePreviewParams(flags.param);
+            if (Object.keys(shotParams).length) {
+                info(`param overrides applied to every frame: ${Object.entries(shotParams).map(([k, v]) => `${k}=${v || dim('(unset)')}`).join(' · ')}`);
+            }
             const shots = await shootPreview(server.url, shootDir, count, {
                 width: Number(flags.width ?? 1000) || 1000,
                 timeoutMs: Number(flags['timeout-ms'] ?? 10_000) || 10_000,
+                params: shotParams,
             });
             ok(`${shots.length} frames → ${shootDir}/  ${dim('(traits in traits.json)')}`);
             for (const s of shots) {
                 const t = s.traits && Object.keys(s.traits).length
                     ? Object.entries(s.traits).map(([k, v]) => `${k} ${String(v)}`).join(' · ')
-                    : `${c.orange}no traits reported${c.reset}`;
-                console.log(`      ${dim(s.seed.slice(0, 10) + '…')}  ${t}${s.done ? '' : dim('  (no abx.done())')}`);
+                    : s.timedOut
+                        ? `${c.orange}timed out — traits unknown${c.reset}`
+                        : `${c.orange}no traits reported${c.reset}`;
+                console.log(`      ${dim(s.seed.slice(0, 10) + '…')}  ${t}${s.done || s.timedOut ? '' : dim('  (no abx.done())')}`);
             }
+            const timedOut = shots.filter((s) => s.timedOut).length;
             const silent = shots.filter((s) => !s.traits || !Object.keys(s.traits).length).length;
-            if (silent === shots.length) {
+            // A timeout is a measurement failure, not a finding about the program — so it must never be
+            // reported as one. The old code printed the "NO frame reported traits" alarm whenever traits
+            // came back empty for any reason, which condemned a CORRECT program on a loaded machine and
+            // inverted the one line agents are told to trust.
+            if (timedOut) {
+                warn(`${timedOut} of ${shots.length} frame(s) hit the ${Math.round((Number(flags['timeout-ms'] ?? 10_000) || 10_000) / 1000)}s wait with nothing reported — ` +
+                    `that is a TIMEOUT, not a verdict on the program. Re-run with ${bold('--timeout-ms 30000')} (or on an idle machine) before believing anything about its traits.`);
+            }
+            if (silent === shots.length && !timedOut) {
                 warn('NO frame reported traits — `abx.traits({…})` is the only thing that becomes marketplace `attributes`. Verify with `abx inspect`.');
             }
-            else if (shots.length > 1 && new Set(shots.map((s) => JSON.stringify(s.traits))).size === 1) {
+            else if (silent < shots.length && shots.length > 1 && new Set(shots.map((s) => JSON.stringify(s.traits))).size === 1) {
                 // Only meaningful when traits DID come back: identical values across seeds is the signature
                 // of a sketch that never reads `abx.tokenData.seed` (prototyped on Math.random()), which
                 // deploys as N visually identical tokens. Skipped when nothing reported at all — the
@@ -2962,6 +3136,33 @@ const FLAG_HINTS = {
     supply: () => 'did you mean --max <N> (the supply cap)?',
     amount: () => 'a sale price/amount is set post-deploy via `abx minter configure`.',
 };
+/**
+ * Unknown flags on a command that can SEND: refuse, don't warn.
+ *
+ * This used to warn and carry on, and `--chain sepolia` proved why that isn't enough — the warning was
+ * accurate, it scrolled past, and the deploy ran on the DEFAULT chain. On a dry run that costs a
+ * confused minute; on a funded send it is a wrong-chain deploy. "Prose that was ignored once will be
+ * ignored again" is the standing rule here, so the tx-sending commands stop instead.
+ *
+ * Safe to refuse rather than warn because a flag absent from the allowlist is, by construction, one
+ * the command never reads — verified per command by comparing every `flags.x` read in its body against
+ * its allowlist. So refusal cannot break a working flag; it only makes an already-ignored one loud.
+ *
+ * `--dry-run` refuses identically. A preview that accepts what the real send rejects is its own trap:
+ * you'd validate a command in preview and have it fail at the moment it matters.
+ */
+function refuseStrayFlags(flags, allowed, cmd) {
+    const stray = unknownFlags(flags, allowed);
+    if (!stray.length)
+        return;
+    const hints = stray.map((f) => FLAG_HINTS[f]?.(cmd)).filter(Boolean);
+    throw new Error(`unrecognized flag(s): ${stray.map((f) => '--' + f).join(', ')} — this command would have ignored them silently, so it is refusing instead.\n` +
+        hints.map((h, i) => `    ↳ --${stray[i]}: ${h}`).join('\n') +
+        (hints.length ? '\n' : '') +
+        `    see \`abx help ${cmd}\` for the flags it accepts.`);
+}
+/** Unknown flags on a READ-ONLY command: warn, don't refuse. Nothing can be mis-sent, and a stray
+ *  flag on `preview`/`inspect` shouldn't stop a creator mid-iteration. */
 function warnStrayFlags(flags, allowed, cmd) {
     const stray = unknownFlags(flags, allowed);
     if (stray.length) {
@@ -3003,7 +3204,7 @@ async function cmdDeployCode(flags) {
     // Surface unsupported/typo'd flags BEFORE any work — a silent no-op on a write-adjacent value
     // (e.g. --description landing nowhere) is the worst failure mode. Non-fatal (see unknownFlags).
     // Shared path so the "did you mean --max / price is post-deploy" hints fire here too.
-    warnStrayFlags(flags, DEPLOY_CODE_FLAGS, 'deploy-code');
+    refuseStrayFlags(flags, DEPLOY_CODE_FLAGS, 'deploy-code');
     warnSignWithoutFor(flags);
     const dryRun = !!flags['dry-run'];
     const name = flags.name ?? 'ABX Code';
@@ -3438,27 +3639,21 @@ async function cmdDeployCode(flags) {
     // gas cap and appear to REVERT. Expected, not a bug — a real session mis-diagnosed it as indexing lag.
     const tokenUriGasRisk = onChainUri && !codeDir && (scriptAnalysis?.doc.estBytes ?? 0) > 30_000;
     // --onchain-uri legs (ride the setup multicall, before the mints): the animation_url field
-    // pointing at the generator, the params.keys contract param, and the two URI renderers.
-    // params.keys composition rule: EVERY param key this deploy writes ∪ the --schema keys ∪
-    // `params.keys` itself — deduped, sorted, comma-joined. deploy-code writes no display.*/
-    // render.* params today; a future flag that does MUST add its key to `writtenParamKeys` so
-    // the generator's on-chain tokenData stays byte-aligned with the resolver's (which carries
-    // every evented param — inputsHash parity is load-bearing).
+    // pointing at the generator, and the two URI renderers. The param surface needs NO leg — the
+    // generator enumerates it from the token on-chain (`contractParamKeys`/`tokenParamKeys`, kept in
+    // step by the write paths themselves), so there is nothing for a deploy to declare and nothing to
+    // drift. (The retired `params.keys` CSV convention is gone; a legacy project keeps its old generator.)
     // THE FOLD: on the renderer-only in-chain lane (no program), the on-chain-URI wiring (tokenURI/
     // contractURI renderers) + the reserve mint move INTO the deploy tx's init params — the token is
     // fully configured at deploy (the renderers already exist on-chain), so the setup multicall is
     // needed ONLY for a PostParam schema (and is skipped entirely when there's none → a 1-tx drop).
     // The script/dir lane is UNCHANGED: its chunks always need the multicall, and its mint must ride
     // AFTER the chunks (a mint-before-chunks token would be transiently unresolvable), so its
-    // URI-renderers + animation + params.keys + mint stay in the multicall exactly as before.
+    // URI-renderers + animation + mint stay in the multicall exactly as before.
     const foldIntoInit = onChainUri && !hasProgram;
-    const writtenParamKeys = [];
-    const paramsKeysCsv = onChainUri ? composeParamsKeys(writtenParamKeys, schemas.map((s) => s.key)) : '';
-    // params.keys + the URI-renderer/animation legs only ride the multicall for a PROGRAM (the
-    // generator consumes params.keys; renderer-only has no generator and folds the renderers to init).
-    const onchainUriLegs = onChainUri && hasProgram
-        ? onchainUriSetupCalls({ generator, metadataRenderer, paramsKeys: paramsKeysCsv })
-        : null;
+    // The URI-renderer/animation legs only ride the multicall for a PROGRAM (renderer-only has no
+    // generator and folds the renderers into init).
+    const onchainUriLegs = onChainUri && hasProgram ? onchainUriSetupCalls({ generator, metadataRenderer }) : null;
     const setupMintCount = foldIntoInit ? 0 : mintCount; // folded mints ride init, not the multicall
     // opt-in --confirm: one y/N before ANY upload or send (no-op without --confirm; never blocks scripts).
     if (!dryRun) {
@@ -3466,7 +3661,7 @@ async function cmdDeployCode(flags) {
         await confirmSend(`About to deploy code project "${name}" (${symbol}) — ${contentSummary}; ` +
             (identityFields.length ? `${identityFields.join(' + ')} on-chain; ` : '') +
             (onChainUri
-                ? `tokenURI ON-CHAIN via renderer ${metadataRenderer}${hasProgram ? ` (generator ${generator}; params.keys "${paramsKeysCsv}")` : ' (renderer-only — image + traits from your Solidity renderers, no animation)'}; `
+                ? `tokenURI ON-CHAIN via renderer ${metadataRenderer}${hasProgram ? ` (generator ${generator})` : ' (renderer-only — image + traits from your Solidity renderers, no animation)'}; `
                 : `resolver base ${baseUrl}; `) +
             `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'}; ` +
@@ -3501,7 +3696,7 @@ async function cmdDeployCode(flags) {
             ? (await publicClient.readContract({ address: factory, abi: seriesCodeFactoryAbi, functionName: 'predictDeterministicAddress', args: [salt] }))
             : null;
         const depLegs = deps.length + (depRegistry ? 1 : 0);
-        const setupLen = scriptChunks.length + schemas.length + depLegs + (onchainUriLegs?.calls.length ?? 0) + setupMintCount;
+        const setupLen = scriptChunks.length + schemas.length + depLegs + (onchainUriLegs?.length ?? 0) + setupMintCount;
         step(`Deploy plan — a ${max}-token code project to ${CHAIN}`);
         if (deployer)
             info(`deployer ${deployer}`);
@@ -3526,7 +3721,7 @@ async function cmdDeployCode(flags) {
                     : `; no animation_url (renderer-only — image + attributes computed on-chain by your Solidity renderer(s))`));
             if (hasProgram) {
                 info(`  on-chain URI legs (ride the setup multicall): collection animation_url field (renderer rep → ${generator}) · ` +
-                    `params.keys = "${paramsKeysCsv}" (${onchainUriLegs.paramsKeysEncoding === 'literal' ? 'literal bytes32' : `data-backed, ${paramsKeysCsv.length}B`}) · setTokenURIRenderer · setContractURIRenderer`);
+                    `setTokenURIRenderer · setContractURIRenderer ${dim('(the param surface enumerates on-chain — no leg, nothing to maintain)')}`);
             }
             else {
                 info(`  on-chain URI wiring rides the ${bold('deploy tx')} itself (tokenURI/contractURI renderers${mintCount > 0 ? ' + the reserve mint' : ''} in init) — no separate setup tx for it.`);
@@ -3578,7 +3773,7 @@ async function cmdDeployCode(flags) {
                 BigInt(storedBytes) * 216n + // ~200 gas/byte code deposit + ~16 gas/byte calldata
                 BigInt(schemas.length) * 45000n +
                 BigInt(depLegs) * 55000n +
-                BigInt(onchainUriLegs?.calls.length ?? 0) * 60000n +
+                BigInt(onchainUriLegs?.length ?? 0) * 60000n +
                 BigInt(mintCount) * 65000n;
             const gasPrice = await publicClient.getGasPrice();
             const eth = Number(roughGas * gasPrice) / 1e18;
@@ -3682,9 +3877,9 @@ async function cmdDeployCode(flags) {
     });
     const setupCalls = (owner) => [
         ...scriptChunks.map((chunk, i) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [BigInt(i), chunk] })),
-        ...schemas.map(({ key, paramType, auth, min, max, selectOptions }) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setParamSchema', args: [encodeTag(key), paramType, auth, zeroAddress, 0, min, max, selectOptions] })),
+        ...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?.calls ?? []), // program lane only: animation_url field · params.keys · the URI renderers (before the mints)
+        ...(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
     const cid = resolveChain(CHAIN).id;
     const preparedFor = async (owner) => {
@@ -3693,7 +3888,7 @@ async function cmdDeployCode(flags) {
         const calls = setupCalls(owner);
         const txs = [prepareDeploySeriesCode({ factory, params: initParamsFor(owner), salt, chainId: cid, clone })];
         if (calls.length)
-            txs.push(prepareCodeSetup({ contract: clone, calls, chainId: cid, chunkCount: scriptChunks.length, schemaKeys: schemas.map((x) => x.key), deps: deps.map((d) => d.display), onchainUri: onChainUri && hasProgram }));
+            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 };
     };
     let clone;
@@ -3745,8 +3940,19 @@ async function cmdDeployCode(flags) {
         // the mempool rejects the duplicate as "replacement transaction underpriced" and the setup leg is
         // lost (leaving a deployed-but-unconfigured clone). Fetch once, then increment per send.
         let nonce = await publicClient.getTransactionCount({ address: account.address, blockTag: 'pending' });
-        for (const tx of txs) {
-            const hash = await wallet.sendTransaction({ to: tx.to, data: tx.data, account, chain: wallet.chain, nonce });
+        for (const [i, tx] of txs.entries()) {
+            // The SAME read-after-write lag the nonce is pinned for, one field over. Every tx after the
+            // first targets the clone the FIRST tx created; if the node serving `eth_estimateGas` hasn't
+            // seen that block yet, the target looks codeless and the estimate comes back as the CALLDATA
+            // cost alone (~200k). That cannot fund the CREATE inside `SSTORE2.write` (~200 gas per stored
+            // byte), so the CREATE returns 0 and the tx reverts `DeploymentFailed()` — which is what a
+            // reporter hit on Base Sepolia on every `deploy-code` attempt, in both lanes: 201,616 sent
+            // where 941,331 was needed. Wait for the code to be visible, then PIN the gas ourselves
+            // (never re-read at send time), flooring it at what the payload provably costs.
+            if (i > 0 && tx.to)
+                await waitForCodeAt(publicClient, tx.to);
+            const gas = await pinGas(publicClient, { from: account.address, to: tx.to, data: tx.data, gasFloor: tx.gasFloor });
+            const hash = await wallet.sendTransaction({ to: tx.to, data: tx.data, account, chain: wallet.chain, nonce, gas });
             nonce += 1;
             const receipt = await publicClient.waitForTransactionReceipt({ hash });
             if (receipt.status !== 'success')
@@ -3773,7 +3979,7 @@ async function cmdDeployCode(flags) {
         step('On-chain URI');
         ok(`tokenURI/contractURI resolve ON-CHAIN via the renderer ${metadataRenderer} — any RPC returns the metadata, no server in the graph`);
         if (hasProgram)
-            info(`animation_url computes on-chain via the generator ${generator} · params.keys = "${paramsKeysCsv}" (auto-managed; keep it in sync when adding param keys)`);
+            info(`animation_url computes on-chain via the generator ${generator} — it enumerates this token's params from chain, so there is no key list to maintain`);
         else
             info(`renderer-only — image + attributes computed on-chain by your Solidity renderer(s); no animation_url · ${g('fully on-chain')}, zero dependency outside the EVM`);
         if (hasProgram && !codeDir) {
@@ -4203,6 +4409,18 @@ async function cmdVerify(address, flags) {
                     console.log(`    ${c.orange}⚠${c.reset} no animation_url in the on-chain JSON — the generator field may be missing or unrenderable`);
                 }
             }
+            // The READ-side envelope. Params enumerate on-chain, so the write side is unbounded — but
+            // tokenURI and tokenData assemble EVERY enumerated param per call, and that is what grows.
+            // ~64 keys is the documented design envelope; hard failure only nears at several hundred.
+            // Advisory (never a ✗) — a big surface is a legitimate choice, it just isn't free.
+            const set = await readSetParamKeys(client, state.address, probe ? BigInt(probe.tokenId) : undefined);
+            if (set) {
+                const total = new Set([...set.contract, ...set.token]).size;
+                if (total > 64) {
+                    console.log(`    ${c.orange}⚠${c.reset} ${total} params enumerate on-chain${probe ? ` for token #${probe.tokenId}` : ''} — tokenURI and tokenData assemble every one of them per call, so both grow with this count. ` +
+                        dim('The documented design envelope is ~64; past a few hundred a public eth_call can hit its gas cap.'));
+                }
+            }
         }
         catch (e) {
             console.log(`    ${c.orange}⚠${c.reset} on-chain URI check unavailable: ${e.message}`);
@@ -4381,29 +4599,35 @@ async function reportRemoteByteIntegrity(address, remote, base) {
 // Read tokenURI(id) STRAIGHT FROM THE CONTRACT on-chain (no server, no node) and decode
 // the data: URI. For a fully on-chain token (`--onchain-uri`), this is the proof it
 // self-resolves: the renderer assembles the JSON on-chain; any RPC returns it.
-function decodeOnChainJson(uri) {
+function decodeOnChainJson(uri, verbatim = false) {
     const m = /^data:application\/json(;[^,]*)?,([\s\S]*)$/.exec(uri);
     if (!m)
         return null;
     const raw = (m[1] ?? '').includes('base64') ? Buffer.from(m[2], 'base64').toString('utf8') : decodeURIComponent(m[2]);
     try {
         const obj = JSON.parse(raw);
+        // `verbatim` (--json) returns the document EXACTLY as the chain assembled it. Everything below is
+        // a courtesy for human eyes, and abbreviating for eyes is fine — abbreviating for a PROGRAM is
+        // not. An integrator scraped this output, got a `data:` URI cut to 96 chars that still looked
+        // valid, and stored it; the only way to read their own token was to reimplement `eth_call`.
+        if (verbatim)
+            return JSON.stringify(obj, null, 2);
         for (const k of Object.keys(obj)) {
             const v = obj[k];
             // Truncate only huge inline `data:` blobs (base64 SVGs/images); show plain locator URLs
             // (http/ipfs/ar) IN FULL so the creator can verify where the image actually resolves.
             if (typeof v === 'string' && v.startsWith('data:') && v.length > 96)
-                obj[k] = `${v.slice(0, 96)}… (${v.length} chars)`;
+                obj[k] = `${v.slice(0, 96)}… (${v.length} chars)  [--json for the full value]`;
         }
         return JSON.stringify(obj, null, 2);
     }
     catch {
-        return raw.slice(0, 600);
+        return verbatim ? raw : raw.slice(0, 600);
     }
 }
 async function cmdTokenUri(address, flags) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx tokenuri <address> [--token <id>]\n');
+        console.error('usage: abx tokenuri <address> [--token <id>] [--json]\n');
         process.exit(1);
     }
     if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
@@ -4438,6 +4662,12 @@ async function cmdTokenUri(address, flags) {
         }
         process.exit(1);
     }
+    // --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');
+        return;
+    }
     console.log(`\n  ${bold(`tokenURI(${tokenId})`)} ${dim(`— read directly from ${address} on ${CHAIN}, no server`)}`);
     const json = decodeOnChainJson(uri);
     if (json) {
@@ -4682,7 +4912,7 @@ async function cmdStorage(rest) {
  */
 async function cmdStorageUpload(path, flags) {
     if (!path || path.startsWith('--')) {
-        console.error('usage: abx storage upload <path> [--backend ipfs|arweave|cloud] [--key <name>]\n  uploads one file and prints its locator (the URI `abx attach` wants).\n');
+        console.error('usage: abx storage upload <path> [--backend ipfs|arweave|cloud] [--key <name>] [--json]\n  uploads one file and prints its locator (the URI `abx attach` wants); --json emits it as data.\n');
         process.exit(1);
     }
     const abs = resolvePath(path);
@@ -4694,7 +4924,9 @@ async function cmdStorageUpload(path, flags) {
         throw new Error("the 'fs' backend has no public URL — an attached file must be reachable off this machine. " +
             'Upload with `--backend arweave` (pay-once permanent) or `--backend ipfs` (keep it pinned), or `--backend cloud` (your S3/R2).');
     }
-    noteArweavePlan(opts, bytes.length); // free-vs-credit readout for the arweave lane
+    const jsonMode = flags.json !== undefined;
+    if (!jsonMode)
+        noteArweavePlan(opts, bytes.length); // free-vs-credit readout for the arweave lane
     const name = (flags.key && flags.key !== 'true' ? flags.key : basename(abs)).replace(/^\/+/, '');
     // --dry-run: an upload is IRREVERSIBLE and can happen even keyless (Arweave's free tier under
     // 100 KB auto-creates an identity), so a "preview" that actually uploaded would surprise. Show
@@ -4704,17 +4936,37 @@ async function cmdStorageUpload(path, flags) {
         console.log(`\n  ${bold('◆ storage upload')} ${dim('(dry run — nothing uploaded)')}`);
         console.log(`    ${dim('file'.padEnd(10))} ${basename(abs)} ${dim(`(${bytes.length} bytes, ${contentType})`)}`);
         console.log(`    ${dim('backend'.padEnd(10))} ${backend.id}`);
+        // Name the IPFS mode, and say what an absent credential actually means. There is no silent
+        // fallback to local `fs` (an earlier skill line wrongly claimed one) — without PINATA_JWT the
+        // backend resolves to kubo against a LOCAL node, so a dry run that looked fine would fail at
+        // upload for anyone not running one. A preview should surface that, not defer it to the failure.
+        if (backend.id === 'ipfs' && !process.env.PINATA_JWT && !process.env.ABX_IPFS_MODE) {
+            warn(`no ${bold('PINATA_JWT')} set → this resolves to a LOCAL IPFS node (kubo at ${process.env.ABX_IPFS_API_URL ?? 'http://127.0.0.1:5001'}). The real upload fails unless that node is running — set PINATA_JWT for the managed lane, or ${bold('--backend arweave')} for no-setup permanent storage.`);
+        }
         console.log(`    ${dim('locator'.padEnd(10))} ${shape} ${dim('(filename preserved → declared type survives)')}`);
         console.log(dim(`\n  Re-run without --dry-run to upload, then: `) + `${g(`abx attach <address> <key> ${shape}`)}\n`);
         return;
     }
-    console.log(`  uploading ${bold(basename(abs))} ${dim(`(${bytes.length} bytes, ${contentType})`)} to '${backend.id}' …`);
+    // In --json mode nothing but the JSON may touch stdout; progress still goes out, on stderr.
+    const progress = (line) => (jsonMode ? process.stderr.write(line + '\n') : console.log(line));
+    progress(`  uploading ${bold(basename(abs))} ${dim(`(${bytes.length} bytes, ${contentType})`)} to '${backend.id}' …`);
     // The returned locator MUST carry the filename so the declared mimeType survives when attached
     // (the on-chain field has no MIME slot — the URL extension IS the declaration). uploadAndLocate
     // encapsulates the capability-based branch (cloud key / dir-wrap / bare fallback).
     const { locator, filenamePreserved, fallbackReason } = await uploadAndLocate(backend, name, { bytes, contentType });
     if (!filenamePreserved && fallbackReason) {
-        warn(`couldn't wrap the file with its name (${fallbackReason}) — the locator has no extension, so its declared type will be application/octet-stream when attached.`);
+        const msg = `couldn't wrap the file with its name (${fallbackReason}) — the locator has no extension, so its declared type will be application/octet-stream when attached.`;
+        if (jsonMode)
+            process.stderr.write(`    ⚠  ${msg}\n`);
+        else
+            warn(msg);
+    }
+    // --json: the locator as data, not as prose. An integrator scraped this line, captured the ANSI
+    // colour codes along with the URL, wrote the result into a STORED player URL, and only found out
+    // when it 404'd in production. A value a program needs must be obtainable without parsing output.
+    if (jsonMode) {
+        process.stdout.write(JSON.stringify({ locator, backend: backend.id, name, bytes: bytes.length, contentType, filenamePreserved }) + '\n');
+        return;
     }
     console.log(`  ${g('✓')} uploaded → ${bold(locator)}`);
     if (contentType === 'application/octet-stream') {
@@ -4843,6 +5095,51 @@ 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)')}`);
+    // 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
+    // are maintained by the contract's own write paths, so there is no list to drift. Read-only,
+    // best-effort, and skipped entirely for a project that has none (a 1/1, or a code project with
+    // no params). LEGACY projects (deployed before enumeration) expose neither getter: they fall back
+    // to the retired `params.keys` CSV so `abx state` still describes them.
+    try {
+        let keys = await readParamSchemaKeys(publicClient, address);
+        let legacy = false;
+        if (keys === null) {
+            // The pre-enumeration lane, READ-ONLY. Nothing writes this CSV any more.
+            keys = (await readLegacyParamsKeys(publicClient, address).catch(() => null)) ?? [];
+            legacy = keys.length > 0;
+        }
+        const rows = keys.length
+            ? await Promise.all(keys.map(async (key) => ({ key, s: await readParamSchema(publicClient, address, key) })))
+            : [];
+        const governed = rows.filter((r) => r.s.exists);
+        const now = Math.floor(Date.now() / 1000);
+        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)') : ''));
+            for (const { key, s } of governed) {
+                const retired = s.lockAfter !== 0 && s.lockAfter < now;
+                const locks = s.lockAfter !== 0 && !retired ? dim(`  locks ${new Date(s.lockAfter * 1000).toISOString().slice(0, 10)}`) : '';
+                const tag = retired ? `  ${c.orange}retired${c.reset}${dim(' — writes revert')}` : locks;
+                console.log(`    ${describeSchema({ key, paramType: s.paramType, auth: s.auth, authAddress: s.authAddress, lockAfter: 0, min: s.min, max: s.max, selectOptions: s.selectOptions })}${tag}`);
+            }
+        }
+        // Legacy only: a key the old CSV lists with no schema behind it. On an enumerating project the
+        // class doesn't exist — schema keys come from the schema list, set values from the value lists.
+        const ungoverned = legacy ? rows.filter((r) => !r.s.exists).map((r) => r.key) : [];
+        if (ungoverned.length)
+            info(`${dim('also in params.keys, no schema:')} ${ungoverned.join(', ')}`);
+        // Collection-scope values (every token sees these). `seed` is per-token and never enumerated —
+        // it is a tokenData coordinate, read directly.
+        const set = legacy ? null : await readSetParamKeys(publicClient, address);
+        if (set?.contract.length) {
+            info(`${dim('contract-scope params set:')} ${[...set.contract].sort().join(', ')} ${dim('(apply to every token)')}`);
+        }
+    }
+    catch {
+        /* best-effort — a non-code project has no params surface to read */
+    }
     console.log('');
 }
 /**
@@ -5826,10 +6123,13 @@ const COMMAND_HELP = {
     ${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
-                          (no --public-base-url needed); the ${g('params.keys')} contract param is written automatically from the schema
-                          flags. The marketplace still is rendered off-chain by the effect runner ${bold('for a JS program')} (--script/--code-dir) — but with ${g('--image-renderer')} the image is computed ON-CHAIN too (nothing to render). Verify with ${g('abx verify <addr>')}.
+                          (no --public-base-url needed); the param surface is enumerated ON-CHAIN, so there is nothing to declare or
+                          keep in sync. The marketplace still is rendered off-chain by the effect runner ${bold('for a JS program')} (--script/--code-dir) — but with ${g('--image-renderer')} the image is computed ON-CHAIN too (nothing to render). Verify with ${g('abx verify <addr>')}.
                           (--generator 0x.. / --renderer 0x.. override the canonical singletons; ABX_GENERATOR / ABX_RENDERER via env.)
-    --schema key:Type:Auth,…   governed PostParams (e.g. ${g('palette:HexColor:TokenOwner')}) — reconfigure later with ${g('abx configure-param')}
+    --schema key:Type:Auth,…   governed PostParams (e.g. ${g('palette:HexColor:TokenOwner')}) — set values later with ${g('abx configure-param')},
+                          change the SCHEMA later with ${g('abx set-schema')}. An Address leg names its writer inline —
+                          ${g('key:Type:Address(0x…)')} (a CONTRACT may hold it: the controller pattern for open participation).
+                          Append ${g(':lock=<when>')} (ISO date, unix seconds, or ${g('now')}) to freeze the value after that time.
                           ${dim('repeatable OR comma-separable (like --dep): ')}${g('--schema a --schema b')}${dim(' ≡ ')}${g('--schema a,b')}
                           Type ∈ Bool·Select·Uint256Range·Int256Range·DecimalRange·HexColor·Timestamp·String·Bytes; Auth ∈ Artist·TokenOwner·Address (+ Or-combos).
                           ${bold('a Select declares its options')}: ${g('mood:Select[Calm|Wild|Chaotic]:TokenOwner')}; ${bold('a Range takes bounds')}: ${g('density:Uint256Range[0..100]:TokenOwner')} (Int/Decimal/Timestamp too; bounds optional)
@@ -5854,6 +6154,7 @@ const COMMAND_HELP = {
     --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)')}
+    ${g('--yes')}                 accept inferred --name/--symbol defaults (the real send otherwise REFUSES to bake placeholders)
     ${g('--dry-run')}             preview (address · resolver base · schema · mint plan · tx count) — nothing sent, no bytes pinned
     ${g('--confirm')}             interactive y/N gate before the real send
     ${bold('After deploy — render the marketplace still')} ${dim('(JS lanes only — --script/--code-dir; with --image-renderer the image is on-chain, nothing to render)')}:
@@ -5891,14 +6192,33 @@ const COMMAND_HELP = {
     ${dim('ABX_RESOLVER_ADMIN_TOKEN — and a backend that can name a public URL (cloud/ipfs/arweave), since the resolver takes the')}
     ${dim('URL and refuses the bytes. PUBLIC runner? set ABX_EFFECTS_TOKEN — it gates /run + /notify.')}
     ${dim('To HOST the runner (fly/docker), use `abx deploy-effects`.')}`,
+    'set-schema': `
+  ${bold('abx set-schema')} <address> ${g('--schema key:Type:Auth[:lock=<when>]')} ${dim('— attach or replace ONE PostParam schema. Owner-only. Sends a tx.')}
+    A project's param surface is NOT frozen at deploy: ${g('setParamSchema')} is owner-gated with no deploy-time restriction,
+    so you can add a key a piece turned out to need without redeploying (and losing the address, mints, and collectors).
+    ${bold('This is a full-row upsert, not a patch.')} Replacing an existing schema rewrites every field — restate anything you
+    want to keep, including an existing ${g('lock=')}. The contract does ${bold('not')} re-validate values already stored under the key,
+    so narrowing a bound, dropping a Select option, or changing the type strands them; that is refused unless you pass
+    ${g('--force')}. A key can never be un-governed — to decommission one use ${g('abx retire-param')}.
+    ${g('--force')}             apply a change that could strand already-stored values
+    ${g('--dry-run')}           print the exact tx and send nothing`,
+    'retire-param': `
+  ${bold('abx retire-param')} <address> <key> ${dim('— permanently stop further writes to a PostParam. Owner-only. Sends a tx.')}
+    Sets the schema's ${g('lockAfter')} into the past, so every later ${g('configure-param')} reverts ${g('ParamLockExpired')}. This is the
+    closest the protocol comes to deleting a parameter, and it is ${bold('irreversible')}.
+    Reads the current schema and changes ONLY the lock, so type/auth/bounds/options are carried forward untouched.
+    What it does NOT do: remove the key (a governed key stays governed forever) or erase a value already stored — that
+    value keeps serving in token data. A value written under a TokenOwner/Address leg came from a collector, and the
+    artist deliberately cannot delete it.
+    ${g('--dry-run')}           print the exact tx and send nothing`,
     'configure-param': `
   ${bold('abx configure-param')} <address> <tokenId|-> <key> <value> ${dim('— set a PostParam (typed, canonical encode). Sends a tx.')}
     Reads the on-chain schema for <key> and canonically encodes <value> (${g('#rrggbb')} for HexColor, fixed-decimal ranges,
     Select by label, address, bool). Auth is per the schema leg (Artist=owner · TokenOwner — delegate.xyz honored · Address).
     A change ${bold('re-addresses renders')} → the still becomes a placeholder until you re-render (${g('abx render <addr> <id>')} or the runner).
     ${g('<tokenId> "-"')}        CONTRACT scope (owner-only raw setter; schema-less keys only) — the write path of well-known params
-                          like ${g('params.keys')} / ${g('display.gateway')}. ≤31 printable-ASCII chars ride as a literal bytes32; longer takes the data path.
-                          After a token write, a project whose ${g('params.keys')} doesn't list the key gets a one-line fix suggestion.
+                          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)
     ${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
@@ -6000,7 +6320,8 @@ const COMMAND_HELP = {
     ${g('--dry-run')}             preview the tx, send nothing   ·   signing: ${g('--send')} (default, needs a hot key) · ${g('--sign')} (browser wallet, no key) · ${g('--unsigned')}
     ${dim('Need the URI first? Upload the file with')} ${g('abx storage upload <path> --backend arweave|ipfs')} ${dim('— it prints the locator to pass here.')}
     ${dim('mimeType is declared from the URL EXTENSION (…/master.tiff → image/tiff) — give the file a real extension.')}
-    ${dim('Surfaces in a resolver\'s artifacts listing (/data/<key> fetches it); a bare on-chain tokenURI shows reserved fields only.')}
+    ${dim('Surfaces in a resolver\'s artifacts listing (/data/<key> fetches it); a bare on-chain tokenURI shows reserved fields + abx_params only —')}
+    ${dim('configured params DO appear on-chain (as')} ${bold('abx_params')}${dim('); ATTACHMENTS are the surface that needs a resolver.')}
     ${dim('The image/animation are just reserved members of the same manifest. `artifacts` itself is COMPUTED — not settable.')}`,
     'set-field': `
   ${bold('abx set-field')} <address> --field <name> ${dim('— set an on-chain metadata field (the low-level primitive). Sends a tx.')}
@@ -6008,7 +6329,7 @@ const COMMAND_HELP = {
     --field <name>        a reserved display field (image · description · animation_url · external_url · attributes ·
                           background_color · …), a collection authorship/rights field with ${g('--collection')}
                           (artist · display_notes · artist_links · license), OR any custom key (which becomes an
-                          ${bold('artifacts')} entry). NOT ${g('artifacts')}/${g('abx_provenance')} (computed).
+                          ${bold('artifacts')} entry). NOT ${g('artifacts')}/${g('abx_params')}/${g('abx_provenance')} (computed).
     --text "<s>"          store literal UTF-8 ON-CHAIN (representation defaults ${g('inline')}) — NOT for an off-chain URL (use ${bold('attach')})
     --file <path>         store a FILE on-chain in SSTORE2 chunks behind the shared reader (any size; multi-chunk)
     ${g('--compress')} none|fastlz|gzip   for --file (default none): ${g('fastlz')} = on-chain decode, stays renderable, cheaper storage;
@@ -6070,7 +6391,7 @@ const COMMAND_HELP = {
     storage: `
   ${bold('abx storage')} <show|upload|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('upload')} <path>         upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend …] [--dry-run] [${g('--json')}]
     ${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.')}
@@ -6205,6 +6526,8 @@ function help() {
                             --dep-registry 0x.. · --description "<s>" · --external-url <url> · ${g('--image-base <url>')} (off-chain thumbnails at a deterministic /{id} URL) ·
                             ${g('--attributes-renderer 0x..')} (traits on-chain) · --max N · ${g('--mint-all')}|${g('--mint-count')} N · --backend ipfs|arweave · ${g('--dry-run')}
     ${g('abx configure-param')} <addr> <id> <key> <value>   set a governed PostParam (typed encode; a change re-addresses the render)
+    ${g('abx set-schema')} <addr> --schema key:Type:Auth[:lock=<when>]   attach or replace ONE key's schema, any time after deploy
+    ${g('abx retire-param')} <addr> <key>   stop all further writes to a param, permanently (the closest thing to removing one)
     ${g('abx set-dependency')} <addr> <index> <ref>   declare/replace a code dependency (name@version via the registry pointer, or 0x.. on-chain)
     ${g('abx remove-last-dependency')} <addr> · ${g('abx set-dependency-registry')} <addr> <0x..|none> · ${g('abx lock-dependencies')} <addr>   operate/freeze the set
     ${g('abx render')} <addr> [id…]   render the still + traits ONCE (the repair lane)   [${g('--force')} re-render] [${g('--remote')} [url] publish to a hosted resolver]
@@ -6278,18 +6601,25 @@ function parseSaltFlag(raw) {
 /** Locate the skill folder: the bundled copy beside the compiled CLI (published), else the
  *  canonical repo copy (dev). Returns null if neither is present. */
 function resolveBundledSkill() {
-    // Published layout: dist/main.js → <pkg>/skill (see scripts/bundle-skill.mjs).
-    const pkgDir = resolvePath(fileURLToPath(import.meta.url), '..', '..');
+    const here = fileURLToPath(import.meta.url);
+    const pkgDir = resolvePath(here, '..', '..');
     const bundled = joinPath(pkgDir, 'skill');
+    // Running from SOURCE (`pnpm abx`, tsx on packages/cli/src/**) means we're in the repo working
+    // tree, where the canonical skill is the source of truth and `<pkg>/skill` is gitignored PREPACK
+    // OUTPUT that may be arbitrarily old. Preferring the bundle there is actively destructive: a
+    // leftover `skill/` from a months-old `npm pack` silently overwrote the canonical skill with a
+    // copy 8 versions behind (and the drift check then reported the damage as if the user had caused
+    // it). In the published layout there is no repo and no canonical copy, so the bundle is correct.
+    const fromSource = /[/\\]src[/\\][^/\\]+$/.test(here);
+    const root = findRepoRoot();
+    const canonical = root ? joinPath(root, '.claude', 'skills', 'abx-self-host') : null;
+    if (fromSource && canonical && existsSync(joinPath(canonical, 'SKILL.md')))
+        return canonical;
+    // Published layout: dist/main.js → <pkg>/skill (see scripts/bundle-skill.mjs).
     if (existsSync(joinPath(bundled, 'SKILL.md')))
         return bundled;
-    // Dev layout: the canonical skill in the repo working tree.
-    const root = findRepoRoot();
-    if (root) {
-        const canonical = joinPath(root, '.claude', 'skills', 'abx-self-host');
-        if (existsSync(joinPath(canonical, 'SKILL.md')))
-            return canonical;
-    }
+    if (canonical && existsSync(joinPath(canonical, 'SKILL.md')))
+        return canonical;
     return null;
 }
 /** Locate the in-chain renderer Foundry scaffold: bundled beside the CLI (published), else the
@@ -6361,11 +6691,20 @@ function resolveInstallParents(agentFlag) {
     return [...parents];
 }
 /** Copy the bundled skill folder to `dest`, replacing any prior copy so a re-install after an
- *  upgrade never leaves stale reference files behind. */
+ *  upgrade never leaves stale reference files behind.
+ *
+ *  Returns `'already-canonical'` when destination IS the source, having done nothing. That case is
+ *  not hypothetical: in a dev checkout of the abx repo `resolveBundledSkill()` resolves to the
+ *  canonical `.claude/skills/abx-self-host`, which is exactly where a cwd-relative install writes —
+ *  so the `rmSync` below would delete the canonical skill, and the copy would then have no source.
+ *  A self-destructing install is a bad way to learn that. */
 function installSkillTo(src, dest) {
+    if (resolvePath(src) === resolvePath(dest))
+        return 'already-canonical';
     mkdirSync(joinPath(dest, '..'), { recursive: true });
     rmSync(dest, { recursive: true, force: true });
     cpSync(src, dest, { recursive: true });
+    return 'installed';
 }
 /**
  * Install the bundled skill into the default per-agent parents (or `~` with `global`), reporting
@@ -6379,9 +6718,10 @@ function installSkillToDefaults(src, opts = {}) {
     ok(`installed the abx skill v${version}${opts.global ? ' (global, ~)' : ''}:`);
     for (const parent of parents) {
         const dest = joinPath(base, parent, SKILL_DIR_NAME);
-        installSkillTo(src, dest);
+        const outcome = installSkillTo(src, dest);
         const label = SKILL_PARENT_LABELS[parent];
-        console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${label ? dim('  → ' + label) : ''}`);
+        const note = outcome === 'already-canonical' ? dim('  (already the canonical copy — left as is)') : label ? dim('  → ' + label) : '';
+        console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${note}`);
     }
     info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
     info(`the skill is version-locked to this CLI (v${version}); re-run ${g('abx skill install')} after upgrading so the two stay in sync.`);
@@ -6409,7 +6749,10 @@ async function cmdSkill(rest, flags) {
         // whose skills dir we don't special-case, or a bespoke location).
         if (typeof flags.target === 'string' && flags.target !== 'true') {
             const dest = joinPath(resolvePath(flags.target), SKILL_DIR_NAME);
-            installSkillTo(src, dest);
+            if (installSkillTo(src, dest) === 'already-canonical') {
+                ok(`${dest} is already the canonical skill v${version} — nothing to install.`);
+                return;
+            }
             ok(`installed the abx skill v${version} → ${dest}`);
             info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
             return;