@artblocks/abx-cli 0.1.0-alpha.11 → 0.1.0-alpha.13

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 { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport, readParamsKeys } 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 { 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
@@ -186,6 +210,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);
@@ -708,7 +734,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 +800,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 +810,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 +830,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 +848,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)],
@@ -1222,6 +1329,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 +1648,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')}`);
@@ -2799,14 +2939,25 @@ async function cmdPreview(flags) {
             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
@@ -3613,8 +3764,15 @@ async function cmdDeployCode(flags) {
         // 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)')}`);
-        else
-            info(`  ${dim('stand up the runner:')} ${bold('abx deploy-effects --resolver-url ' + baseUrl)} · one-shot: ${bold('abx render ' + (predicted ?? '<address>') + (onChainUri && hasImageBase ? '' : ' --remote ' + baseUrl))} · verify: ${bold('abx verify ' + (predicted ?? '<address>'))}`);
+        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>'))}`);
+            // Rendering against a resolver you don't share a disk with means YOU hold the bytes and it
+            // holds the URL — so say now which backend that needs, rather than letting the render fail.
+            if (remoteRender && !resolveBackend(storageOptions(storageOverrides(flags))).locator) {
+                info(`  ${dim('that render publishes a URL, so it needs a backend that can name one:')} ${bold('--backend cloud')} ${dim('(S3/R2 + public base) ·')} ${bold('ipfs')} ${dim('·')} ${bold('arweave')} ${dim('— or render co-located with the resolver (`abx effects` on its host).')}`);
+            }
+        }
         if (dirUpload)
             await noteStorageReadiness(storageOptions(storageOverrides(flags)), dirUpload.sizes);
         if (deployer && salt && !parseSaltFlag(flags.salt)) {
@@ -3675,7 +3833,7 @@ 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)
     ].concat(Array.from({ length: setupMintCount }, () => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'mint', args: [owner] }))); // folded mints ride init, not here
