@artblocks/abx-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/main.js

@@ -14,6 +14,7 @@
  *   abx demo                 deploy a 1/1 to Sepolia, index it, and serve it
  *   abx deploy [--image ..]  deploy + index a 1/1 (--image to custody your own bytes; --no-mint to defer)
  *   abx predict [--salt ..]  pre-compute a deploy address (reserve / vanity it before signing)
+ *   abx preview              run a code project on localhost while it's still being made (no chain)
  *   abx deploy-code          deploy a code project (SeriesCode): --script <file> (on-chain template)
  *                            or --code-dir <dir> (build directory → ipfs/arweave `code` field)
  *   abx add <address>        register + index a project (--remote: on a hosted resolver, not this machine)
@@ -57,6 +58,7 @@ import { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUri
 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 { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
 /** The `--schema` type/auth/format catalog, shown wherever the CLI nudges `--schema`. Kept accurate
@@ -134,7 +136,7 @@ async function maybeNotifyUpdate(flags) {
         const latest = await checkForCliUpdate(current);
         if (latest) {
             console.error(`\n    ${c.orange}⚠${c.reset}  update available: ${bold('abx')} ${dim(current)} → ${g(latest)}\n` +
-                `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx abx@latest <command>')}\n` +
+                `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx @artblocks/abx-cli@latest <command>')}\n` +
                 `       release notes: https://github.com/ArtBlocks/abx/releases ${dim('· silence: ABX_NO_UPDATE_CHECK=1')}\n`);
         }
     }
@@ -166,6 +168,7 @@ async function main() {
         case 'deploy-series': return cmdDeploySeries(flags);
         case 'deploy-code': return cmdDeployCode(flags);
         case 'inspect': return cmdInspect(rest[0], flags);
+        case 'preview': return cmdPreview(flags);
         case 'scaffold-renderer': return cmdScaffoldRenderer(rest, flags);
         case 'predict': return cmdPredict(flags);
         case 'add': return cmdAdd(rest[0], flags);
@@ -984,7 +987,24 @@ async function cmdDeploy(flags, serveAfter) {
     // lockable) — mirrors the description model. On-chain wins if both ever set the same trait.
     const traits = parseDeployTraits(flags);
     console.log(bold(`\n  ABX Self-Host Toolkit — ${serveAfter ? 'demo' : 'deploy'}\n  ${dim('a project, served from chain alone')}`));
-    const lane = serveAfter ? 'send' : laneFromFlags(flags); // demo is always hot (one-shot)
+    // Signing lane. `demo` used to hard-force the hot lane, which SILENTLY dropped `--sign`: with no
+    // env key it died confusingly, and WITH one it signed from that key while the operator had asked
+    // for their browser wallet — a signing choke point that ignored the lane it was handed. The demo
+    // deploy is a single tx, so the wallet lane works here exactly as it does for `deploy`.
+    const lane = laneFromFlags(flags);
+    // The cold lane only PRINTS a tx; demo's whole point is to index + serve what it just deployed,
+    // and there is nothing to index until someone broadcasts. Refuse the combo instead of doing
+    // half the job — `abx deploy --unsigned` is the command for that lane.
+    if (serveAfter && lane === 'unsigned') {
+        throw new Error('`abx demo --unsigned` can\'t work: the cold lane only prints a transaction, and the demo ' +
+            'indexes + serves the contract it just deployed. Use `abx demo` (hot key) or `abx demo --sign` ' +
+            '(browser wallet) — or `abx deploy --unsigned` if you only want the raw tx.');
+    }
+    // Same shape for --dry-run: previewing sends nothing, so there is nothing to serve.
+    if (serveAfter && flags['dry-run']) {
+        throw new Error('`abx demo --dry-run` can\'t work: a dry run sends nothing, and the demo indexes + serves what ' +
+            'it deployed. Use `abx deploy --dry-run` to preview a 1/1 deploy without sending.');
+    }
     const dryRun = !serveAfter && !!flags['dry-run']; // preview only — no send, no custody, no factory deploy
     const publicClient = makePublicClient({ chainKey: CHAIN });
     // Verify the RPC really is CHAIN before any send (factory/renderer/staging/deploy). A dry run
@@ -2227,6 +2247,78 @@ async function ensureSeedSource(publicClient) {
  * Schemas: --schema key:Type:Auth[,key:Type:Auth…] (e.g. palette:HexColor:TokenOwner).
  * Seeds: canonical randomizer by default; --no-seed opts out.
  */
+/**
+ * `abx preview` — serve the program on localhost, live, for as long as the work is being made.
+ *
+ * The studio lane, and deliberately the FIRST thing to reach for on a code project: it renders the
+ * same document the generator serves (real `abx.js`, real tokenData shape, real dependency tags)
+ * with a synthetic seed, so a creator can refresh for new seeds, drive their PostParams from real
+ * inputs, and watch an animated piece actually move — none of which a still-image sweep can show.
+ * No chain, no key, no deploy. `--shoot` renders the same document headlessly for an agent that
+ * can't open a browser.
+ */
+async function cmdPreview(flags) {
+    warnStrayFlags(flags, PREVIEW_FLAGS, 'preview');
+    const cfg = previewConfigFromFlags(flags);
+    const shootDir = flags.shoot && flags.shoot !== 'true' ? String(flags.shoot) : flags.shoot === 'true' ? 'abx-preview' : undefined;
+    const count = Math.min(Math.max(Number(flags.count ?? 9) || 9, 1), 64);
+    console.log(bold(`\n  ABX Self-Host Toolkit — preview\n  ${dim('the program, running locally — no chain, no deploy')}`));
+    const { notes } = previewDepTags(cfg.deps);
+    step('Program');
+    info(cfg.source.kind === 'dir' ? `directory build ${cfg.source.path}/ (its own index.html + abx.js)` : `script ${cfg.source.path} ${dim('(re-read from disk on every render)')}`);
+    if (cfg.schemas.length)
+        info(`params: ${cfg.schemas.map(describeSchema).join(' · ')}`);
+    else
+        info(dim('params: none declared — add --schema key:Type:Auth to drive them from the studio'));
+    for (const n of notes)
+        info(`dep ${n}`);
+    // A raw on-chain dependency can't be fetched without a chain, so the preview would render a
+    // sketch missing its runtime and look broken for the wrong reason. Say so rather than let them
+    // debug their own art.
+    if (cfg.deps.some((d) => d.display.startsWith('0x'))) {
+        warn('an on-chain data-contract dep is NOT loaded in preview — the sketch will run without it here. Use a name@version ref to preview against the CDN copy.');
+    }
+    const server = await startPreviewServer(cfg, shootDir ? 0 : Number(flags.port ?? DEFAULT_PREVIEW_PORT));
+    if (shootDir) {
+        step(`Render ${count} seeds headlessly`);
+        try {
+            const shots = await shootPreview(server.url, shootDir, count, {
+                width: Number(flags.width ?? 1000) || 1000,
+                timeoutMs: Number(flags['timeout-ms'] ?? 10_000) || 10_000,
+            });
+            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())')}`);
+            }
+            const silent = shots.filter((s) => !s.traits || !Object.keys(s.traits).length).length;
+            if (silent === shots.length) {
+                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) {
+                // 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
+                // warning above already covers that, and firing both reads as noise.
+                warn('every seed produced identical traits — check the sketch actually reads `abx.tokenData.seed` (the silent "all tokens the same" failure).');
+            }
+        }
+        finally {
+            await server.close();
+        }
+        return;
+    }
+    step('Studio');
+    console.log(`\n  ${g('●')} ${bold('preview')}  ${server.url}`);
+    console.log(`    ${dim('studio     ')}${server.url}          ${dim('seed + params + live traits')}`);
+    console.log(`    ${dim('grid       ')}${server.url}/grid     ${dim('9 seeds at once, all live')}`);
+    console.log(`    ${dim('bare view  ')}${server.url}/view     ${dim('the generator document itself')}`);
+    console.log(`\n  ${dim('Edit the program and refresh — it is re-read from disk. Ctrl-C to stop.')}`);
+    console.log(`  ${dim('This is a preview: `abx inspect` is still the wiring check, and a testnet deploy is the faithful end-to-end.')}\n`);
+    await new Promise(() => { }); // block like `serve` — the creator drives it
+}
 /**
  * `abx inspect <script.js>` — read a generative script and, WITHOUT executing it, report what it
  * needs (traits + their on-chain reproducibility, dependency hints, size → assembled-document size →
@@ -4167,114 +4259,109 @@ async function cmdMigrate(address, flags) {
 }
 // ── doctor ────────────────────────────────────────────────────────────────--
 async function cmdDoctor(flags) {
-    console.log(bold('\n  abx doctor\n'));
-    const check = (label, pass, detail = '') => console.log(`  ${pass ? g('✓') : `${c.red}✗${c.reset}`} ${label}${detail ? dim('  ' + detail) : ''}`);
+    console.log(bold('\n  abx doctor') + dim(`  ·  ${CHAIN}`) + '\n');
+    // Two visual tiers: PASS/FAIL checks (✓/✗) for things that are either working or broken, and an
+    // "Optional" block (·) for path-dependent setup that is fine to be unset. We deliberately do NOT
+    // use ⚠ for "unset but often fine" — that read as noise; ⚠ is reserved for a real gotcha (a
+    // range-capped RPC). Labels are padded so both tiers align.
+    const CONT = ' '.repeat(17); // continuation indent: aligns under a check/opt detail column
+    const check = (label, pass, detail = '') => console.log(`  ${pass ? g('✓') : `${c.red}✗${c.reset}`} ${label.padEnd(13)}${detail ? dim(detail) : ''}`);
+    const opt = (label, detail) => console.log(`  ${dim('·')} ${label.padEnd(13)}${dim(detail)}`);
     const hasKey = !!(process.env.ABX_DEPLOYER_PK ?? process.env.SEPOLIA_FUNDED_PK ?? process.env.SEPOLIA_WALLET_PK);
-    // Not having an env key is NOT fatal: the wallet lane (`--sign`) signs in the user's own wallet,
-    // key-free. Only flag it as a soft note + point at the lanes — never imply "paste a private key."
-    if (hasKey)
-        check('signing key in env', true, 'hot lane ready (env key signs unattended)');
-    else
-        console.log(`  ${c.orange}⚠${c.reset} signing key in env${dim('  none — fine if you sign in your own wallet (`--sign`; the key never touches the CLI). Only set ABX_DEPLOYER_PK / SEPOLIA_FUNDED_PK / SEPOLIA_WALLET_PK for hot/unattended signing.')}`);
+    // 1. Agent skill — FIRST and prominent. The primary way to use abx is to let a coding agent drive
+    //    it, so a missing/stale skill is a ✗: not broken infra, but the main UX isn't set up. Its
+    //    version lives in SKILL.md frontmatter (version-locked to this CLI). Notify-only — no exit code.
+    const cliVersion = readCliVersion();
+    const skillVersions = installedSkillVersions();
+    const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
+    if (skillVersions.length === 0) {
+        check('agent skill', false, `not installed — run ${g('abx skill install')}`);
+        console.log(`${CONT}${dim('(recommended: let a coding agent drive abx)')}`);
+    }
+    else if (staleSkills.length > 0) {
+        check('agent skill', false, `v${staleSkills.join(', v')} behind CLI v${cliVersion} — run ${g('abx skill install')}`);
+    }
+    else {
+        check('agent skill', true, `in sync (v${cliVersion})`);
+    }
+    console.log('');
+    // 2. Core environment (✓/✗). Signing-wallet balances are computed here (they need the RPC) but
+    //    printed in the Optional block below, so buffer them.
+    let signingOpt = null;
+    let forOpt = null;
     try {
         const publicClient = makePublicClient({ chainKey: CHAIN });
         const bn = await publicClient.getBlockNumber();
-        check(`RPC reachable (${CHAIN})`, true, `head block ${bn}`);
-        // RPC endpoints — probe each for reachability, getLogs range, and archive depth,
-        // so the toolkit uses (and recommends) the one fit for the job — and says so if none are.
+        // Collapse the RPC report to one line (best endpoint + head), and only add a ⚠ when there is a
+        // genuine problem — a range-capped-only set that will grind a resolver under load.
         const probes = await probeRpcEndpoints({ chainKey: CHAIN });
         const usable = probes.filter((pr) => pr.verdict !== 'unusable');
         const best = probes.find((pr) => pr.verdict === 'best') ?? usable[0];
-        check(`RPC endpoints for ${CHAIN} (${probes.length})`, usable.length > 0, usable.length > 0
-            ? `best for reconstruction: ${best.label} (${best.verdict === 'best' ? 'wide range + archive' : 'usable, range-capped'})`
-            : 'none usable for reconstruction');
-        for (const pr of probes) {
-            const glyph = pr.verdict === 'best' ? g('✓') : pr.verdict === 'capped' ? `${c.orange}⚠${c.reset}` : `${c.red}✗${c.reset}`;
-            console.log(`      ${glyph} ${pr.label} ${dim('— ' + (pr.verdict === 'best' ? 'wide getLogs range + archive' : pr.reason ?? pr.verdict))}`);
-        }
-        if (usable.length === 0) {
-            console.log(`  ${c.orange}↳${c.reset} ${dim('research a current free archive RPC with a wide getLogs range and add it to ABX_RPC_URLS — see the skill’s “Choosing an RPC”')}`);
-        }
-        else if (!probes.some((pr) => pr.verdict === 'best')) {
-            // Every usable endpoint is range-capped. Indexing still works (chunking), but a first
-            // reconstruction — and a resolver under marketplace load — is slow + rate-limit-prone. That's
-            // a serious infra signal, NOT "a paid plan is required": flag it. A normal deploy→index only
-            // scans from the deploy block, so this bites first reconstructions and busy resolvers most.
-            console.log(`  ${c.orange}⚠ every usable RPC is getLogs-range-capped${c.reset} ${dim('— add a wide-range archive endpoint to ABX_RPC_URLS before running a resolver under load; capped ones grind on wide scans (skill → “Choosing an RPC”).')}`);
-        }
-        if (hasKey) {
-            const { account } = makeWalletClient({ chainKey: CHAIN });
-            const bal = await publicClient.getBalance({ address: account.address });
-            check('deployer funded', bal > 0n, `${account.address} · ${formatEther(bal)} ETH`);
-        }
-        // Wallet lane has no env key — let a creator preflight THEIR OWN signing wallet's balance,
-        // the one gap where an unfunded wallet otherwise only surfaces at the signing step.
-        if (flags.for) {
-            const bal = await publicClient.getBalance({ address: flags.for });
-            check('wallet funded (--for)', bal > 0n, `${flags.for} · ${formatEther(bal)} ETH${bal > 0n ? '' : ` — ${faucetHint(CHAIN)}`}`);
+        if (usable.length > 0) {
+            check('RPC', true, `${best.label} · head ${bn} · ${best.verdict === 'best' ? 'wide range + archive' : 'range-capped'}`);
+            if (!probes.some((pr) => pr.verdict === 'best')) {
+                console.log(`${CONT}${c.orange}⚠${c.reset}${dim(' every endpoint is getLogs-range-capped — add a wide-range archive RPC to ABX_RPC_URLS before running a resolver under load')}`);
+            }
         }
-        else if (!hasKey) {
-            console.log(`  ${dim('↳ wallet lane: run `abx doctor --for 0x<your wallet>` to check your signing wallet is funded')}`);
+        else {
+            check('RPC', false, `${CHAIN} — no endpoint usable for reconstruction; add a wide-range archive RPC to ABX_RPC_URLS`);
         }
         const factory = factoryAddress();
         if (factory) {
             const code = await publicClient.getCode({ address: factory });
-            if (!code || code === '0x') {
-                check('canonical factory deployed', false, `${factory} — no code on ${CHAIN}; \`abx deploy\` redeploys`);
-            }
-            else if (await isCurrentFactory(publicClient, factory)) {
-                check('canonical factory deployed', true, factory);
-            }
-            else {
-                check('canonical factory deployed', false, `${factory} — older/incompatible version; \`abx deploy\` redeploys`);
-            }
+            if (!code || code === '0x')
+                check('factory', false, `${factory} — no code on ${CHAIN}; \`abx deploy\` redeploys`);
+            else if (await isCurrentFactory(publicClient, factory))
+                check('factory', true, factory);
+            else
+                check('factory', false, `${factory} — older/incompatible; \`abx deploy\` redeploys`);
         }
         else {
-            check('canonical factory deployed', false, 'none yet — `abx demo` deploys one');
+            check('factory', false, 'none yet — `abx demo` deploys one');
+        }
+        if (hasKey) {
+            const { account } = makeWalletClient({ chainKey: CHAIN });
+            const bal = await publicClient.getBalance({ address: account.address });
+            signingOpt = `env key ${account.address} · ${bal > 0n ? `funded ${formatEther(bal)} ETH` : `empty — fund it (${faucetHint(CHAIN)})`}`;
+        }
+        if (flags.for) {
+            const bal = await publicClient.getBalance({ address: flags.for });
+            forOpt = `${flags.for} · ${bal > 0n ? `funded ${formatEther(bal)} ETH` : `empty — ${faucetHint(CHAIN)}`}`;
         }
     }
     catch (err) {
-        check('RPC reachable', false, err.message);
+        check('RPC', false, err.message);
     }
-    // public base URL — baked into on-chain URIs at deploy; unset is fine for a demo
-    // but a silent footgun for a real launch, so surface it explicitly.
-    const baseUrl = process.env.ABX_PUBLIC_BASE_URL;
-    if (baseUrl)
-        check('public base URL set (baked into on-chain URIs)', true, baseUrl);
-    else
-        console.log(`  ${c.orange}⚠${c.reset} public base URL${dim('  ABX_PUBLIC_BASE_URL unset → resolver-served deploys REFUSE (localhost on-chain resolves for no one). Set it (or --public-base-url) for a hosted resolver. IRRELEVANT if you go fully on-chain: --onchain-image (1/1) or --onchain-uri (code project) bake no resolver base.')}`);
     // storage backend — resolve it (catches missing config), then probe liveness/creds
     const backendId = activeBackendId();
     try {
         const backend = resolveBackend(storageOptions());
         const h = await backend.health?.();
         if (h)
-            check(`storage backend '${backend.id}' reachable`, h.ok, h.detail ?? '');
+            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''}`);
         else
-            check(`storage backend '${backend.id}' configured`, true);
+            check('storage', true, `${backend.id} · configured`);
     }
     catch (err) {
-        check(`storage backend '${backendId}' configured`, false, err.message);
+        check('storage', false, `${backendId} · ${err.message}`);
     }
-    // Managed Turbo/Arweave key — if it exists, it holds prepaid credits, so remind them to back it up.
+    // 3. Optional — path-dependent setup. Unset is fine; these say WHEN you'll need each, so an unset
+    //    value never reads as a warning.
+    console.log(`\n  ${dim('Optional — depends how you deploy:')}`);
+    if (signingOpt)
+        opt('signing', signingOpt);
+    else
+        opt('signing', 'no env key → sign in your browser wallet (--sign). Preflight yours: `abx doctor --for 0x<addr>`. Set ABX_DEPLOYER_PK for the unattended hot lane.');
+    if (forOpt)
+        opt('wallet --for', forOpt);
+    const baseUrl = process.env.ABX_PUBLIC_BASE_URL;
+    if (baseUrl)
+        opt('resolver URL', baseUrl);
+    else
+        opt('resolver URL', 'ABX_PUBLIC_BASE_URL unset → needed for off-chain/resolver-served deploys; skip if fully on-chain (--onchain-image / --onchain-uri).');
     if (!process.env.ARWEAVE_JWK && existsSync(arweaveKeyFilePath())) {
         const jwk = loadArweaveJwk();
-        console.log(`  ${dim('↳ Turbo/Arweave key ' + (jwk ? arweaveAddress(jwk) + ' ' : '') + 'holds your upload credits — back it up: `abx storage backup-key --out <path>`')}`);
-    }
-    // Agent skill co-versioning — the skill drives this CLI and is version-locked to it (its version
-    // lives in SKILL.md frontmatter). Report any installed copy and flag drift; notify-only, so a
-    // stale/absent skill never fails doctor (`abx skill install` resyncs).
-    const cliVersion = readCliVersion();
-    const skillVersions = installedSkillVersions();
-    const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
-    if (skillVersions.length === 0) {
-        console.log(`  ${dim('↳ agent skill: not installed here — `abx skill install` so a coding agent can drive abx')}`);
-    }
-    else if (staleSkills.length > 0) {
-        console.log(`  ${c.orange}⚠${c.reset} agent skill behind CLI${dim(`  installed v${staleSkills.join(', v')} · CLI v${cliVersion} — refresh: `)}${g('abx skill install')}`);
-    }
-    else {
-        check(`agent skill in sync (v${cliVersion})`, true);
+        opt('arweave key', `${jwk ? arweaveAddress(jwk) + ' ' : ''}holds upload credits — back it up: \`abx storage backup-key --out <path>\``);
     }
     console.log('');
 }
@@ -4639,6 +4726,20 @@ const COMMAND_HELP = {
       ${g('abx deploy-series')} --dir ./photos --name "My Series" --symbol MS --onchain-uri --backend ipfs --mint-all --sign
       ${dim('# tiny SVGs → fully on-chain (no storage at all):')}
       ${g('abx deploy-series')} --dir ./svgs --name "My Series" --symbol MS --onchain-image --compress fastlz --mint-all --sign`,
+    preview: `
+  ${bold('abx preview')} (--script <file.js> | --code-dir <dir>) ${dim('— run the program on localhost, live. No chain, no key, no deploy.')}
+    ${g('--schema key:Type:Auth')}[,…]  declare PostParams so the studio gives you real inputs for them (e.g. palette:HexColor:TokenOwner)
+    ${g('--dep <name@version>')}[,…]    load a library the way the resolver would (built-in CDN map; on-chain refs can't be fetched offline)
+    ${g('--port')} <n>                  studio port (default ${DEFAULT_PREVIEW_PORT}; the resolver's ${DEFAULT_PORT} stays free)
+    ${g('--shoot')} <dir>               render headlessly to PNGs + traits.json and EXIT ${dim('(for an agent that has no browser)')}
+    ${g('--count')} <n>                 seeds to shoot / show in the grid (default 9)   ${g('--width')} <px>   ${g('--timeout-ms')} <n>
+    Serves the ${bold('same document the generator serves')} — real ${g('abx.js')}, real tokenData shape, real dep tags — with a synthetic
+    seed, so what you iterate on is what deploys. Routes: ${g('/')} studio (seed + params + live traits) · ${g('/grid')} N seeds at once,
+    all live · ${g('/view')} the bare document. The program is re-read from disk per render, so ${bold('edit and refresh')} — no watcher.
+    Unlike a still-image sweep this shows ${bold('animation')}, which is most of what a screenshot throws away.
+    ${dim('Still do both after the art settles:')} ${g('abx inspect')} ${dim('(is it wired right?) and a testnet deploy (the faithful end-to-end).')}
+      ${g('abx preview')} --script art.js --schema palette:HexColor:TokenOwner
+      ${g('abx preview')} --script art.js --shoot ./frames --count 12`,
     inspect: `
   ${bold('abx inspect')} <script.js> ${dim('— static analysis of a generative script + a lane recommendation. Read-only; the script is never executed.')}
     ${g('--dep <name@version>[,…]')}   the on-chain deps you plan to declare, so the assembled-document size estimate is realistic (e.g. --dep p5@1.0.0)
@@ -4896,7 +4997,10 @@ const COMMAND_HELP = {
     ${g('upload')} <path>         upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend …] [--dry-run]
     ${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.')}`,
+  ${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.')}
+    ${g('--sign')}               ${dim('approve in your browser wallet instead of a hot env key (no key needed)')}
+    ${g('--for')} <0x…>          ${dim('pin who must connect on --sign (owner + royalty receiver + mint recipient)')}
+  ${dim('--unsigned / --dry-run are refused here: both skip the broadcast, and the demo indexes + serves what it deployed.')}`,
     minter: `
   ${bold('abx minter')} <configure|show|buy> <token> ${dim('— sell a Series via the shared fixed-price minter (Minter spine).')}
     ${g('configure')} <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x..]   ${dim('(token-owner only)')}
@@ -4990,7 +5094,9 @@ function help() {
                             project + notify the effects layer on change (${g('ABX_WATCH_INTERVAL_MS')}; 0 = off)
 
   ${bold('code / generative projects')} ${dim('— a program is the content; output is a function of live on-chain state')}
-    ${g('abx inspect')} <script.js>   ${bold('start here')} — static analysis (traits + on-chain reproducibility, deps, doc size → RPC viability) + a lane recommendation
+    ${g('abx preview')} (--script <f> | --code-dir <d>)   ${bold('while you are still making it')} — run the program on localhost, live: refresh for new seeds,
+                            drive your PostParams, watch it animate. Same document the generator serves. ${g('--shoot <dir>')} for headless frames. No chain.
+    ${g('abx inspect')} <script.js>   ${bold('before you pick a lane')} — static analysis (traits + on-chain reproducibility, deps, doc size → RPC viability) + a lane recommendation
     ${g('abx scaffold-renderer')} [<dir>]   write a buildable Foundry project for the ${bold('in-chain Solidity art lane')} (seed + PostParam → on-chain SVG + traits; you forge build/test/deploy)
     ${g('abx deploy-code')} (--script <file> | --code-dir <dir> | ${g('--image-renderer 0x..')})   deploy a ${bold('generative / code project')} (on-chain script, a build directory, or a Solidity SVG renderer — in-chain art)
                             ${bold('--public-base-url <url>')} OR ${bold('--onchain-uri')} · --schema key:Type:Auth · ${g('--dep')} name@version|0x.. (ordered; index 0 = the runtime) ·