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

package/dist/main.js

@@ -43,7 +43,7 @@
  * the tx for a multisig / offline signer). The agent picks the lane; the CLI signs.
  */
 import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -60,6 +60,7 @@ import { AGENT_SKILL_PARENTS, checkForCliUpdate, compareVersions, installedSkill
 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 { 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 —
@@ -77,7 +78,7 @@ import { cmdTransfer, cmdMint, cmdSetMinter, cmdSetMaxInvocations, cmdConfigureP
 import { openWalletSession, signTx } from './signer.js';
 import { remoteAddProject, remoteRemoveProject } from './remote.js';
 import { buildMigrationPlan, repinNodeCustody, verifyParity } from './migrate.js';
-import { activeBackendId, arweaveKeyFilePath, backendResolution, ensureArweaveJwk, factoryAddress, seriesFactoryAddress, fixedPriceMinterAddress, loadArweaveJwk, loopbackBaseUrl, rendererAddress, storageOptions, storageSignerChoice, } from './config.js';
+import { activeBackendId, arweaveKeyFilePath, backendResolution, ensureArweaveJwk, factoryAddress, seriesFactoryAddress, fixedPriceMinterAddress, loadArweaveJwk, loopbackBaseUrl, faucetHint, rendererAddress, storageOptions, storageSignerChoice, } from './config.js';
 const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY;
 // Block explorer base per chain (keyed by EIP-155 chainId), for the tx/address links the CLI prints.
 const EXPLORERS = {
@@ -297,17 +298,6 @@ async function detectCanonicalFactory(address, override, stored) {
     }
     return factoryAddress() ?? undefined;
 }
-/** A short faucet pointer for the active testnet — a 0-balance signer's #1 next step. A known URL
- *  plus a search hint (URLs rot; the search always works), so "fund it" isn't a dead end. */
-function faucetHint(chainKey) {
-    const url = {
-        'base-sepolia': 'https://portal.cdp.coinbase.com/products/faucet',
-        sepolia: 'https://www.alchemy.com/faucets/ethereum-sepolia',
-    };
-    return url[chainKey]
-        ? `get free test ETH from a ${chainKey} faucet (${url[chainKey]} — or search "${chainKey} faucet"), usually ≤1 min`
-        : `get test ETH from a "${chainKey}" faucet`;
-}
 // Funding preflight — a 0-balance signer fails only at the tx, with a confusing error. Surface it
 // up front. Especially the wallet lane (--sign/--for), which has no env key for `doctor` to check.
 async function warnUnfunded(publicClient, address) {
@@ -986,7 +976,9 @@ async function cmdDeploy(flags, serveAfter) {
     // editable later via `abx add --traits`); `--traits-onchain` inlines them on-chain (durable,
     // 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')}`));
+    console.log(serveAfter
+        ? bold(`\n  ABX · your first token\n  ${dim("we'll put art on a blockchain — then delete our copy and get all of it back")}`)
+        : bold(`\n  ABX Self-Host Toolkit — deploy\n  ${dim('a project, served from chain alone')}`));
     // 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
@@ -1005,6 +997,17 @@ async function cmdDeploy(flags, serveAfter) {
         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.');
     }
+    // Port preflight BEFORE anything irreversible. The demo ends by serving, and `listen` used to be
+    // the first thing to discover the port was taken — after the deploy tx had already been signed and
+    // paid for, so a second `abx demo` (a very normal thing to try) spent gas and then died with a raw
+    // Node EADDRINUSE stack trace. Check first, and name the fix.
+    if (serveAfter) {
+        const wanted = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
+        if (await portInUse(wanted)) {
+            throw new Error(`port ${wanted} is already in use — probably an \`abx demo\`/\`abx serve\` still running in another terminal.\n` +
+                `  Nothing was deployed. Stop that one (Ctrl-C), or run this on another port: \`abx demo --port ${wanted + 1}\`.`);
+        }
+    }
     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
@@ -1035,7 +1038,7 @@ async function cmdDeploy(flags, serveAfter) {
         if (signer)
             await warnUnfunded(publicClient, signer);
     }
-    step('Trust anchor');
+    step(serveAfter ? 'Who vouches for this token?' : 'Trust anchor');
     let factory;
     if (dryRun) {
         const existing = factoryAddress(flags.factory);
@@ -1050,24 +1053,47 @@ async function cmdDeploy(flags, serveAfter) {
     else {
         factory = await ensureFactory(flags.factory, !!flags['bootstrap-factory']);
     }
+    // The demo explains what it just did; `deploy` stays terse. The authenticity point is the least
+    // obvious thing about ABX and the easiest to get wrong, so it's worth spelling out — but in plain
+    // language, with the actual term parked in a dim aside for whoever wants to look it up.
+    if (serveAfter) {
+        console.log(`    ${g('✦')} anyone can write a contract that ${bold('claims')} to be an ABX token`);
+        console.log(`    ${g('✦')} only this one factory can make a token that ${bold('is')} one`);
+        info(dim('so "is this real?" is a yes/no question anyone can ask the chain — not a matter of trusting us'));
+        info(dim(`the factory answers it on-chain: isAbxClone(yourToken) · ${EXPLORER}/address/${factory}`));
+    }
     // --onchain-uri: resolve tokenURI/contractURI fully on-chain via the canonical renderer
     // (the JSON is assembled from on-chain fields → no resolver needed, ever). The off-chain
     // URLs are still baked as a fallback if the renderer is later cleared.
     // --onchain-image: stage the --image bytes on-chain (chunk store, ownerless) and bake a
     // `reader` field into the deploy — so large on-chain content needs NO post-deploy tx. It
     // implies on-chain URI resolution (the renderer emits the reader-backed image).
-    const onchainImage = !!flags['onchain-image'];
-    const onChainUri = !!flags['onchain-uri'] || onchainImage;
-    // On-chain traits when explicitly asked, or implied by --onchain-uri (the renderer can only
-    // emit on-chain fields, so off-chain-only traits would be invisible there). Else off-chain.
-    const traitsOnchain = traits.length > 0 && (!!flags['traits-onchain'] || onChainUri);
     // A fully on-chain token self-resolves via the renderer; the stored off-chain pointer is
     // never read while a renderer is set. So bake a real URL only if one was explicitly given —
     // otherwise leave it EMPTY rather than baking a misleading localhost into the contract.
     const hasPublicUrl = !!(flags['public-base-url'] || process.env.ABX_PUBLIC_BASE_URL);
+    const onchainImage = !!flags['onchain-image'];
+    // `abx demo` defaults to FULLY ON-CHAIN. Its default art is a generative SVG, which the renderer
+    // can inline — so the token self-resolves and, crucially, NO localhost gets baked into the
+    // contract as the tokenURI base. The old default shipped a first-ever token that resolved for
+    // nobody but its author (broken on every marketplace, dead the moment `abx serve` stops) and
+    // taught that as the normal shape of an NFT. It also undercut the demo's own claim: with the art
+    // on-chain, "rebuilt from the chain alone" now covers the IMAGE, not just the metadata.
+    //
+    // Opting back into off-chain custody is anything that says "I have somewhere to host": a real base
+    // URL, an explicit --backend, or a RASTER --image. An SVG --image still goes on-chain — inlining is
+    // exactly what the renderer supports (v1 is SVG-only), so there's no reason to send someone's own
+    // vector art down the localhost path. Raster stays off-chain because forcing it on-chain would
+    // silently inline a placeholder instead of their image.
+    const demoImageInlineable = !flags.image || contentTypeFromPath(flags.image) === 'image/svg+xml';
+    const demoDefaultsOnChain = serveAfter && demoImageInlineable && !flags.backend && !hasPublicUrl;
+    const onChainUri = !!flags['onchain-uri'] || onchainImage || demoDefaultsOnChain;
+    // On-chain traits when explicitly asked, or implied by --onchain-uri (the renderer can only
+    // emit on-chain fields, so off-chain-only traits would be invisible there). Else off-chain.
+    const traitsOnchain = traits.length > 0 && (!!flags['traits-onchain'] || onChainUri);
     let renderer = zeroAddress;
     if (onChainUri) {
-        step('On-chain renderer');
+        step(serveAfter ? 'What will answer when someone asks about your token' : 'On-chain renderer');
         if (dryRun) {
             renderer = rendererAddress(flags.renderer) ?? zeroAddress;
             info(renderer === zeroAddress ? 'would deploy the canonical renderer first' : `would use renderer ${renderer}`);
@@ -1075,8 +1101,28 @@ async function cmdDeploy(flags, serveAfter) {
         else {
             renderer = await ensureRenderer(flags.renderer);
         }
+        // A first-timer has no idea what a "renderer" is, and the word suggests something that draws
+        // pictures. What it actually does is assemble the JSON a marketplace asks for, on-chain, out of
+        // the fields your contract holds — worth one plain sentence, since it's why no server is needed.
+        if (serveAfter) {
+            info(dim('a marketplace asks your contract a question; this shared contract composes the answer'));
+            info(dim('already deployed, used by every ABX token, owned by no one — you are not paying to set it up'));
+        }
+    }
+    step(serveAfter ? `Mint it · one transaction on ${CHAIN}` : `Deploy a ${DIMENSIONS[dimension].label} (--type ${dimension}) to ${CHAIN}`);
+    // What the chain ends up holding is the single most useful thing to understand about an ABX token,
+    // and it's invisible unless someone says it out loud. Two honest versions, because the answer is
+    // genuinely different per lane. Demo only — `deploy` prints the same facts per-field.
+    if (serveAfter && onChainUri) {
+        console.log(`    Your art goes ${bold('INTO')} the contract. Not a link to it — the image itself.`);
+        console.log(`    ${g('✦')} the chain will hold   ${dim('your art · your name on it · your royalty · you as owner')}`);
+        console.log(`    ${g('✦')} you will need         ${dim('nothing else. no server, no IPFS pin, no monthly bill to forget')}`);
+    }
+    else if (serveAfter) {
+        console.log(`    ${g('✦')} the chain will hold   ${dim('your name · your royalty · you as owner · a fingerprint of the art')}`);
+        console.log(`    ${g('✦')} this computer holds   ${dim('the image bytes themselves')}`);
+        info(dim('the chain proves the bytes are unaltered; it does not store them (that fingerprint is a keccak256 hash)'));
     }
-    step(`Deploy a ${DIMENSIONS[dimension].label} (--type ${dimension}) to ${CHAIN}`);
     // Off-chain custody (no renderer) bakes the resolver URL straight into the on-chain
     // tokenURI/contractURI at deploy. A localhost / loopback URL there resolves for NO ONE —
     // not marketplaces, not wallets, not even your own browser unless `abx serve` is running —
@@ -1103,7 +1149,14 @@ async function cmdDeploy(flags, serveAfter) {
             }
         }
     }
-    if (onChainUri) {
+    if (onChainUri && serveAfter) {
+        // The demo's version of the same fact, in words a first-timer can act on. Naming what we are
+        // NOT doing matters here: a localhost URL written into a contract is the single most common way
+        // a first NFT ends up permanently broken, and the demo used to model exactly that.
+        info(dim('nothing points at this computer — no http://localhost anywhere in your contract.'));
+        info(dim('anyone can read your token from the chain, forever, with you offline.'));
+    }
+    else if (onChainUri) {
         info('tokenURI/contractURI resolve ON-CHAIN via the renderer — no resolver, no server, no localhost.');
         if (!hasPublicUrl)
             info('off-chain fallback pointer left empty (the renderer is authoritative); set --public-base-url to bake one anyway.');
@@ -1280,7 +1333,9 @@ async function cmdDeploy(flags, serveAfter) {
         // wallet lane + on-chain staging: ONE sign session signs every chunk write AND the deploy.
         // The connecting wallet pays for (and is the deployer of) all of it — staging can't precede
         // the connect here, so it happens inside the session, then the deploy bakes in the manifest.
-        info(`a wallet will become the owner; URIs point at ${baseUrl}`);
+        // --onchain-image implies on-chain resolution, so NOTHING points at baseUrl — saying it did was
+        // a flat contradiction of the line above it (and reintroduced the localhost the lane exists to avoid).
+        info('a wallet will become the owner; the token resolves from chain — no URI base is baked in.');
         const plan = computeContentPlan(readFileSync(resolvePath(flags.image)), parseCompress(flags.compress)).plan;
         const stagingTxs = plan.mode === 'single' ? 1 : plan.txCount;
         const session = await openWalletSession({
@@ -1345,8 +1400,12 @@ async function cmdDeploy(flags, serveAfter) {
         info(`tx ${EXPLORER}/tx/${r.txHash}  (block ${blockNumber})`);
     }
     else {
-        // wallet lane (off-chain custody) or cold lane: a single deploy tx, no staging sequence.
-        info(`a wallet will become the owner; URIs point at ${baseUrl}`);
+        // wallet lane (off-chain custody OR on-chain URI) or cold lane: a single deploy tx, no staging.
+        // Only claim a URI base when one is actually written — on the on-chain lane this line used to
+        // announce `http://localhost:8787` two lines after promising no localhost anywhere.
+        info(onChainUri
+            ? 'a wallet will become the owner; the token resolves from chain — no URI base is baked in.'
+            : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeployOneOfOne({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
@@ -1359,7 +1418,7 @@ async function cmdDeploy(flags, serveAfter) {
         blockNumber = result.blockNumber;
         ok(`deployed ${clone}`);
     }
-    step('Index it — replay the event spine from chain');
+    step(serveAfter ? 'What the chain knows now' : 'Index it — replay the event spine from chain');
     const indexer = new SelfHostIndexer();
     // Off-chain traits ride in the registration (on-chain ones are already in the contract fields).
     const offChainTraits = !traitsOnchain && traits.length ? JSON.stringify(traits) : undefined;
@@ -1374,10 +1433,20 @@ async function cmdDeploy(flags, serveAfter) {
         attributes: offChainTraits,
     };
     indexer.register(baseReg);
-    const { state, elapsedMs } = await indexer.reindex(clone);
-    ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — no provider involved`);
-    info(`name "${state.name}" · owner ${state.owner} · canonical: ${state.isCanonical ? 'yes (factory-verified)' : 'unverified'}`);
-    info(`extensions: ${state.extensions.map((e) => e.name).join(', ') || 'none'}`);
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, clone);
+    if (serveAfter) {
+        if (state.eventCount > 0)
+            ok(`read ${bold(String(state.eventCount))} events straight off ${CHAIN} in ${elapsedMs}ms — no API key, no company's server`);
+        info(`it says: "${state.name}" · owned by ${state.owner} · ${state.isCanonical ? `${g('verified real')} ${dim('(that factory vouched for it)')}` : `${c.orange}unverified${c.reset}`}`);
+        info(dim(`optional features switched on: ${state.extensions.map((e) => e.name.replace(/^abx\.extension\./, '')).join(' · ') || 'none'}`));
+        walkthroughSpine(state);
+    }
+    else {
+        if (state.eventCount > 0)
+            ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — no provider involved`);
+        info(`name "${state.name}" · owner ${state.owner} · canonical: ${state.isCanonical ? 'yes (factory-verified)' : 'unverified'}`);
+        info(`extensions: ${state.extensions.map((e) => e.name).join(', ') || 'none'}`);
+    }
     // For off-chain custody (image committed as keccak256), resolve the durable locator (ipfs://…)
     // from this machine's content index and store it on the registration — so the LOCAL resolver
     // points `image` at IPFS, and `abx add --remote` can ship it to a hosted one (the localhost-image fix).
@@ -1426,8 +1495,21 @@ async function cmdDeploy(flags, serveAfter) {
         }
         return;
     }
-    step('Serve the token API + dashboard');
+    // The demo's teaching sections — see the walkthrough helpers. `deploy` skips them: someone
+    // shipping real work doesn't need their projection deleted to make a point.
+    if (serveAfter)
+        await walkthroughRebuild(indexer, clone, state);
+    // Start the server BEFORE the read-back step (which fetches the served metadata over HTTP), but
+    // print the serve banner after it — otherwise the "Serve" step header lands with nothing under it
+    // while the read-back prints below, which reads like the step failed.
     const { url } = await startTokenApiServer({ indexer, port, baseUrl, storage: resolveBackend(storageOptions()) });
+    if (serveAfter)
+        await walkthroughReadBack(state, url, onChainUri);
+    // On the on-chain lane this server is a convenience, not infrastructure — say so, or standing one
+    // up as the finale re-teaches the dependency the whole run just disproved.
+    step(onChainUri ? 'Go look at it' : 'Serve the token API + dashboard');
+    if (onChainUri)
+        info(dim('a local viewer, purely for your eyes — your token does not need it. Ctrl-C whenever; the token stays up.'));
     printServing(url, clone);
     keepAlive();
 }
@@ -1869,8 +1951,11 @@ async function cmdDeploySeries(flags) {
     }
     else {
         // wallet lane (off-chain / inline) or cold lane: a single deploy tx, no staging sequence —
-        // tokenFields is already built.
-        info(`a wallet will become the owner; URIs point at ${baseUrl}`);
+        // tokenFields is already built. Same correction as the 1/1 lane: only claim a URI base when one
+        // is actually written, or an --onchain-uri Series announces a localhost it never bakes.
+        info(onChainUri
+            ? 'a wallet will become the owner; tokens resolve from chain — no URI base is baked in.'
+            : `a wallet will become the owner; URIs point at ${baseUrl}`);
         const result = await signTx(async (signer) => {
             const { clone: predicted, params, salt } = await buildForDeployer(signer);
             return prepareDeploySeries({ factory, params, salt, chainId: resolveChain(CHAIN).id, clone: predicted });
@@ -1898,8 +1983,9 @@ async function cmdDeploySeries(flags) {
         tokenAttributes: offChainTokenTraits,
     };
     indexer.register(baseReg);
-    const { state, elapsedMs } = await indexer.reindex(clone);
-    ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — ${state.tokens.length} token(s), max ${state.maxInvocations}`);
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, clone);
+    if (state.eventCount > 0)
+        ok(`reconstructed ${state.eventCount} events in ${elapsedMs}ms — ${state.tokens.length} token(s), max ${state.maxInvocations}`);
     info(`extensions: ${state.extensions.map((e) => e.name).join(', ') || 'none'}`);
     // Off-chain custody: bridge each token's keccak → durable locator so the resolver (local and,
     // via `abx add --remote`, a hosted one) points images off this node.
@@ -2163,7 +2249,11 @@ async function cmdAdd(address, flags) {
             info(`scanning blocks ${start}${dim(' → ')}${head} ${dim(`(~${span} blocks)`)} — on a range-capped RPC (see ${g('abx doctor')}) this can take a few minutes with no per-block output; leave it running.`);
     }
     catch { /* advisory only — the real scan still runs */ }
-    const { state, elapsedMs } = await indexer.reindex(address);
+    // Don't accept a zero here either: `deploy-code` finishes through this command, so this IS the
+    // post-deploy index for a code project — and a real ABX clone always emits a spine (its extension
+    // registrations at minimum), so 0 events means the RPC hasn't served the logs yet, not that the
+    // project is empty. See reindexAfterDeploy.
+    const { state, elapsedMs } = await reindexAfterDeploy(indexer, address);
     // Resolve durable locators for off-chain-by-hash content from this machine's index.
     const locators = await collectContentLocators(state, resolveBackend(storageOptions(storageOverrides(flags))));
     if (Object.keys(locators).length) {
@@ -2180,7 +2270,14 @@ async function cmdAdd(address, flags) {
             contentLocators: JSON.stringify(locators),
         });
     }
-    ok(`registered + indexed ${state.name ?? address} LOCALLY (this machine): ${state.eventCount} events in ${elapsedMs}ms`);
+    // A ✓ on 0 events is the lie that produced an empty dashboard; reindexAfterDeploy has already
+    // explained the failure and named the recovery command, so don't stamp it as success too.
+    if (state.eventCount > 0) {
+        ok(`registered + indexed ${state.name ?? address} LOCALLY (this machine): ${state.eventCount} events in ${elapsedMs}ms`);
+    }
+    else {
+        warn(`registered ${state.name ?? address}, but with NO reconstructed state — it will serve empty until the index succeeds.`);
+    }
     info(`serve it from here with ${bold('abx serve')} — or push it to a hosted resolver with ${bold('abx add ' + address + ' --remote')}`);
 }
 /** The code-project trust anchor: use the canonical factory, else deploy one (a sandbox /
@@ -2247,6 +2344,199 @@ 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.
  */
+// ── the demo walkthrough: teaching sections, demo-only ────────────────────────
+//
+// `abx demo` is a TEACHING command, not a shortcut — the docs point a first-time reader here to
+// learn what the toolkit does on their behalf. Its old form asserted the interesting claims
+// ("reconstructed 9 events — no provider involved") without ever showing them, which made it a
+// smoke test wearing a demo's clothes. These sections demonstrate instead: print the spine the
+// chain now holds, throw the local projection away and rebuild it, then read the token back the way
+// a marketplace would. They run only for `demo` (never `deploy`), and never pause — an agent or CI
+// run has to behave identically.
+/**
+ * The deterministic part of a projection: everything that is a pure function of the chain.
+ * Deliberately EXCLUDES `reconstructedAt`, `rpcUrl` and `toBlock` — a timestamp, the endpoint that
+ * happened to answer, and the head at scan time all legitimately differ between two replays, so
+ * folding them in would make the rebuild proof fail for reasons that aren't about correctness.
+ */
+function projectionFingerprint(s) {
+    const canonical = {
+        address: s.address.toLowerCase(),
+        name: s.name,
+        symbol: s.symbol,
+        owner: s.owner?.toLowerCase() ?? null,
+        isCanonical: s.isCanonical,
+        deployBlock: s.deployBlock,
+        eventCount: s.eventCount,
+        royalty: s.royalty ? { bps: s.royalty.bps, receiver: s.royalty.receiver.toLowerCase() } : null,
+        extensions: s.extensions.map((e) => e.name).sort(),
+        collectionFields: s.collectionFields.map((f) => `${f.field}=${f.value}`).sort(),
+        tokens: s.tokens.map((t) => ({ id: t.tokenId, minted: t.minted, owner: t.owner?.toLowerCase() ?? null })),
+        events: s.events.map((e) => `${e.blockNumber}:${e.logIndex}:${e.name}`),
+    };
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
+/**
+ * Print the reconstructed spine — the point being that this list IS the database. Rendered inside
+ * the index step (no header of its own: "Index it — replay the event spine" immediately followed by
+ * a separate "The event spine" step read as a stutter).
+ */
+function walkthroughSpine(state) {
+    if (state.events.length === 0) {
+        warn('no events to show (the index came back empty — see the recovery hint above).');
+        return;
+    }
+    const width = Math.max(...state.events.map((e) => e.name.length));
+    state.events.forEach((e, i) => {
+        // ERC vs ABX register: standard ERC-721 events a marketplace already understands, versus ABX's
+        // own. Worth surfacing — it's why an ABX token indexes fine on tools that know nothing about ABX.
+        const reg = e.register === 2 ? p('ABX') : dim('ERC');
+        console.log(`    ${dim(`#${String(i + 1).padStart(2)}`)} ${reg} ${e.name.padEnd(width)}  ${dim(e.what)}`);
+    });
+    console.log(`    ${dim('→')} those ${bold(String(state.events.length))} lines ${bold('are')} the database. ` +
+        dim('There is no other copy that counts — not ours, not anyone\'s.'));
+    console.log(`      ${p('ABX')} ${dim('= ABX\'s own events')}   ${dim('ERC')} ${dim('= bog-standard ERC-721/7572, which is why wallets and marketplaces that have never heard of ABX still show your token.')}`);
+}
+/**
+ * [4] The claim, demonstrated: delete the local projection and rebuild it from the chain.
+ *
+ * This is the one step that can't be faked by good output — it drops the projection for real
+ * (registration kept), confirms it's gone, replays from the deploy block, and compares a
+ * fingerprint of everything chain-derived. If ABX's premise is wrong, this step fails loudly.
+ */
+async function walkthroughRebuild(indexer, address, before) {
+    step('The moment of truth · delete it all');
+    const fpBefore = projectionFingerprint(before);
+    indexer.dropProjection(address);
+    const gone = indexer.getProject(address) === null;
+    console.log(`    ${dim('wiping this computer\'s copy …')}          ${gone ? g('gone. nothing left locally.') : `${c.orange}⚠ still present${c.reset}`}`);
+    const { state: after, elapsedMs } = await indexer.reindex(address, { full: true });
+    const fpAfter = projectionFingerprint(after);
+    console.log(`    ${dim(`asking ${CHAIN} to tell us everything again …`)}   ` +
+        `${g(`${after.eventCount} events, ${elapsedMs}ms`)}`);
+    if (fpBefore === fpAfter) {
+        ok(bold('byte-for-byte identical.'));
+        info('Your token just survived losing every local file. No backup, no API key, no company —');
+        info(`the chain remembered. ${dim('That is the whole point of ABX.')}`);
+        info(dim(`checked by hashing every chain-derived field, not by eyeballing it: sha256 ${fpAfter.slice(0, 12)}…`));
+    }
+    else {
+        warn('the rebuilt state does NOT match what we just had — that is a real bug, please report it.');
+        info(`before ${fpBefore.slice(0, 16)}… · after ${fpAfter.slice(0, 16)}…`);
+    }
+}
+/**
+ * [5] Read the token back the way a marketplace would.
+ *
+ * Which is genuinely a different act per lane, so it reads from the real source in each case rather
+ * than always going through the local server:
+ *   • fully on-chain → call `tokenURI(0)` on the contract. That IS what a marketplace does, and on
+ *     this lane the whole answer (art included) comes back from the chain with nothing else running.
+ *   • off-chain custody → fetch the resolver, because that's what the baked URI points at.
+ * Reading the on-chain lane over HTTP would have quietly implied the local server was load-bearing
+ * when it isn't — the opposite of the lesson.
+ */
+async function walkthroughReadBack(state, baseUrl, onChainUri) {
+    step('Read it back the way a marketplace would');
+    const token = state.tokens[0];
+    if (!token?.minted) {
+        info('no minted token to read yet.');
+        return;
+    }
+    if (onChainUri) {
+        info(dim(`calling tokenURI(0) on your contract — the same call OpenSea makes …`));
+        try {
+            const uri = (await makePublicClient({ chainKey: CHAIN }).readContract({
+                address: state.address,
+                abi: oneOfOneImageAbi,
+                functionName: 'tokenURI',
+                args: [0n],
+            }));
+            const json = decodeOnChainJson(uri);
+            if (json) {
+                const parsed = JSON.parse(json);
+                const img = typeof parsed.image === 'string' ? parsed.image : '';
+                console.log(`    ${g('✓')} came back with: ${bold(String(parsed.name ?? '(no name)'))}`);
+                console.log(`      ${dim(`image: ${img.slice(0, 48)}${img.length > 48 ? '…' : ''}`)}`);
+                // The punchline of the whole lane: a data: URI means the art travelled IN the answer.
+                if (img.startsWith('data:'))
+                    info(`${g('the art itself came back in that answer')} ${dim('— no link to follow, nothing to go missing')}`);
+            }
+            else {
+                console.log(`    ${dim(uri.slice(0, 160))}${uri.length > 160 ? dim('…') : ''}`);
+            }
+            info(dim('nothing was running to answer that. no server of ours, no server of yours.'));
+        }
+        catch (e) {
+            info(dim(`could not read tokenURI from the chain: ${e.message}`));
+        }
+        console.log(`    ${dim('read it yourself any time:')} ${bold(`abx tokenuri ${state.address}`)}`);
+        return;
+    }
+    info(`tokenURI(0) ${dim('on chain →')} ${token.tokenURI ?? dim('(none)')}`);
+    // Off-chain custody: the CHAIN holds a keccak256 commitment to the image and a URI base; this NODE
+    // holds the bytes. That split is the thing worth understanding, so name it rather than implying the
+    // JSON came from the chain.
+    info(dim('the chain stored a URI base + a keccak256 commitment; this node serves the bytes.'));
+    try {
+        const res = await fetch(`${baseUrl}/t/${resolveChain(CHAIN).id}/${state.address}/0`);
+        const json = (await res.json());
+        const shown = { name: json.name, image: json.image };
+        console.log(`    ${dim(JSON.stringify(shown))}`);
+        if (Array.isArray(json.abx_provenance)) {
+            info(dim(`every field is tagged with where it came from (abx_provenance: ${json.abx_provenance.length} entries)`));
+        }
+    }
+    catch (e) {
+        info(dim(`could not read the served metadata: ${e.message}`));
+    }
+    console.log(`    ${dim('prove the bytes match the chain:')} ${bold(`abx verify ${state.address}`)}`);
+}
+/** Is a TCP port already bound on localhost? Used to preflight a serve BEFORE spending a tx. */
+async function portInUse(port) {
+    const { createServer } = await import('node:net');
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once('error', (e) => resolve(e.code === 'EADDRINUSE'));
+        probe.once('listening', () => probe.close(() => resolve(false)));
+        probe.listen(port);
+    });
+}
+/**
+ * Index a project we *just* deployed — and don't believe a zero.
+ *
+ * `eth_getLogs` is read-after-write inconsistent on load-balanced RPCs: `waitForTransactionReceipt`
+ * resolves against a node that has the block, then the log query lands on one that doesn't yet, and
+ * returns an empty set for a block we KNOW contains our deploy. The old code took that single read at
+ * face value, printed `✓ reconstructed 0 events`, stored the empty projection, and served an empty
+ * dashboard — a first-run that looks like the toolkit simply doesn't work. It reproduced 100% of the
+ * time on `https://sepolia.base.org`, which is the DEFAULT endpoint when there's no `.env`, i.e. the
+ * documented first run was the broken path. The same block returned all 9 logs seconds later.
+ *
+ * We have the one thing that makes this checkable: we just minted, so the spine cannot be empty.
+ * So verify instead of trusting — re-scan with backoff until events appear, and if they never do,
+ * say so as a FAILURE with the recovery command rather than dressing a zero up as a ✓.
+ */
+async function reindexAfterDeploy(indexer, address, opts = {}) {
+    const attempts = opts.attempts ?? 6;
+    const delayMs = opts.delayMs ?? 1500;
+    let last = await indexer.reindex(address);
+    for (let i = 1; i < attempts && last.state.eventCount === 0; i++) {
+        if (i === 1) {
+            info(dim("no events yet — the RPC hasn't served the logs for that block; re-scanning…"));
+        }
+        await new Promise((r) => setTimeout(r, delayMs));
+        // `full: true` — the stored projection has 0 events, so there is no valid checkpoint to
+        // resume from; a full replay from the deploy block is the only correct re-scan.
+        last = await indexer.reindex(address, { full: true });
+    }
+    if (last.state.eventCount === 0) {
+        warn(`the RPC still reports no logs for this project after ${attempts} tries — the deploy DID succeed ` +
+            `(it's on chain), but this node can't reconstruct it yet.`);
+        console.log(`    ${dim('recover with')} ${bold(`abx index ${address} --full`)} ${dim('in a minute, or point ABX_RPC_URLS at a better endpoint (`abx doctor` ranks them).')}`);
+    }
+    return last;
+}
 /**
  * `abx preview` — serve the program on localhost, live, for as long as the work is being made.
  *
@@ -4258,6 +4548,44 @@ async function cmdMigrate(address, flags) {
     info('keep the source running until DNS / base-URI propagates (source-only images were already re-pinned above, unless a warning said otherwise).');
 }
 // ── doctor ────────────────────────────────────────────────────────────────--
+/**
+ * Doctor's "want me to fix that?" for a missing or stale skill. Three lanes, deliberately:
+ *   `--fix`      install without asking (CI, scripts, an agent running doctor for someone)
+ *   interactive  name the exact directories, then ask — Enter accepts, since doctor's whole job is
+ *                getting setup right and this is the one check whose fix is a local file copy
+ *   non-TTY      change NOTHING and print how to do it; a diagnostic must never mutate a
+ *                scripted environment just because nobody was there to say no
+ * Honors `--global` / `--agent` so the fix can target the same place an explicit install would.
+ */
+async function offerSkillInstall(flags, stale, indent) {
+    const opts = { global: flags.global !== undefined, agent: flags.agent };
+    const src = resolveBundledSkill();
+    if (!src)
+        return; // no bundled skill to install (dev checkout oddity) — the hint above still stands
+    const verb = stale ? 'resync' : 'install';
+    const dests = defaultSkillDests(opts);
+    if (flags.fix === undefined) {
+        if (!process.stdin.isTTY) {
+            console.log(`${indent}${dim(`non-interactive — run \`abx doctor --fix\` (or \`abx skill install\`) to ${verb} it.`)}`);
+            return;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+            // EOF (Ctrl-D) closes the interface WITHOUT firing the question callback — awaiting only the
+            // callback would hang doctor forever. Treat a closed stream as a decline: the safe direction is
+            // always "change nothing", never "write files because nobody answered".
+            rl.once('close', () => resolve('n'));
+            rl.question(`${indent}${verb} the abx skill into ${bold(dests)} now? [Y/n] `, resolve);
+        });
+        rl.close();
+        if (declinesSkillInstall(answer)) {
+            console.log(`${indent}${dim(`skipped — \`abx skill install\` when you want it.`)}`);
+            return;
+        }
+    }
+    console.log('');
+    installSkillToDefaults(src, opts);
+}
 async function cmdDoctor(flags) {
     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
@@ -4274,16 +4602,28 @@ async function cmdDoctor(flags) {
     const cliVersion = readCliVersion();
     const skillVersions = installedSkillVersions();
     const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
-    if (skillVersions.length === 0) {
+    const skillMissing = skillVersions.length === 0;
+    const skillStale = !skillMissing && staleSkills.length > 0;
+    if (skillMissing) {
         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) {
+    else if (skillStale) {
         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})`);
     }
+    // Offer to fix it here rather than only naming the command. `npm i -g` + `abx skill install` was a
+    // two-step install flow where the second step is easy to skip and invisible when skipped (an agent
+    // that never learned abx just... doesn't use it). Doctor is already the documented first run, so
+    // this collapses the flow without an npm `postinstall` hook — which could not work anyway: npm runs
+    // lifecycle scripts with cwd set to the installed package dir (so the skill would land inside
+    // node_modules), pnpm gates install scripts by default, and writing to a user's ~/.claude on
+    // install is the kind of side effect that belongs to the user, not to us.
+    if (skillMissing || skillStale) {
+        await offerSkillInstall(flags, skillStale, CONT);
+    }
     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.
@@ -4376,7 +4716,13 @@ function printServing(url, address) {
         console.log(`    ${dim('image      ')}${url}/t/${cid}/${address}/0/image`);
         console.log(`    ${dim('state API  ')}${url}/api/project/${address}`);
     }
-    console.log(`\n  ${dim('Open the dashboard, then hit “Re-index from chain” to watch state rebuild live.')}`);
+    // The dashboard is READ-ONLY: re-index/verify are admin actions that 404 unless the node has an
+    // ABX_RESOLVER_ADMIN_TOKEN, so there is no button to press. This line used to say "hit Re-index
+    // from chain", which sent every first-run user hunting for a control that isn't there.
+    console.log(`\n  ${dim('The dashboard shows the event spine it replayed — that table IS the reconstruction.')}`);
+    if (address) {
+        console.log(`  ${dim('Rebuild it yourself (read-only, safe):')} ${bold(`abx index ${address} --full`)} ${dim('— replays from the deploy block and must land on identical state.')}`);
+    }
     console.log(`  ${dim('Ctrl-C to stop.')}\n`);
 }
 // ── deploy-resolver: scaffold a hosted resolver for a provider the operator owns ──────────
@@ -4986,8 +5332,12 @@ const COMMAND_HELP = {
   ${bold('abx set-max-invocations')} <address> --max <N> ${dim('— LOWER the supply cap (Series). Sends a tx.')}
     --max <N>             the new cap — MONOTONIC: can only DECREASE, and never below what's already minted (else it reverts)`,
     doctor: `
-  ${bold('abx doctor')} ${dim('— preflight readiness: signing key/wallet, RPC health, canonical factory, storage. Read-only.')}
+  ${bold('abx doctor')} ${dim('— preflight readiness: agent skill, signing key/wallet, RPC health, canonical factory, storage.')}
     --for 0x..            also report that address's balance (fund before signing)
+    ${g('--fix')}                 ${dim('install/resync the agent skill without asking (the one thing doctor can repair)')}
+    ${g('--global')} · ${g('--agent')} <a>  ${dim('where --fix installs the skill (mirrors `abx skill install`)')}
+    ${dim('Read-only apart from --fix. Interactively it OFFERS to install a missing/stale skill; a non-TTY')}
+    ${dim('run changes nothing and just prints the command, so scripts and CI are never mutated.')}
     ${dim('a missing signing key is NOT fatal — the wallet lane (`--sign`) needs no key in `.env`.')}`,
     status: `
   ${bold('abx status')} ${dim('— list the projects this node has indexed, plus node info. Read-only.')}`,
@@ -5265,6 +5615,31 @@ function installSkillTo(src, dest) {
     rmSync(dest, { recursive: true, force: true });
     cpSync(src, dest, { recursive: true });
 }
+/**
+ * Install the bundled skill into the default per-agent parents (or `~` with `global`), reporting
+ * each destination. Shared by `abx skill install` and `abx doctor`'s offer to fix a missing/stale
+ * skill — one implementation, so the two can't drift on where the skill lands or what it prints.
+ */
+function installSkillToDefaults(src, opts = {}) {
+    const version = readSkillVersion(joinPath(src, 'SKILL.md')) ?? readCliVersion();
+    const base = opts.global ? homedir() : process.cwd();
+    const parents = resolveInstallParents(opts.agent);
+    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 label = SKILL_PARENT_LABELS[parent];
+        console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${label ? dim('  → ' + label) : ''}`);
+    }
+    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.`);
+    return version;
+}
+/** The default skill destinations, as a display string — what doctor's prompt has to name up front. */
+function defaultSkillDests(opts = {}) {
+    const prefix = opts.global ? '~/' : './';
+    return resolveInstallParents(opts.agent).map((p) => `${prefix}${p}`).join(' and ');
+}
 async function cmdSkill(rest, flags) {
     const sub = rest[0] ?? 'install';
     const src = resolveBundledSkill();
@@ -5287,17 +5662,7 @@ async function cmdSkill(rest, flags) {
             info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
             return;
         }
-        const base = flags.global !== undefined ? homedir() : process.cwd();
-        const parents = resolveInstallParents(flags.agent);
-        ok(`installed the abx skill v${version}${flags.global !== undefined ? ' (global, ~)' : ''}:`);
-        for (const parent of parents) {
-            const dest = joinPath(base, parent, SKILL_DIR_NAME);
-            installSkillTo(src, dest);
-            const label = SKILL_PARENT_LABELS[parent];
-            console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${label ? dim('  → ' + label) : ''}`);
-        }
-        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.`);
+        installSkillToDefaults(src, { global: flags.global !== undefined, agent: flags.agent });
         return;
     }
     throw new Error('usage: abx skill <install|path> [--agent claude|cursor|codex|gemini|copilot] [--global] [--target <dir>]');