@@ -3686,7 +3844,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;
@@ -3738,8 +3896,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')
@@ -3892,6 +4061,10 @@ async function cmdRender(address, tokenIds, flags) {
     const remote = remoteFlag(flags);
     const resolverUrl = (remote?.url ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
     const adminToken = remote ? requireRemoteToken(remote) : undefined;
+    // Refuse the combination that can't work before launching Chromium (a laptop render against a
+    // hosted resolver, on a backend with no public URL) — the render would end in a 400 either way.
+    if (remote)
+        requirePublishableBackend(flags, 'abx render --remote');
     // Co-located (no --remote): record each declared output into the shared store's artifact
     // registry so the local resolver's `artifacts` manifest enumerates it. Remote: the publish
     // lane (adminToken) records rows on the hosted resolver instead.
@@ -3916,6 +4089,41 @@ async function cmdRender(address, tokenIds, flags) {
     else
         ok(summary);
 }
+/**
+ * The publish topology's one hard prerequisite, checked BEFORE any capture.
+ *
+ * A resolver that doesn't share this machine's disk serves referenced output (the still, a video, a
+ * model) by **redirect** — so it needs a URL, and it refuses the bytes (`specs/protocol/effects.md →
+ * Bound vs referenced`). A backend that can't name a locator therefore has no publish lane at all,
+ * and every render against one would be work spent to earn a 400.
+ *
+ * So this refuses up front and names the ways out, rather than warning and letting the render run.
+ * It deliberately does NOT pick a backend for the operator: which store holds their art — and which
+ * gateway serves it — is theirs to decide. The three that work are peers, not a ranking: `https://`
+ * from S3/R2, an IPFS gateway, and Arweave are all fine, because derived output is re-creatable and
+ * the only real requirement is that a third party can fetch it.
+ */
+function requirePublishableBackend(flags, what) {
+    const backend = resolveBackend(storageOptions(storageOverrides(flags)));
+    // `cloud` is the one backend that HAS a locator method and can still return null: the URL is
+    // `<publicBase>/<key>`, so without a public base it can name nothing. Catch that here too — it
+    // would otherwise be the same failure one render later.
+    if (backend.id === 'cloud' && !backend.publicBase) {
+        throw new Error(`${what} hands the resolver a URL for each render, but the 'cloud' backend has no public read base — ` +
+            `set ${bold('ABX_S3_PUBLIC_BASE')} to the bucket's public URL (an R2/CloudFront/S3-website base), ` +
+            `or use ${bold('--backend ipfs')} / ${bold('--backend arweave')}, or render co-located with the resolver.`);
+    }
+    if (backend.locator)
+        return;
+    const { backend: name, source } = backendResolution(storageOverrides(flags));
+    throw new Error(`${what} publishes each render to a resolver that doesn't share this machine's disk, but the '${name}' backend ` +
+        `(${source === 'default' ? 'the default' : `from ${source}`}) can't produce a URL for what it stores — so the resolver would have nothing to serve.\n` +
+        `  Point it at a backend that can (equal options — pick on cost/ops, not durability dogma):\n` +
+        `    ${bold('--backend cloud')}    S3 / R2 / B2 with a public base (ABX_S3_* + ABX_S3_PUBLIC_BASE)\n` +
+        `    ${bold('--backend ipfs')}     Pinata or your own Kubo + a public gateway (PINATA_JWT / ABX_IPFS_*)\n` +
+        `    ${bold('--backend arweave')}  pay-once permanent (uploads under 100KiB are free, no setup)\n` +
+        `  …or run co-located instead: ${bold('abx effects')} on the same host as ${bold('abx serve')}, sharing one backend and no remote token.`);
+}
 /**
  * `abx effects` — run the reference effect runner LOCALLY, in-process (the local counterpart to
  * `abx deploy-effects`, which scaffolds a HOSTED runner). This is what makes a param change / new
@@ -3935,6 +4143,8 @@ async function cmdEffects(flags) {
     // the shared artifact registry so the resolver's `artifacts` manifest enumerates it. With an
     // admin token, the publish lane records rows on the hosted resolver instead.
     const localStore = adminToken ? null : new SqliteStore();
+    if (adminToken)
+        requirePublishableBackend(flags, 'abx effects against a remote resolver');
     const { EffectRunner, renderEffect } = await loadEffects();
     const runner = new EffectRunner({
         resolverUrl,
@@ -4795,6 +5005,36 @@ 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 governed PostParam surface. There is no on-chain enumeration of schema keys, so the source
+    // is the project's own `params.keys` list — which is also what the on-chain generator reads, so
+    // anything missing from it is invisible to renders anyway. Read-only, best-effort, and skipped
+    // entirely for a project that has none (a 1/1, or a code project with no params).
+    try {
+        const csv = await readParamsKeys(publicClient, address);
+        const keys = (csv ?? '').split(',').map((k) => k.trim()).filter((k) => k && k !== 'params.keys');
+        if (keys.length) {
+            const rows = 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`)}`);
+                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}`);
+                }
+            }
+            // Listed but ungoverned: the generator will inject the key with whatever raw value is set (or
+            // nothing). Not an error — say it plainly rather than leaving a silent discrepancy.
+            const ungoverned = rows.filter((r) => !r.s.exists).map((r) => r.key);
+            if (ungoverned.length)
+                info(`${dim('also in params.keys, no schema:')} ${ungoverned.join(', ')}`);
+        }
+    }
+    catch {
+        /* best-effort — a non-code project has no params surface to read */
+    }
     console.log('');
 }
 /**
@@ -5320,10 +5560,16 @@ async function cmdDoctor(flags) {
     try {
         const backend = resolveBackend(storageOptions());
         const h = await backend.health?.();
+        // Whether this backend can name a public URL for what it stores decides one thing operators hit
+        // later: a REMOTE effects runner needs it (the resolver serves referenced output by redirect, so
+        // it takes a URL and refuses bytes). Co-located rendering doesn't care — hence a note, not a fail.
+        const publishable = backend.locator
+            ? 'can publish to a remote resolver'
+            : 'local-only — a remote effects runner needs cloud/ipfs/arweave (co-located rendering is fine)';
         if (h)
-            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''}`);
+            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''} · ${publishable}`);
         else
-            check('storage', true, `${backend.id} · configured`);
+            check('storage', true, `${backend.id} · configured · ${publishable}`);
     }
     catch (err) {
         check('storage', false, `${backendId} · ${err.message}`);
@@ -5532,13 +5778,19 @@ async function cmdDeployEffects(flags) {
     const intervalMs = flags['interval-ms'] ? Number(flags['interval-ms']) : undefined;
     const environmentId = flags['env-id'] ?? process.env.ABX_ENVIRONMENT_ID;
     const storageBackend = process.env.ABX_STORAGE_BACKEND;
-    // A HOSTED runner must publish renders where the resolver can read them — a durable locator
-    // (ipfs/arweave) or a shared bucket (s3). The default `fs` writes to the runner CONTAINER's disk,
-    // which the resolver can't see → the thumbnail never clears. Flag it before scaffolding (not just
-    // in the artifact's comments), since it's the #1 silent misconfig for a hosted effects runner.
+    // A HOSTED runner holds its own render bytes and hands the resolver a URL — that's the whole
+    // topology (`specs/protocol/effects.md → Bound vs referenced`). The default `fs` writes to the
+    // runner CONTAINER's disk, which nothing else can reach, so there is no URL to publish: the runner
+    // now REFUSES to start on that config. Scaffolding it anyway would just deploy a container that
+    // exits, so this is a hard stop rather than the warning it used to be.
     if (!storageBackend || storageBackend === 'fs') {
-        warn(`ABX_STORAGE_BACKEND is ${storageBackend ? "'fs'" : 'unset (defaults to fs)'} — a HOSTED runner can't publish 'fs' renders anywhere the resolver can read ` +
-            `(the thumbnail will stay a placeholder). Set ABX_STORAGE_BACKEND to ${bold('ipfs')} / ${bold('arweave')} (durable locator) or ${bold('s3')} before deploying the runner.`);
+        throw new Error(`ABX_STORAGE_BACKEND is ${storageBackend ? "'fs'" : 'unset (defaults to fs)'} — a hosted runner can't serve renders off its own container disk, ` +
+            `and it refuses to start without a backend that can name a public URL for what it stores.\n` +
+            `  Set ABX_STORAGE_BACKEND to one of (equal options — pick on cost/ops):\n` +
+            `    ${bold('cloud')} (alias s3)  S3 / R2 / B2 with ABX_S3_* + a public base\n` +
+            `    ${bold('ipfs')}             Pinata or your own Kubo + a public gateway\n` +
+            `    ${bold('arweave')}          pay-once permanent (<100KiB uploads are free)\n` +
+            `  …then re-run. (Rendering on the resolver's own host instead? Use ${bold('abx effects')} co-located — no publish lane, no locator needed.)`);
     }
     const repoRoot = findRepoRoot();
     if (!repoRoot) {
@@ -5560,10 +5812,7 @@ async function cmdDeployEffects(flags) {
     const outDir = resolvePath(joinPath(dir, 'effects'));
     console.log(bold(`\n  ABX Self-Host Toolkit — provision effects runner (fly)`));
     info(`resolver: ${bold(cleanResolver)} ${dim('(reads token state + publishes renders here)')}`);
-    info(`storage home: ${bold(storageBackend ?? 'fs')} ${dim('— where rendered thumbnails live; the resolver redirects/serves from here')}`);
-    if (!storageBackend || storageBackend === 'fs') {
-        warn('storage backend is fs (LOCAL) — a HOSTED runner needs a PUBLIC home (ipfs/arweave/s3) so the resolver can serve the render. Set ABX_STORAGE_BACKEND before deploying, or the runner will push raw bytes to the resolver.');
-    }
+    info(`storage home: ${bold(storageBackend)} ${dim('— the runner HOLDS the render bytes here and publishes their URL; the resolver redirects to it and never proxies')}`);
     step('Write the effects artifact (self-contained — Dockerfile.effects + fly.toml + vendored source)');
     mkdirSync(outDir, { recursive: true });
     for (const f of art.files) {
@@ -5772,7 +6021,10 @@ const COMMAND_HELP = {
                           (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>')}.
                           (--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)
@@ -5797,6 +6049,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)')}:
@@ -5807,8 +6060,12 @@ const COMMAND_HELP = {
     No tokenId → sweeps all minted tokens; pass ids (${g('0 1 2')}) to target specific tokens.
     ${g('--force')}               RE-RENDER even when the still already exists — the fix for a bad / blank / timed-out capture
                           (the art is otherwise deterministic, so a plain render idempotent-skips an existing still). Overwrites it (+ republishes on --remote).
-    ${g('--remote [name|url]')}   publish each render to a REMOTE resolver (the locator bridge: upload to ${bold('ABX_STORAGE_BACKEND')}, POST /v1/effect-artifacts).
-                          Idempotent; a re-run restores a resolver that lost its volume. Needs its token (a named remote's
+    ${g('--remote [name|url]')}   register each render with a REMOTE resolver: the bytes go to ${bold('ABX_STORAGE_BACKEND')} (YOU hold them), and
+                          POST /v1/effect-artifacts hands the resolver the URL — it redirects there and never proxies. Traits are the
+                          exception: they stitch into the token JSON, so their content (≤64KB) goes to the resolver itself.
+                          ${bold('Requires a backend that can name a public URL')} — ${g('--backend cloud')} (S3/R2 + public base), ${g('ipfs')}, or ${g('arweave')};
+                          equal options, pick on cost/ops. The default ${g('fs')} is refused up front rather than after the render.
+                          Idempotent; a re-run re-registers rows on a resolver that lost them. Needs its token (a named remote's
                           ${g('ABX_REMOTE_<NAME>_TOKEN')}, else ${g('ABX_RESOLVER_ADMIN_TOKEN')}).
     --effects-url <url>   enqueue on a running effect-runner service instead of rendering inline (else ${g('ABX_EFFECTS_URL')})
     ${dim('Inline (no --remote) renders on THIS machine (needs `npx playwright install chromium` once), pointing Chromium at the live')}
@@ -5825,9 +6082,30 @@ const COMMAND_HELP = {
     --port <n>            HTTP port (default ${g('ABX_EFFECTS_PORT')} / 8788) — ${g('POST /notify')} enqueues (watcher lane) · ${g('POST /run')} sweeps synchronously (command lane)
     --interval-ms <n>     the SAFETY-FLOOR sweep (default ${g('ABX_EFFECTS_INTERVAL_MS')} / 300000) — catches a missed notify / cold start; the watcher is the trigger
     --concurrency <n>     parallel renders while draining (default ${g('ABX_EFFECTS_CONCURRENCY')} / 1 — Chromium is heavy; raise deliberately)
-    ${dim('Co-located with a local `abx serve` (same store) → no tokens needed. Against a REMOTE resolver: --remote <name|url> (its')}
-    ${dim('token publishes renders + reports status), or ABX_RESOLVER_URL + ABX_RESOLVER_ADMIN_TOKEN. PUBLIC runner? set ABX_EFFECTS_TOKEN — it gates /run + /notify.')}
+    ${dim('Co-located with a local `abx serve` (same store) → no tokens needed, any backend works (fs included).')}
+    ${dim('Against a REMOTE resolver: --remote <name|url> (its token registers renders + reports status), or ABX_RESOLVER_URL +')}
+    ${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,
@@ -6142,6 +6420,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]
@@ -6215,18 +6495,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
@@ -6298,11 +6585,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
@@ -6316,9 +6612,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.`);
@@ -6346,7 +6643,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;