@artblocks/abx-cli 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/main.js

@@ -14,10 +14,12 @@
  *   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)
- *   abx index [<address>]    re-index a project from chain (replay; --remote to nudge a hosted resolver)
+ *   abx add <address>        register + index a project (--remote <name|url>: on a remote resolver, not this machine)
+ *   abx remote [<name|url>]  inspect a remote service (descriptor · chains · managed rendering · your projects there)
+ *   abx index [<address>]    re-index a project from chain (replay; --remote to nudge a remote resolver)
  *   abx verify <address>     re-hash served bytes vs the on-chain commitment (no server)
  *   abx configure-param <addr> <id> <key> <value>  set a governed PostParam (typed encode; any lane)
  *   abx set-param-hooks <addr>  wire/clear a SeriesCode's configure/augment/transfer param hooks
@@ -34,14 +36,15 @@
  *   abx storage backup-key   copy the managed Turbo/Arweave key (holds credits) to a safe path
  *   abx status               list indexed projects + node info
  *   abx doctor               check environment (key, RPC, balance, factory, storage)
- *   abx skill install        install the abx agent skill into your agent (.claude/skills; --global)
+ *   abx skill install        install the version-locked abx agent skill into your agent(s)
+ *                            (default: Claude Code + the neutral .agents/skills; --agent/--global)
  *
  * Every write picks a signing lane: default hot (env key signs), `--sign` (a human
  * approves in their own wallet via a one-shot localhost page), `--unsigned` (print
  * the tx for a multisig / offline signer). The agent picks the lane; the CLI signs.
  */
-import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
+import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+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';
@@ -54,9 +57,11 @@ import { DEP_RESOLUTION, deploySeedSource, deploySeriesCodeFactory, prepareCodeS
 import { checkRegistryDeps, dependencySetupCalls, parseDepFlag, resolveDepRegistryPointer } from './deps.js';
 import { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport } from './onchain-uri.js';
 import { parseFlags, unknownFlags } from './flags.js';
-import { checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, SKILL_VERSION_MARKER } from './update-check.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 { 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 —
@@ -66,22 +71,20 @@ 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, DEFAULT_CHAIN_KEY, normalizeAttributes, parseTraitPairs, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } 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, 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 { openWalletSession, signTx } from './signer.js';
-import { remoteAddProject, remoteRemoveProject } from './remote.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, 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 = {
-    11155111: 'https://sepolia.etherscan.io', // Sepolia
-    84532: 'https://sepolia.basescan.org', // Base Sepolia
-};
-const EXPLORER = EXPLORERS[resolveChain(CHAIN).id] ?? 'https://sepolia.etherscan.io';
+// 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
+// the same shape of bug that had the token-api dashboard sending every Base Sepolia link to Etherscan.
+const EXPLORER = explorerUrl(resolveChain(CHAIN).id);
 // Product dimensions — what you can launch. One concrete contract exists today
 // (the 1/1 image); this table is the seam future implementations slot into, so
 // `abx deploy --type <dimension>` is stable while the contracts grow under it.
@@ -133,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`);
         }
     }
@@ -151,7 +154,7 @@ async function main() {
         return;
     }
     // Notify-only "you're behind" nudge (cached, opt-out, stderr — see update-check.ts). Awaited so
-    // the notice lands before command output, but it hits the network at most once a day and never
+    // the notice lands before command output, but it hits the network at most once every 6h and never
     // throws, so it can't break or meaningfully slow a command. Skipped for the pure help path below.
     await maybeNotifyUpdate(flags);
     // SAFETY: --help / -h on ANY command is read-only — print usage, never execute.
@@ -165,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);
@@ -204,8 +208,9 @@ async function main() {
         case 'set-admin': return cmdSetAdmin(rest[0], flags);
         case 'forget': return cmdForget(rest[0], flags);
         case 'migrate': return cmdMigrate(rest[0], flags);
+        case 'remote': return cmdRemote(rest[0], flags);
         case 'storage': return cmdStorage(rest);
-        case 'status': return cmdStatus();
+        case 'status': return cmdStatus(rest[0], flags);
         case 'state': return cmdState(rest[0], flags);
         case 'doctor': return cmdDoctor(flags);
         case 'skill': return cmdSkill(rest, flags);
@@ -220,6 +225,65 @@ async function main() {
             process.exit(1);
     }
 }
+/**
+ * A `--dry-run` computes the deterministic deploy address, which is a pure function of
+ * (factory, salt, deployer) — so it needs a deployer even though it signs nothing. Resolve it the
+ * same way the preview will (`--for`, else an env key) and fail EARLY with the fix if neither
+ * exists, rather than after the preview has printed several steps of work.
+ */
+/**
+ * A dry run only checks whether a factory address is CONFIGURED, not whether it has code on this
+ * chain — and the manifest always has an address, so a chain where the trust anchor isn't deployed
+ * (a private/local chain, or a wrong-network RPC) sailed past this and died inside
+ * `predictDeterministicAddress` with a raw `returned no data ("0x")` and a list of ABI hypotheses.
+ * The real deploy and `abx predict` both explain that case; a preview of the same deploy must too.
+ * Returns false when the caller should stop (message already printed).
+ */
+async function previewFactoryLive(client, factory, label) {
+    const code = await client.getCode({ address: factory }).catch(() => undefined);
+    if (code && code !== '0x')
+        return true;
+    warn(`the configured ${label} ${factory} has no code on '${CHAIN}' (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}).`);
+    info('so this preview can\'t compute the deterministic address. Either point at a chain where the trust anchor is deployed');
+    info(`(${bold('ABX_CHAIN=' + DEFAULT_CHAIN_KEY)} is the default and has one), or deploy your own on this chain with ${bold('--bootstrap-factory')}`);
+    info(dim('(a private anchor — platforms won\'t recognize its clones, so it\'s for private/sandbox chains).'));
+    console.log(`\n  ${g('dry run')} ${dim('— nothing sent.')}\n`);
+    return false;
+}
+/**
+ * Placeholder-identity guard, shared by ALL THREE deploy commands. `name`/`symbol` are written
+ * on-chain as the public collection identity and are effectively permanent, so a real deploy must
+ * never bake a tool default silently: warn in a preview, HARD-STOP a real send unless `--yes`.
+ *
+ * It was duplicated per command, and `deploy-series` simply never got a copy — its default
+ * "ABX Series"/"ABXS" went on-chain with at most a warning, while the skill promises the CLI
+ * refuses demo defaults. (deploy-code's copy even said "mirror deploy/deploy-series", which made
+ * the gap look closed.) One predicate now, like `loopbackBaseUrl()`, so a fourth command can't drift.
+ */
+function assertRealIdentity(flags, o) {
+    if (flags.name && flags.symbol)
+        return;
+    if (!flags.name)
+        warn(`no --name → default "${o.name}" would be the on-chain collection name`);
+    if (!flags.symbol)
+        warn(`no --symbol → default "${o.symbol}" would be the on-chain symbol`);
+    if (o.dryRun || flags.yes)
+        return; // a preview still runs; --yes is the explicit opt-in
+    throw new Error('refusing to write tool placeholders as your public on-chain identity — pass --name "Your Title" --symbol SYM ' +
+        '(or --yes to accept the defaults). On-chain identity is effectively permanent.');
+}
+function assertPreviewDeployer(flags) {
+    if (flags.for)
+        return;
+    try {
+        makeWalletClient({ chainKey: CHAIN });
+    }
+    catch {
+        throw new Error('dry run needs a deployer address to compute the deterministic deploy address — pass --for 0x.. ' +
+            '(a preview signs nothing, so no key is needed). For the REAL deploy with no key in .env, use the ' +
+            'wallet lane: --sign --for 0x.. (you approve in your own wallet).');
+    }
+}
 // When the user/agent opts in (--yes), lift the getLogs chunk cap so a large
 // reconstruction proceeds despite a range-limited RPC (otherwise it stops early with
 // guidance — see GetLogsScanTooLargeError + the skill's "Choosing an RPC" decision).
@@ -293,17 +357,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) {
@@ -455,7 +508,7 @@ function refuseMissingFactory(kind, envVar, reason) {
         `  To deploy your OWN trust anchor instead (private chains, sandboxes — platforms won't recognize its clones), ` +
         `re-run with --bootstrap-factory.`);
 }
-async function ensureFactory(override, allowBootstrap = false) {
+async function ensureFactory(override, allowBootstrap = false, quiet = false) {
     // Resolve the canonical factory from the shipped manifest (flag → env → manifest); on a chain
     // with no entry, deploy a fresh trust anchor and tell the operator how to reuse it.
     const known = factoryAddress(override);
@@ -465,7 +518,10 @@ async function ensureFactory(override, allowBootstrap = false) {
         const code = await publicClient.getCode({ address: known });
         if (code && code !== '0x') {
             if (await isCurrentFactory(publicClient, known)) {
-                info(`using canonical factory ${EXPLORER}/address/${known}`);
+                // `quiet` suppresses only this happy-path line (the demo resolves the factory without making a
+                // teaching moment of it). Bootstrap/mismatch messages below always print — those matter.
+                if (!quiet)
+                    info(`using canonical factory ${EXPLORER}/address/${known}`);
                 return known;
             }
             if (!allowBootstrap)
@@ -982,26 +1038,53 @@ 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')}`));
-    const lane = serveAfter ? 'send' : laneFromFlags(flags); // demo is always hot (one-shot)
+    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
+    // 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.');
+    }
+    // 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
+    // A keyless preview needs `--for` (the address is a pure function of factory+salt+deployer). Check
+    // it HERE, before the trust-anchor/content/plan steps print — hitting this after a wall of output
+    // reads as "it half-worked", and a first-timer previewing with no key in .env always hits it.
+    if (dryRun)
+        assertPreviewDeployer(flags);
     const publicClient = makePublicClient({ chainKey: CHAIN });
     // Verify the RPC really is CHAIN before any send (factory/renderer/staging/deploy). A dry run
     // sends nothing, but it DOES read the chain (predict address, resolve the factory/renderer), so
     // a wrong-network RPC must still be caught with the clear mismatch message rather than failing
     // opaquely inside predict; `allowUnreachable` keeps a genuinely offline dry-run previewable.
     await assertChainId(CHAIN, { allowUnreachable: dryRun });
-    // Identity guard: the demo placeholders ("ABX Self-Host Demo"/"ABXSH") are written on-chain as
-    // the public collection identity. Warn in preview; HARD-STOP a real deploy unless acknowledged.
-    if (!serveAfter && (!flags.name || !flags.symbol)) {
-        if (!flags.name)
-            warn(`no --name → default "${name}" would be the on-chain collection name`);
-        if (!flags.symbol)
-            warn(`no --symbol → default "${symbol}" would be the on-chain symbol`);
-        if (!dryRun && !flags.yes) {
-            throw new Error('refusing to write demo placeholders as your public on-chain identity — pass --name "Your Title" --symbol SYM (or --yes to accept the defaults).');
-        }
-    }
+    // `demo` is exempt: its whole job is a zero-argument first token.
+    if (!serveAfter)
+        assertRealIdentity(flags, { name, symbol, dryRun });
     // Funding preflight (real deploys): warn now if the signer is unfunded, not at the tx.
     if (!dryRun) {
         let signer = flags.for;
@@ -1014,7 +1097,13 @@ async function cmdDeploy(flags, serveAfter) {
         if (signer)
             await warnUnfunded(publicClient, signer);
     }
-    step('Trust anchor');
+    // `deploy` surfaces the trust anchor as a step; the demo does NOT. It briefly opened on "only this
+    // factory can make a token that IS an ABX token", which is simply false — anything that follows the
+    // protocol's event spine is an ABX token, and the factory is one way to get there, not the
+    // definition of the thing. Rather than restate it more carefully, the demo skips it: a first-timer
+    // does not need a provenance lecture before they have made anything.
+    if (!serveAfter)
+        step('Trust anchor');
     let factory;
     if (dryRun) {
         const existing = factoryAddress(flags.factory);
@@ -1024,10 +1113,12 @@ async function cmdDeploy(flags, serveAfter) {
             return;
         }
         factory = existing;
+        if (!(await previewFactoryLive(publicClient, factory, 'factory')))
+            return;
         info(`would reuse canonical factory ${factory}`);
     }
     else {
-        factory = await ensureFactory(flags.factory, !!flags['bootstrap-factory']);
+        factory = await ensureFactory(flags.factory, !!flags['bootstrap-factory'], serveAfter);
     }
     // --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
@@ -1035,18 +1126,32 @@ async function cmdDeploy(flags, serveAfter) {
     // --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}`);
@@ -1054,8 +1159,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 —
@@ -1082,7 +1207,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.');
@@ -1259,7 +1391,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({
@@ -1324,8 +1458,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 });
@@ -1338,7 +1476,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;
@@ -1353,10 +1491,23 @@ 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`);
+        // "verified real" overstated it in the same way the removed trust-anchor step did — factory
+        // provenance is a fact about how this contract was made, not a verdict on whether a token counts
+        // as ABX. Report the fact.
+        info(`it says: "${state.name}" · owned by ${state.owner} · ${state.isCanonical ? g('made by the canonical factory') : dim('not factory-made')}`);
+        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: ${canonicalLabel(state.isCanonical)}`);
+        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).
@@ -1405,8 +1556,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();
 }
@@ -1457,21 +1621,15 @@ async function cmdDeploySeries(flags) {
         throw new Error(`--count ${count} exceeds the ${files.length} media file(s) in ${dirPath}`);
     const slots = files.slice(0, count);
     const dryRun = !!flags['dry-run'];
+    if (dryRun)
+        assertPreviewDeployer(flags); // fail fast, before the preview does any work (see cmdDeploy)
+    assertRealIdentity(flags, { name, symbol, dryRun });
     const lane = laneFromFlags(flags);
     const publicClient = makePublicClient({ chainKey: CHAIN });
     // Catch a wrong-network RPC with the clear mismatch message even on dry-run (which still reads
     // the chain to predict the address); tolerate an unreachable RPC so an offline preview still works.
     await assertChainId(CHAIN, { allowUnreachable: dryRun });
-    // Identity guard (mirror cmdDeploy): never write demo placeholders as the public identity.
-    if (!flags.name || !flags.symbol) {
-        if (!flags.name)
-            warn(`no --name → default "${name}" would be the on-chain collection name`);
-        if (!flags.symbol)
-            warn(`no --symbol → default "${symbol}" would be the on-chain symbol`);
-        if (!dryRun && !flags.yes) {
-            throw new Error('refusing to write demo placeholders as your public on-chain identity — pass --name "Your Title" --symbol SYM (or --yes).');
-        }
-    }
+    // (identity guard already ran above, via the shared assertRealIdentity — before any RPC)
     // Mint timing: mint-all → the whole series; mint-count N → the first N; else deferred.
     const mintCount = flags['mint-all'] !== undefined ? count : flags['mint-count'] ? Number(flags['mint-count']) : 0;
     if (mintCount > count)
@@ -1515,6 +1673,8 @@ async function cmdDeploySeries(flags) {
             return;
         }
         factory = existing;
+        if (!(await previewFactoryLive(publicClient, factory, 'Series factory')))
+            return;
         info(`would reuse canonical Series factory ${factory}`);
     }
     else {
@@ -1848,8 +2008,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 });
@@ -1877,8 +2040,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.
@@ -1972,18 +2136,166 @@ async function cmdPredict(flags) {
         info(dim('(this is the 1/1 lane; a Series/code drop uses a different factory → a different address — pass --dir / --script to predict those, or use that command\'s --dry-run)'));
     console.log('');
 }
-// A `--remote [url]` flag targets a HOSTED resolver's admin control plane instead of
-// this machine's local projection. Bare `--remote` falls back to ABX_PUBLIC_BASE_URL
-// (the URL baked on-chain). Returns null for a local op (the default).
-function remoteTarget(flags) {
-    const v = flags.remote;
-    if (v === undefined)
-        return null;
-    const base = v !== 'true' ? v : process.env.ABX_PUBLIC_BASE_URL;
-    if (!base) {
-        throw new Error('`--remote` needs a resolver URL: pass `--remote https://host` or set ABX_PUBLIC_BASE_URL in .env');
+// The `--remote <name|url>` target (remote.ts owns the convention): a named remote's
+// `ABX_REMOTE_<NAME>_URL/_TOKEN`, an ad-hoc URL, or bare `--remote` = the self-host default.
+// Returns null for a local op (the default).
+function remoteFlag(flags) {
+    return resolveRemote(flags.remote, flags['remote-token']);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * The factory-verification tri-state, said plainly. `null` means the check never ran (no factory
+ * configured, or the configured one has no code on this chain — common on a local/dev chain), which
+ * is NOT the same as the chain telling us this contract isn't a clone of it.
+ */
+function canonicalLabel(isCanonical) {
+    if (isCanonical === true)
+        return g('yes (factory-verified)');
+    if (isCanonical === false)
+        return `${c.orange}NO — not a clone of the configured factory${c.reset}`;
+    return dim('not checked (no canonical factory for this chain — `abx doctor` shows which)');
+}
+/** How a lifecycle state reads at a glance — the same word everywhere it's printed. */
+function statusLabel(s) {
+    if (s === 'live')
+        return g('live');
+    if (s === 'failed')
+        return `${c.orange}failed${c.reset}`;
+    if (s === 'stale')
+        return `${c.orange}stale${c.reset}`;
+    return dim(s); // queued | backfilling — in progress, not a problem
+}
+/** `label   value` with only the label dimmed — status values carry their own color, and wrapping
+ *  them in `info()` would fight it. */
+const statusRow = (label, value) => console.log(`    ${dim(label.padEnd(10))} ${value}`);
+/**
+ * What to DO about a failure class — whose problem it is and whether waiting is the answer.
+ * The class alone told an agent enough to reason it out; it does not tell a creator, and "whose
+ * problem is this" is the single question a failed catch-up has to answer.
+ */
+function indexErrorAction(cls) {
+    if (cls === 'rpc_rate_limited')
+        return "the SERVICE's chain RPC is throttled — not your key, address, or chain. It retries on its own; if it stays this way, that's the operator's to fix.";
+    if (cls === 'rpc_unavailable')
+        return "the SERVICE can't reach its chain RPC — not your key, address, or chain. It retries on its own; if it stays this way, contact the operator.";
+    if (cls === 'not_abx_contract')
+        return 'the service found no ABX events at that address on this chain — check the address and that the service serves the right chain.';
+    return 'the cause is in the service operator’s logs — nothing you can fix from here; contact them if it persists.';
+}
+/** The one wording for "registered, but catch-up failed" — shared by add/index so both say the same
+ *  thing: what failed, whose problem it is, and that the registration survived. */
+function failedCatchUpMessage(address, remote, err, check) {
+    const cls = err?.class;
+    return (`${address} is registered on ${remote.url}, but its catch-up FAILED` +
+        `${cls ? ` (${cls}${err?.message ? `: ${err.message}` : ''})` : ''}.\n` +
+        `  ${cls ? `→ ${indexErrorAction(cls)}\n  ` : ''}` +
+        `The registration is durable and the service retries with backoff — watch it with ${bold(check + ' --watch')}.`);
+}
+/**
+ * One human line for a status read: where it is, how far along, and why if it's unhappy.
+ *
+ * What "where" means depends on the state, so say the right thing rather than one number that reads
+ * differently in each: a percentage is only honest while BACKFILLING (see indexProgress). A `live`
+ * project's `toBlock` only advances when that project has events, so on a busy chain a perfectly
+ * current project sits far below head — printing that as a ratio makes healthy look broken.
+ */
+function statusLine(s) {
+    const p = indexProgress(s);
+    let where;
+    if (p)
+        where = `${s.toBlock}/${s.headBlock} ${dim(`(${p.percent}%)`)}`;
+    else if (!s.toBlock)
+        where = dim('not indexed yet');
+    else if (s.status === 'live')
+        where = `${g('caught up')} ${dim(`· scanned through block ${s.toBlock}`)}`;
+    else if (s.status === 'stale')
+        where = `${dim('not tracking head right now')} ${dim(`· scanned through block ${s.toBlock}${s.headBlock ? ` of ${s.headBlock}` : ''}`)}`;
+    else
+        where = dim(`scanned through block ${s.toBlock}`);
+    const why = s.error ? `  ${c.orange}${s.error.class}${c.reset}${s.error.message ? dim(` — ${s.error.message}`) : ''}` : '';
+    return `${statusLabel(s.status)}  ${where}${why}`;
+}
+/**
+ * Report a register/reindex answer, whichever of the two conformant shapes the service used.
+ *
+ * A `200` already carries the counts. A `202` means the registration is durable and catch-up is still
+ * running — so by default we poll to a terminal state and print the SAME summary line, giving the
+ * human the "waits, then tells you what happened" UX without the service holding a socket open for
+ * minutes. `--no-wait` stops at the 202 and names the command that checks later.
+ */
+async function reportRemoteIndexing(remote, chainId, address, r, flags, verb) {
+    // A real ABX clone ALWAYS emits a spine (its extension registrations at minimum), so a caught-up
+    // projection with zero events means the service scanned the wrong chain/floor or its RPC hasn't
+    // served the logs — not that the project is empty. A ✓ there is the lie that produces an empty
+    // dashboard (the same guard `reindexAfterDeploy` applies locally).
+    const settledLine = (events, tail) => {
+        if (events > 0)
+            ok(`remote resolver ${verb} ${address}: ${tail}`);
+        else
+            warn(`${address} is registered and caught up on ${remote.url}, but with ${bold('0 events')} — it will serve nothing. Check the service covers ${CHAIN} and that its RPC serves logs from the deploy block.`);
+    };
+    if (!isAccepted(r)) {
+        settledLine(r.project.eventCount, `${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
+        return;
+    }
+    const spec = remote.name ? remote.name.toLowerCase() : remote.source === 'default' ? '' : remote.url;
+    const check = `abx status ${address} --remote${spec ? ` ${spec}` : ''}`;
+    // The registration is durable in EVERY branch here — but don't claim it "is catching up" when the
+    // service already told us the catch-up failed. Two different sentences for two different facts.
+    if (r.project.status === 'failed') {
+        // Lead with the OUTCOME, not the sub-step that succeeded: a line starting "registered on …" skims
+        // as success even with the failure later in the sentence (a reviewer read it exactly that way).
+        warn(`${bold('catch-up FAILED')} on ${remote.url} — nothing is being served yet ${dim('(the registration itself is durable; the service retries it)')}`);
+    }
+    else {
+        info(`registered — ${r.project.status} ${dim('(the service accepted it and is catching up; the registration is durable)')}`);
+    }
+    // A known failure is not something to "not wait" for — we already have the answer, so report it as
+    // one regardless of --no-wait (never a ✓ over a broken index).
+    if (flags['no-wait'] !== undefined && r.project.status !== 'failed') {
+        info(`not waiting (--no-wait). Check with ${bold(check)}`);
+        return;
+    }
+    const label = `remote ${verb === 'indexed' ? 'add' : 'index'}`;
+    if (r.project.status === 'failed') {
+        // Fetch the class the register response may not have carried, so the "whose problem" line is
+        // never missing on the path that reports the failure soonest.
+        const st = await serviceClient(remote).projectStatus(chainId, address).catch(() => undefined);
+        throw new Error(`${label}: ${failedCatchUpMessage(address, remote, st?.error ?? undefined, check)}`);
+    }
+    let shown = -100;
+    let lastStatus;
+    try {
+        const final = await serviceClient(remote).awaitIndexed(chainId, address, {
+            onProgress: (s) => {
+                const p = indexProgress(s);
+                // Print on a state change or a meaningful step — a poll line every 3s is noise in a log an
+                // agent has to read back.
+                if (s.status !== lastStatus || (p && p.percent - shown >= 10)) {
+                    lastStatus = s.status;
+                    if (p)
+                        shown = p.percent;
+                    console.log(`      ${statusLine(s)}`);
+                }
+            },
+        });
+        if (final.status === 'failed') {
+            throw new Error(`${label}: ${failedCatchUpMessage(address, remote, final.error, check)}`);
+        }
+        settledLine(final.eventCount, `${final.eventCount} events, ${final.tokenCount} token(s) ${dim('(live)')}`);
+    }
+    catch (err) {
+        if (err instanceof AbxIndexTimeoutError) {
+            warn(`${address} is still ${err.last?.status ?? 'catching up'} on ${remote.url} — nothing is lost, it just isn't done.`);
+            info(`follow it with ${bold(check + ' --watch')}`);
+            return;
+        }
+        // The service went away mid-wait (or rejected the poll). The registration still landed — say
+        // which failure this is, in the same words every other remote command uses.
+        if (err instanceof AbxServiceError)
+            throw describeRemoteError(err, remote, `remote ${verb}: registered, but polling status`);
+        throw err;
     }
-    return base;
 }
 /**
  * Ensure a resolver admin token exists locally, generating + persisting one to `.env`
@@ -2016,24 +2328,24 @@ function ensureEffectsToken() {
     process.env.ABX_EFFECTS_TOKEN = token;
     return { token, generated: true };
 }
-/** The shared secret that authorizes remote indexing control (never on-chain signing). */
-function requireAdminToken() {
-    const t = process.env.ABX_RESOLVER_ADMIN_TOKEN;
-    if (!t) {
-        throw new Error('remote ops need ABX_RESOLVER_ADMIN_TOKEN in your .env — it must match the token set on the resolver ' +
-            '(`abx deploy-resolver` generates one and wires both sides).');
-    }
-    return t;
-}
 // ── add ──────────────────────────────────────────────────────────────────────
 // Register + index a project this node didn't deploy. LOCAL by default (this
 // machine's store); `--remote [url]` instead tells a HOSTED resolver to index it —
 // the bridge a local deploy can't make on its own (separate projection stores).
 async function cmdAdd(address, flags) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx add <address> [--from-block N] [--factory 0x..] [--label "..."] [--remote [url]]\n');
+        console.error('usage: abx add <address> [--from-block N] [--factory 0x..] [--label "..."] [--remote [name|url]]\n');
         process.exit(1);
     }
+    // REFUSE `--dry-run` rather than ignoring it. `add` is a write (a local registration + index, and
+    // with `--remote` a registration on someone else's service), and it has no preview mode — so
+    // silently proceeding to DO the thing when the caller explicitly asked to preview is the one
+    // outcome we must never produce. Name what's read-only instead.
+    if (flags['dry-run'] !== undefined) {
+        throw new Error('`abx add` has no --dry-run: it registers + indexes for real (and with --remote it registers on that service). ' +
+            'Nothing here touches the chain, but it does write. To look before acting: `abx state <address>` (on-chain snapshot) ' +
+            'or `abx status <address> [--remote <name>]` (what a node already has). Re-run without --dry-run when you mean it.');
+    }
     // `--attributes` is lane-aware here exactly as at deploy: a PER-TOKEN payload edits a Series'
     // per-token off-chain traits; a flat payload (+ `--traits`) edits the collection/1-of-1 `attributes`.
     // Ambiguity defaults to flat (see looksPerTokenAttributes), so a 1/1 add is never mis-read.
@@ -2045,10 +2357,10 @@ async function cmdAdd(address, flags) {
     if (flags.traits)
         flagTraits.push(...parseTraitPairs(flags.traits));
     const editedTokenAttributes = perTokenEdit ? parseSeriesTraitsById(attrRaw) : undefined;
-    const remote = remoteTarget(flags);
+    const remote = remoteFlag(flags);
     if (remote) {
-        const token = requireAdminToken();
-        // Bridge what a hosted resolver can't derive itself: the off-chain traits and the durable
+        requireRemoteToken(remote);
+        // Bridge what a remote resolver can't derive itself: the off-chain traits and the durable
         // content locators (ipfs://…). Prefer flags; otherwise forward what the LOCAL deploy stored
         // (the local registration), and compute locators from this machine's content index if needed.
         const localReg = new SelfHostIndexer().store.getRegistration(address);
@@ -2057,7 +2369,7 @@ async function cmdAdd(address, flags) {
             : localReg?.attributes
                 ? normalizeAttributes(JSON.parse(localReg.attributes))
                 : undefined;
-        // Bridge a Series' per-token off-chain traits to the hosted resolver (the resolver has no other
+        // Bridge a Series' per-token off-chain traits to the remote resolver (the resolver has no other
         // way to derive them — they're operator metadata, not chain state). A fresh per-token `--attributes`
         // EDITS them; otherwise forward what the LOCAL deploy stored. Best-effort parse.
         let tokenAttributes;
@@ -2083,6 +2395,7 @@ async function cmdAdd(address, flags) {
         // (Its ABSENCE here was the bug: a hosted resolver defaulted to genesis and scanned the whole
         // chain.) Re-sending the same floor stays incremental server-side, so a nudge ≠ a re-scan.
         const body = {
+            chainId: resolveChain(CHAIN).id,
             address,
             fromBlock: await resolveScanFloor(address, localReg?.fromBlock, flags),
             factory: await detectCanonicalFactory(address, flags.factory, localReg?.factory),
@@ -2094,12 +2407,22 @@ async function cmdAdd(address, flags) {
             contentLocators: Object.keys(contentLocators).length ? contentLocators : undefined,
             full: flags.full ? true : undefined,
         };
-        info(`${bold('REMOTE')} → ${remote}  ${dim('(registering with the hosted resolver — NOT this machine)')}`);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(registering with the remote resolver — NOT this machine)')}`);
         if (body.contentLocators)
             info(`bridging image locator → ${Object.values(body.contentLocators)[0]} ${dim('(so the resolver points at IPFS, not its own localhost)')}`);
-        const r = await remoteAddProject(remote, token, body);
-        ok(`remote resolver indexed ${r.project.name ?? address}: ${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
-        info(`it now serves ${remote.replace(/\/+$/, '')}/t/${resolveChain(CHAIN).id}/${address.toLowerCase()}/0`);
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject(body);
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote add');
+        }
+        await reportRemoteIndexing(remote, body.chainId, address, r, flags, 'indexed');
+        info(`it now serves ${remote.url}/t/${body.chainId}/${address.toLowerCase()}/0`);
+        // "Indexed" is not "correct". This line proves the service replayed the chain and will answer at
+        // that URL — it says nothing about whether the bytes it serves match the on-chain commitment, and
+        // two reviewers stopped here and reported a blank page as fixed. Name the step that checks.
+        info(`confirm what it actually serves (bytes vs. the on-chain hash): ${bold(`abx verify ${address} --remote ${remote.name?.toLowerCase() ?? remote.url}`)}`);
         return;
     }
     allowLargeScan(flags);
@@ -2142,7 +2465,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) {
@@ -2159,7 +2486,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 /
@@ -2226,6 +2560,271 @@ 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.
+ *
+ * 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 →
@@ -2406,17 +3005,7 @@ async function cmdDeployCode(flags) {
     const dryRun = !!flags['dry-run'];
     const name = flags.name ?? 'ABX Code';
     const symbol = flags.symbol ?? 'ABXC';
-    // Identity guard (mirror deploy/deploy-series): never write demo placeholders as the public
-    // on-chain identity. dry-run only warns so a preview still runs without --name/--symbol.
-    if (!flags.name || !flags.symbol) {
-        if (!flags.name)
-            warn(`no --name → default "${name}" would be the on-chain collection name`);
-        if (!flags.symbol)
-            warn(`no --symbol → default "${symbol}" would be the on-chain symbol`);
-        if (!dryRun && !flags.yes) {
-            throw new Error('refusing to write demo placeholders as your public on-chain identity — pass --name "Your Title" --symbol SYM (or --yes).');
-        }
-    }
+    assertRealIdentity(flags, { name, symbol, dryRun });
     const maxProvided = flags.max !== undefined;
     const max = Number(flags.max ?? 16);
     if (!Number.isInteger(max) || max <= 0)
@@ -3257,7 +3846,7 @@ async function loadEffects() {
  */
 async function cmdRender(address, tokenIds, flags) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx render <address> [tokenId…] [--force] [--remote [url]]   (missing stills/traits; --force re-renders an existing one — abx render --help)\n');
+        console.error('usage: abx render <address> [tokenId…] [--force] [--remote [name|url]]   (missing stills/traits; --force re-renders an existing one — abx render --help)\n');
         process.exit(1);
     }
     // Token ids are decimal (mint order). Keep only those — `parseFlags` leaves `--flag value` pairs
@@ -3294,12 +3883,12 @@ async function cmdRender(address, tokenIds, flags) {
             ok(line);
         return;
     }
-    // --remote publishes each render to the hosted resolver's control plane (the locator bridge) so a
+    // --remote publishes each render to the remote resolver's control plane (the locator bridge) so a
     // laptop render lands on a resolver that doesn't share this disk; republish=true makes a re-run
     // restore a resolver that lost its volume without re-rendering. Local (no --remote): shared backend.
-    const remote = remoteTarget(flags);
-    const resolverUrl = (remote ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
-    const adminToken = remote ? requireAdminToken() : undefined;
+    const remote = remoteFlag(flags);
+    const resolverUrl = (remote?.url ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
+    const adminToken = remote ? requireRemoteToken(remote) : undefined;
     // 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.
@@ -3334,8 +3923,11 @@ async function cmdRender(address, tokenIds, flags) {
  * single time and exits (vs `abx render <addr>` which is the per-project repair lane).
  */
 async function cmdEffects(flags) {
-    const resolverUrl = (remoteTarget(flags) ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
-    const adminToken = process.env.ABX_RESOLVER_ADMIN_TOKEN;
+    const effectsRemote = remoteFlag(flags);
+    const resolverUrl = (effectsRemote?.url ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
+    // Token optional BY DESIGN: no token = the co-located topology (shared store, no publish lane).
+    // A named remote brings its own token; otherwise the self-host env token.
+    const adminToken = effectsRemote?.token ?? process.env.ABX_RESOLVER_ADMIN_TOKEN;
     // Co-located (no admin token — we share the resolver's store): record each declared output into
     // 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.
@@ -3375,16 +3967,23 @@ async function cmdEffects(flags) {
     await new Promise(() => { }); // block like `serve`
 }
 async function cmdIndex(address, flags) {
-    const remote = remoteTarget(flags);
+    const remote = remoteFlag(flags);
     if (remote) {
         if (!address || address.startsWith('--')) {
-            console.error('usage: abx index <address> --remote [url]   (re-index one project on a hosted resolver)\n');
+            console.error('usage: abx index <address> --remote [name|url]   (re-index one project on a remote resolver)\n');
             process.exit(1);
         }
-        const token = requireAdminToken();
-        info(`${bold('REMOTE')} → ${remote}  ${dim('(re-indexing on the hosted resolver — the post-deploy nudge)')}`);
-        const r = await remoteAddProject(remote, token, { address, full: flags.full ? true : undefined });
-        ok(`remote resolver re-indexed ${r.project.name ?? address}: ${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
+        requireRemoteToken(remote);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(re-indexing on the remote resolver — the post-deploy nudge)')}`);
+        const chainId = resolveChain(CHAIN).id;
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject({ chainId, address, full: flags.full ? true : undefined });
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote index');
+        }
+        await reportRemoteIndexing(remote, chainId, address, r, flags, 're-indexed');
         return;
     }
     allowLargeScan(flags);
@@ -3414,7 +4013,7 @@ async function cmdVerify(address, flags) {
         process.exit(1);
     }
     allowLargeScan(flags);
-    const remote = remoteTarget(flags);
+    const remote = remoteFlag(flags);
     if (remote)
         return cmdVerifyRemote(address, remote);
     const indexer = new SelfHostIndexer();
@@ -3428,7 +4027,11 @@ async function cmdVerify(address, flags) {
     if (!state)
         throw new Error(`could not load state for ${address}`);
     console.log(bold(`\n  verify ${state.name ?? address}`));
-    info(`canonical: ${state.isCanonical ? g('yes (factory-verified)') : 'unverified'} · owner ${state.owner ?? '—'}`);
+    // isCanonical is a TRUE TRI-STATE (true | false | null) and collapsing it lost the only
+    // distinction that matters: "the chain says this is NOT a clone of the configured factory" is a
+    // trust finding; "we couldn't run the check" (no factory configured, or none deployed on this
+    // chain) is an environment note. Two reviewers read the collapsed word as a second failure.
+    info(`canonical: ${canonicalLabel(state.isCanonical)} · owner ${state.owner ?? '—'}`);
     const storage = resolveBackend(storageOptions());
     const result = await verifyProject(state, storage);
     const tokens = result.tokens ?? [];
@@ -3558,18 +4161,33 @@ async function cmdVerify(address, flags) {
         console.log(`\n  ${dim('live view animates regardless; the placeholder only affects the static marketplace thumbnail.')}\n`);
     else
         console.log(anyCheck && allGood ? `\n  ${g('✓ verified')} — the node serves exactly what the chain commits to.\n` : '\n');
+    // A byte-vs-chain mismatch is an integrity FAILURE, so fail the command. Verify's whole job is to
+    // answer "is what's served what the chain vouches for" — exiting 0 while printing ✗ meant nothing
+    // could gate on it (a script or CI would sail past a corrupted image). Deliberately narrow: a
+    // missing render / placeholder is a normal, expected state and still exits 0.
+    if (anyCheck && !allGood)
+        process.exitCode = 1;
 }
 // `abx verify <addr> --remote <url>` — verify what a HOSTED resolver actually serves (the local
 // `verify` checks THIS machine's store/backend, the wrong store for a hosted drop). Probes the real
 // `/…/image` route, so it accounts for the locator bridge (a 302 to ipfs/ar) exactly as a marketplace
 // sees it — the truthful "did the thumbnail land?" check after a remote render.
-async function cmdVerifyRemote(address, resolver) {
-    const base = resolver.replace(/\/$/, '');
+async function cmdVerifyRemote(address, remote) {
+    const base = remote.url.replace(/\/$/, '');
     const chainId = resolveChain(CHAIN).id;
     console.log(bold(`\n  verify ${address} ${dim(`(remote → ${base})`)}`));
-    const stateRes = await fetch(`${base}/api/project/${address}`);
+    // A DOWN endpoint and a wrong-address endpoint are different problems with different fixes, and a
+    // bare `fetch failed` says neither. `abx status --remote` already gets this right — match it, or the
+    // two commands disagree about the same condition (a reviewer's top misdiagnosis risk).
+    let stateRes;
+    try {
+        stateRes = await fetch(`${base}/api/project/${address}`);
+    }
+    catch {
+        throw new Error(`verify: nothing responded at ${base}${remote.source === 'named' ? ` (from ABX_REMOTE_${remote.name}_URL)` : ''}. Is it running, and is that the right address?`);
+    }
     if (!stateRes.ok) {
-        throw new Error(`resolver ${base} doesn't serve ${address} (HTTP ${stateRes.status}) — register it first: abx add ${address} --remote ${base}`);
+        throw new Error(`resolver ${base} doesn't serve ${address} (HTTP ${stateRes.status}) — register it first: abx add ${address} --remote ${remote.name?.toLowerCase() ?? base}`);
     }
     const state = (await stateRes.json());
     info(`serving as "${state.name ?? address}"`);
@@ -3615,10 +4233,24 @@ async function cmdVerifyRemote(address, resolver) {
                 console.log(`    ${c.orange}⚠${c.reset} ${label}: stale — no render at the current state yet (the runner's next notify/sweep picks it up, or \`abx render ${address} --remote ${base}\`)`);
         }
         const { upToDate, stale, rendering, failed } = report.counts;
-        const summary = `${upToDate}/${minted.length} up to date${rendering ? ` · ${rendering} rendering` : ''}${stale ? ` · ${stale} stale` : ''}${failed ? ` · ${failed} FAILED` : ''}`;
-        console.log(failed || stale
-            ? `\n  ${c.orange}⚠${c.reset} ${summary} ${dim('— live view animates regardless; only the static thumbnail is affected.')}\n`
-            : `\n  ${g(`✓ ${summary}`)} — served straight from the resolver.\n`);
+        // RENDERS ONLY — say so. This report answers "is there a current render for each token", never
+        // "do the served bytes match the on-chain commitment"; those are different questions and this
+        // command promises the second one too. A project with no renders at all (a 1/1, an image Series)
+        // has nothing to be "up to date" ABOUT, so don't print a 0/N fraction — but don't let a green ✓
+        // here read as "the image is verified" either. Byte integrity comes from the check below.
+        if (report.tokens.length === 0) {
+            info(`renders    ${dim('none for this project (a static image needs no off-chain render)')}`);
+        }
+        else {
+            // Lead with the count that carries the polarity: "N of M current" never inverts on a skim the
+            // way "0/M up to date" does.
+            const summary = `${upToDate} of ${minted.length} token(s) current${rendering ? ` · ${rendering} rendering` : ''}${stale ? ` · ${stale} stale` : ''}${failed ? ` · ${failed} FAILED` : ''}`;
+            if (failed || stale)
+                console.log(`  ${c.orange}⚠${c.reset} renders: ${summary} ${dim('— live view animates regardless; only the static thumbnail is affected.')}`);
+            else
+                ok(`renders: ${summary}`);
+        }
+        await reportRemoteByteIntegrity(address, remote, base);
         return;
     }
     let gap = false;
@@ -3636,8 +4268,63 @@ async function cmdVerifyRemote(address, resolver) {
         }
     }
     console.log(gap
-        ? `\n  ${dim('live view animates regardless; the placeholder only affects the static marketplace thumbnail.')}\n`
-        : `\n  ${g('✓ thumbnails are real renders')} — served straight from the resolver.\n`);
+        ? `  ${dim('live view animates regardless; the placeholder only affects the static marketplace thumbnail.')}`
+        : `  ${g('✓ thumbnails are real renders')} ${dim('— served straight from the resolver.')}`);
+    await reportRemoteByteIntegrity(address, remote, base);
+}
+/**
+ * The half `abx verify --remote` was missing: do the served BYTES still hash to the on-chain
+ * commitment? Everything above it checks renders (is a thumbnail current, is it a placeholder) — a
+ * different question, and a green ✓ there was reading as "the image is correct" when the bytes could
+ * genuinely mismatch.
+ *
+ * The service is the right place to answer it: it holds both the bytes and the chain, and it already
+ * exposes exactly this check (`GET /api/project/:addr/verify`, bearer-gated because it triggers
+ * outbound fetches). When we can't reach that — no credential, or an older node — say plainly that
+ * byte integrity was NOT checked rather than leaving the ✓ above to imply it was.
+ */
+async function reportRemoteByteIntegrity(address, remote, base) {
+    if (!remote.token) {
+        warn(`byte integrity NOT checked — that check is credentialed on the service. Set ${remote.tokenVar} (or pass --remote-token) and re-run, or run ${bold(`abx verify ${address}`)} against a node that holds the bytes.`);
+        return;
+    }
+    let report;
+    try {
+        const res = await fetch(`${base}/api/project/${address}/verify`, { headers: { authorization: `Bearer ${remote.token}` } });
+        if (res.status === 401 || res.status === 403) {
+            warn(`byte integrity NOT checked — ${base} rejected ${tokenSourceLabel(remote)} for its verify route (the read plane served fine, so this is a credential/scoping issue, not a broken project).`);
+            return;
+        }
+        if (!res.ok) {
+            // Spec'd as part of `abx-token-api/v1`, so a conforming service has it — but say it neutrally:
+            // this is equally "an older self-hosted node" and "a provider that didn't implement it".
+            warn(`byte integrity NOT checked — ${base} serves no /api/project/…/verify route (HTTP ${res.status}). ` +
+                `Your own node? Redeploy it (\`abx deploy-resolver\`). A provider's? It's part of abx-token-api/v1 — ask them for it. ` +
+                `Meanwhile ${bold(`abx verify ${address}`)} checks the bytes on a node that holds them.`);
+            return;
+        }
+        report = (await res.json());
+    }
+    catch {
+        warn(`byte integrity NOT checked — couldn't reach ${base}'s verify route.`);
+        return;
+    }
+    const checked = (report.tokens ?? []).filter((t) => t.checks.length > 0);
+    if (checked.length === 0) {
+        info(`bytes      ${dim('no on-chain byte commitment to check (this project commits no image hash)')}`);
+        return;
+    }
+    const bad = checked.filter((t) => t.checks.some((k) => !k.verified));
+    if (bad.length === 0) {
+        ok(`bytes: ${checked.length} token(s) hash-match their on-chain commitment ${dim('(what the service serves IS what the chain vouches for)')}`);
+        return;
+    }
+    const spec = remote.name?.toLowerCase() ?? base;
+    console.log(`  ${c.red}✗${c.reset} ${bold('BYTE MISMATCH')} on token(s) ${bad.map((t) => `#${t.tokenId}`).join(', ')} — ${base} does NOT serve bytes that hash to the on-chain commitment ` +
+        `${dim('(this is what a marketplace shows as a blank or placeholder image)')}. The chain is the truth, so the served copy is the wrong one. Two causes, two fixes:`);
+    info(`durable bytes exist (ipfs://, ar://) but weren't bridged → ${bold(`abx add ${address} --remote ${spec}`)} forwards the locator, then re-run this.`);
+    info(`the bytes only exist on THIS machine (local fs custody) → a hosted resolver can never serve them: ${bold('abx storage upload')} to a durable backend + re-point the field, or serve the project from a node that holds them.`);
+    process.exitCode = 1; // same rule as the local lane: an integrity mismatch fails the command
 }
 // ── tokenuri ─────────────────────────────────────────────────────────────────
 // Read tokenURI(id) STRAIGHT FROM THE CONTRACT on-chain (no server, no node) and decode
@@ -3688,7 +4375,12 @@ async function cmdTokenUri(address, flags) {
     catch {
         const code = await publicClient.getCode({ address }).catch(() => undefined);
         if (!code || code === '0x') {
-            console.error(`abx tokenuri: no contract at ${address} on ${CHAIN} — double-check the address and that you're on the right chain. If you JUST deployed, give the tx a block or two to mine.\n`);
+            // Name the endpoint we actually asked. "No contract here" is indistinguishable from "you're
+            // pointed at the wrong node", and a chain KEY doesn't disambiguate that — two endpoints can
+            // both claim `sepolia` (a fork, a stale duplicate .env line) and only one has your contract.
+            console.error(`abx tokenuri: no contract at ${address} on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}) — ` +
+                `double-check the address, and that this endpoint is the network you deployed to. ` +
+                `If you JUST deployed, give the tx a block or two to mine.\n`);
         }
         else {
             console.error(`abx tokenuri: ${address} didn't return a tokenURI for token ${tokenId} — it may not be an ABX/ERC-721 token, token ${tokenId} may be unminted (try --token <id>), or — on a large on-chain tokenURI — an unauthenticated RPC read hit its gas cap (try a wallet-connected / high-gas RPC).\n`);
@@ -4007,9 +4699,53 @@ async function cmdState(address, flags) {
     info(`renderer       ${renderer && renderer !== zeroAddress ? `on-chain (${renderer})` : dim('off-chain (stored URI base / override)')}`);
     console.log('');
 }
-async function cmdStatus() {
+/**
+ * `abx status [address] [--remote [name|url]] [--watch]` — INDEXING status: where a project sits in
+ * the lifecycle (`queued | backfilling | live | stale | failed`) and how far behind head it is.
+ *
+ * One vocabulary for both sides of the membrane, which is the point: bare = this node, `--remote` =
+ * ask the service, and the same five words either way. Distinct from `abx state <address>`, which
+ * reads the CHAIN (owner, royalty, locks) and knows nothing about who is serving it.
+ */
+async function cmdStatus(address, flags) {
+    // `abx status --remote <name>` has no address — without this guard the flag itself lands in
+    // rest[0] and gets sent as the address path segment (the same guard every other command applies).
+    if (address?.startsWith('--'))
+        address = undefined;
+    const remote = remoteFlag(flags);
+    if (remote)
+        return cmdStatusRemote(address, remote, flags);
     const indexer = new SelfHostIndexer();
     const regs = indexer.store.listRegistrations();
+    if (address) {
+        const reg = indexer.store.getRegistration(address);
+        if (!reg)
+            throw new Error(`${address} isn't tracked by this node. Add it with \`abx add ${address}\`, or ask a service: \`abx status ${address} --remote <name>\``);
+        const s = indexer.getProject(address);
+        const row = indexer.indexStatus(address);
+        const head = indexer.store.getMeta(`watch:${reg.chainKey}:head`);
+        // Don't print the address twice when there's no name to lead with.
+        console.log(s?.name ? `\n  ${bold(s.name)}  ${dim(address)}` : `\n  ${bold(address)}`);
+        statusRow('status', statusLine({
+            chainId: resolveChain(reg.chainKey).id,
+            address,
+            status: row.status,
+            fromBlock: reg.fromBlock,
+            toBlock: s?.toBlock ?? null,
+            headBlock: head,
+            eventCount: s?.eventCount ?? 0,
+            tokenCount: s?.tokens.length ?? 0,
+            mintedCount: 0,
+            reconstructedAt: s?.reconstructedAt ?? null,
+            ...(row.errorClass ? { error: { class: row.errorClass, message: row.errorMessage ?? undefined } } : {}),
+        }));
+        statusRow('floor', `${reg.fromBlock}${row.attempts ? dim(`   attempts ${row.attempts}`) : ''}`);
+        statusRow('indexed', s ? `${s.eventCount} events · ${s.tokens.length} token(s) ${dim(`· ${s.reconstructedAt}`)}` : dim('no projection yet'));
+        if (!head)
+            statusRow('head', dim("unknown — this node isn't watching the chain (ABX_WATCH_INTERVAL_MS=0, or `abx serve` isn't running)"));
+        console.log('');
+        return;
+    }
     console.log(bold(`\n  ABX self-host node`));
     info(`chain: ${CHAIN} · factory: ${factoryAddress() ?? 'none'} · storage: ${activeBackendId()} · data: ${indexer.store.path}`);
     if (regs.length === 0) {
@@ -4019,27 +4755,114 @@ async function cmdStatus() {
     console.log('');
     for (const reg of regs) {
         const s = indexer.getProject(reg.address);
-        const line = s
-            ? `${g('●')} ${s.name ?? s.address}  ${dim(s.address)}  ${s.eventCount} events`
-            : `${dim('○')} ${reg.address}  ${dim('(registered, not indexed)')}`;
-        console.log('  ' + line);
+        const st = indexer.indexStatus(reg.address).status;
+        const mark = st === 'failed' || st === 'stale' ? `${c.orange}●${c.reset}` : s ? g('●') : dim('○');
+        const tail = s ? `${s.eventCount} events` : dim('(registered, not indexed)');
+        console.log(`  ${mark} ${s?.name ?? reg.address}  ${dim(reg.address)}  ${tail}  ${statusLabel(st)}`);
     }
-    console.log('');
+    console.log(dim(`\n  one project in detail: abx status <address>\n`));
+}
+/** The `--remote` half of {@link cmdStatus}: one project, or the roll-up for every project the token
+ *  can see. `--watch` tails until everything reaches a terminal state. */
+async function cmdStatusRemote(address, remote, flags) {
+    requireRemoteToken(remote);
+    const client = serviceClient(remote);
+    const chainId = resolveChain(CHAIN).id;
+    const watch = flags.watch !== undefined;
+    const spec = remote.name ? remote.name.toLowerCase() : remote.source === 'default' ? '' : remote.url;
+    info(`${bold('REMOTE')} → ${remote.url}  ${dim('(indexing status as the service reports it)')}`);
+    if (address) {
+        for (;;) {
+            let s;
+            try {
+                s = await client.projectStatus(chainId, address);
+            }
+            catch (err) {
+                throw describeRemoteError(err, remote, 'remote status');
+            }
+            console.log(`\n  ${bold(address)}`);
+            statusRow('status', statusLine(s));
+            statusRow('floor', `${s.fromBlock}${s.attempts ? dim(`   attempts ${s.attempts}`) : ''}`);
+            statusRow('indexed', `${s.eventCount} events · ${s.tokenCount} token(s)${s.reconstructedAt ? dim(` · ${s.reconstructedAt}`) : ''}`);
+            // Spell out what `watching` MEANS on the line itself — a bare `no` sent a reviewer to a
+            // different command's output to find out whether it was a problem (it usually isn't).
+            if (s.watcher) {
+                statusRow('watching', s.watcher.watching
+                    ? `${g('yes')}${s.watcher.head ? dim(` · head ${s.watcher.head}`) : ''}${dim(' — it tails new blocks, so on-chain changes land on their own')}`
+                    : `${dim('no')} ${dim('— this service updates on an explicit add/index, not by tailing new blocks (normal for many providers)')}`);
+            }
+            // Don't leave a creator staring at a red word with no next move. `failed` especially reads as
+            // terminal when it isn't — name what it means and the one command that follows it.
+            if (!watch && s.status !== 'live') {
+                if (s.status === 'failed' && s.error)
+                    statusRow('what now', indexErrorAction(s.error.class));
+                statusRow('follow', dim(`this is not final — ${bold(`abx status ${address} --remote${spec ? ` ${spec}` : ''} --watch`)} tails it until it settles`));
+            }
+            console.log('');
+            if (!watch || s.status === 'live' || s.status === 'failed')
+                return;
+            await sleep(3000);
+        }
+    }
+    for (;;) {
+        let projects;
+        try {
+            projects = await client.listProjects();
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote status');
+        }
+        if (projects.length === 0) {
+            console.log(dim('\n  no projects visible to this token\n'));
+            return;
+        }
+        console.log('');
+        for (const p of projects) {
+            console.log(`  ${g('●')} ${p.name ?? p.label ?? p.address}  ${dim(p.address)}  ` +
+                `${p.status ? statusLabel(p.status) : dim('status not reported')}` +
+                `${p.error ? ` ${c.orange}${p.error.class}${c.reset}` : ''}  ${dim(`${p.tokenCount ?? '?'} token(s)`)}`);
+        }
+        console.log(`\n  ${rollUp(projects)}\n`);
+        const settled = projects.every((p) => !p.status || p.status === 'live' || p.status === 'failed');
+        if (!watch || settled)
+            return;
+        await sleep(3000);
+    }
+}
+/** "3 live, 1 backfilling, 1 failed (rpc_rate_limited)" — the one-line answer to "is my stuff ok?" */
+function rollUp(projects) {
+    const counts = new Map();
+    for (const p of projects) {
+        const k = p.status ?? 'unknown';
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    const classes = [...new Set(projects.filter((p) => p.error).map((p) => p.error.class))];
+    const parts = [...counts.entries()].map(([k, n]) => `${n} ${k}`);
+    return `${parts.join(', ')}${classes.length ? ` ${dim(`(${classes.join(', ')})`)}` : ''}`;
 }
 // ── forget ────────────────────────────────────────────────────────────────--
 // Drop a project this node tracks (registration + projection) — for cleaning up
 // test/junk deploys. On-chain data is untouched; `abx add` can re-register it.
 async function cmdForget(address, flags) {
     if (!address || address.startsWith('--')) {
-        console.error('usage: abx forget <address> [--remote [url]]\n');
+        console.error('usage: abx forget <address> [--remote [name|url]]\n');
         process.exit(1);
     }
-    const remote = remoteTarget(flags);
+    const remote = remoteFlag(flags);
     if (remote) {
-        const token = requireAdminToken();
-        info(`${bold('REMOTE')} → ${remote}  ${dim('(deregistering on the hosted resolver — NOT this machine)')}`);
-        await remoteRemoveProject(remote, token, address);
-        ok(`remote resolver forgot ${address} — it will stop serving it. On-chain data is untouched.`);
+        requireRemoteToken(remote);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(deregistering on the remote resolver — NOT this machine)')}`);
+        let removed;
+        try {
+            ({ removed } = await serviceClient(remote).removeProject(resolveChain(CHAIN).id, address));
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote forget');
+        }
+        if (removed)
+            ok(`remote resolver forgot ${address} — it will stop serving it. On-chain data is untouched.`);
+        else
+            console.log(dim(`  ${address} wasn't registered on ${remote.url} — nothing to forget.`));
         return;
     }
     const indexer = new SelfHostIndexer();
@@ -4050,6 +4873,97 @@ async function cmdForget(address, flags) {
     indexer.store.deregister(address);
     ok(`forgot ${address} — dropped its registration + projection. On-chain data is untouched.`);
 }
+// ── remote ────────────────────────────────────────────────────────────────--
+// Inspect a remote service. Bare `abx remote` lists the named remotes configured in .env plus the
+// self-host default pair (URLs + whether a token is set — never the secret itself). With a target,
+// fetches its PUBLIC service descriptor (what it serves: interfaces, chains, auth, managed
+// rendering) and — when a token resolves — lists the projects visible to that token, which makes
+// this the one-command "is my provider key valid?" check. Read-only; registers nothing.
+async function cmdRemote(spec, flags) {
+    if (!spec || spec.startsWith('--')) {
+        const remotes = listConfiguredRemotes();
+        console.log(`\n  ${bold('named remotes')}  ${dim('(ABX_REMOTE_<NAME>_URL/_TOKEN in .env — inspect one: abx remote <name>)')}`);
+        if (remotes.length === 0)
+            console.log(dim('    none configured'));
+        for (const r of remotes) {
+            console.log(`    ${g('●')} ${r.name.toLowerCase()}  ${dim(r.url)}  ${r.hasToken ? g('token set') : dim('no token')}`);
+        }
+        // A near-miss var reads as "no token" while the value is sitting in .env under the wrong name.
+        for (const bad of misnamedRemoteVars()) {
+            warn(`${bad.key} isn't a recognized remote var — the convention is ${bold(bad.suggestion)} (only _URL and _TOKEN are read).`);
+        }
+        const def = process.env.ABX_PUBLIC_BASE_URL ?? process.env.ABX_RESOLVER_URL;
+        console.log(`\n  ${bold('self-host default')}  ${dim('(bare --remote)')}`);
+        console.log(def
+            ? `    ${g('●')} ${def}  ${process.env.ABX_RESOLVER_ADMIN_TOKEN ? g('token set') : dim('no ABX_RESOLVER_ADMIN_TOKEN')}`
+            : dim('    none (set ABX_PUBLIC_BASE_URL in .env)'));
+        console.log('');
+        return;
+    }
+    const target = resolveRemote(spec, flags['remote-token']);
+    if (!target)
+        return;
+    const client = serviceClient(target);
+    console.log(`\n  ${bold(target.name ? `remote ${target.name.toLowerCase()}` : 'remote')} ${dim(`→ ${target.url}`)}`);
+    let d;
+    try {
+        d = await client.descriptor();
+    }
+    catch (err) {
+        // Two very different situations, and the fix differs — so don't nest the raw client error
+        // (it repeats the URL and leaks `GET`/`fetch failed` at a creator).
+        const status = err instanceof AbxServiceError ? err.status : -1;
+        if (status === 0) {
+            throw new Error(`nothing responded at ${target.url} — check the address. A provider gives you an https:// base ` +
+                `(e.g. https://meta.provider.xyz); if it's your own node, is it running?`);
+        }
+        throw new Error(`${target.url} answered, but serves no ABX service descriptor at /.well-known/abx-service. ` +
+            `That's either an older self-hosted node (fine if it's yours — the remote commands still work against it) ` +
+            `or not an ABX service at all. Verify the URL before registering anything with it.`);
+    }
+    info(`service    ${d.service?.name ?? '—'} ${dim(d.service?.version ?? '')}`);
+    info(`serves     ${(d.interfaces ?? []).join(' · ') || '—'}`);
+    const chainId = resolveChain(CHAIN).id;
+    const coversChain = (d.chains ?? []).includes(chainId);
+    info(`chains     ${(d.chains ?? []).join(', ') || '—'}  ${coversChain ? g(`✓ covers ${CHAIN} (${chainId})`) : `${c.orange}⚠${c.reset} does NOT cover ${CHAIN} (${chainId}) — registrations will be refused`}`);
+    if (d.render?.attached) {
+        const outputs = d.render.effects?.flatMap((e) => e.outputs.map((o) => `${e.key}/${o.key}`)).join(', ');
+        info(`rendering  managed behind this service${outputs ? ` (${outputs})` : d.render.effects === null ? dim(' (attached — runner unverified right now)') : ''} — code drops need no effects runner here`);
+    }
+    if (d.auth) {
+        info(`auth       bearer${d.auth.signupUrl ? ` · get a key: ${d.auth.signupUrl}` : ''}${d.auth.docsUrl ? ` · docs: ${d.auth.docsUrl}` : ''}`);
+    }
+    else {
+        info(`auth       none advertised ${dim('(control plane disabled on this node)')}`);
+    }
+    if (!target.token) {
+        // Same near-miss check the register path does — this is where someone lands FIRST when their
+        // credential is set under a name the CLI doesn't read, so the hint has to be here too.
+        const nearMiss = misnamedRemoteVars().find((v) => v.suggestion === target.tokenVar);
+        if (nearMiss)
+            warn(`${nearMiss.key} is set but is NOT read — the convention is ${bold(target.tokenVar)} (only _URL and _TOKEN). Rename it and re-run.`);
+        else
+            info(dim(`no token resolved (set ${target.tokenVar} or pass --remote-token) — descriptor only; can't list your projects.`));
+        console.log('');
+        return;
+    }
+    try {
+        const projects = await client.listProjects();
+        ok(`token accepted — ${projects.length} project(s) visible to it`);
+        for (const p of projects.slice(0, 10)) {
+            console.log(`    ${g('●')} ${p.name ?? p.label ?? p.address}  ${dim(`${p.address} · ${p.tokenCount ?? '?'} token(s)`)}` +
+                `${p.status ? `  ${statusLabel(p.status)}` : ''}${p.error ? ` ${c.orange}${p.error.class}${c.reset}` : ''}`);
+        }
+        if (projects.length > 10)
+            console.log(dim(`    … and ${projects.length - 10} more`));
+        if (projects.some((p) => p.status))
+            info(rollUp(projects) + dim('  — one project in detail: abx status <address> --remote ' + (target.name?.toLowerCase() ?? target.url)));
+    }
+    catch (err) {
+        throw describeRemoteError(err, target, 'remote list');
+    }
+    console.log('');
+}
 // ── migrate ───────────────────────────────────────────────────────────────--
 // Move a contract's OFF-CHAIN operator state from one resolver to another (e.g. fly.io →
 // a droplet). The destination replays all ON-CHAIN state from chain itself; this bridges
@@ -4058,13 +4972,17 @@ async function cmdForget(address, flags) {
 // and write through the admin control plane. It does NOT cut over — after a clean migration the
 // operator re-points DNS (custom domain) or the on-chain base URI (provider endpoint).
 async function cmdMigrate(address, flags) {
-    const from = typeof flags.from === 'string' ? flags.from : undefined;
-    const to = typeof flags.to === 'string' ? flags.to : undefined;
-    if (!address || address.startsWith('--') || !from || !to) {
-        console.error('usage: abx migrate <address> --from <source-resolver-url> --to <dest-resolver-url> [--from-block N]\n');
+    // Both sides accept a named remote or a URL. Only the DESTINATION needs a credential — the
+    // source is read via its PUBLIC api (the exit ramp works with zero provider cooperation).
+    const fromTarget = typeof flags.from === 'string' ? resolveRemote(flags.from) : null;
+    const toTarget = typeof flags.to === 'string' ? resolveRemote(flags.to, flags['remote-token']) : null;
+    if (!address || address.startsWith('--') || !fromTarget || !toTarget) {
+        console.error('usage: abx migrate <address> --from <source-resolver name|url> --to <dest-resolver name|url> [--from-block N]\n');
         process.exit(1);
     }
-    const token = requireAdminToken();
+    requireRemoteToken(toTarget);
+    const from = fromTarget.url;
+    const to = toTarget.url;
     const chainId = resolveChain(CHAIN).id;
     allowLargeScan(flags);
     console.log(bold(`\n  abx migrate ${dim('— port off-chain state between resolvers (no cutover)')}`));
@@ -4121,6 +5039,7 @@ async function cmdMigrate(address, flags) {
     step('Populate the destination');
     const locCount = Object.keys(plan.contentLocators).length;
     const body = {
+        chainId,
         address,
         // The deploy block (locally known); if somehow absent, omit it so the destination derives it
         // rather than scanning from genesis (never bake a from-0 floor into a fresh resolver).
@@ -4133,9 +5052,18 @@ async function cmdMigrate(address, flags) {
         contentLocators: locCount ? plan.contentLocators : undefined,
         full: true, // first registration on the destination — replay from the deploy block
     };
-    info(`${bold('REMOTE')} → ${to} ${dim('(admin control plane — chain replay + off-chain enrichment)')}`);
-    const r = await remoteAddProject(to, token, body);
-    ok(`destination indexed ${r.project.name ?? address}: ${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
+    info(`${bold('REMOTE')} → ${to} ${dim('(control plane — chain replay + off-chain enrichment)')}`);
+    let r;
+    try {
+        r = await serviceClient(toTarget).registerProject(body);
+    }
+    catch (err) {
+        throw describeRemoteError(err, toTarget, 'migrate destination');
+    }
+    // Always wait here, even if the caller passed --no-wait: the parity check below reads the
+    // destination's served metadata, and comparing a half-indexed projection would report a false
+    // mismatch — worse than a slow migrate.
+    await reportRemoteIndexing(toTarget, chainId, address, r, {}, 'indexed');
     // 5) Parity check — does the destination now serve the same metadata as the source? Sample a
     //    token we did NOT re-pin (a re-pinned image is durable-locator-on-dest vs old-host-on-source
     //    BY DESIGN — different there is correct, so comparing it would mislead).
@@ -4165,100 +5093,171 @@ 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\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);
+    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 (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.
+    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>`')}`);
+        opt('arweave key', `${jwk ? arweaveAddress(jwk) + ' ' : ''}holds upload credits — back it up: \`abx storage backup-key --out <path>\``);
+    }
+    // Named remotes: report what's configured, and — the part doctor was missing — flag a credential
+    // stored under a name the CLI does NOT read. That fault presents as "it acts like I never gave it a
+    // key", and until now it only surfaced from `abx remote <name>`, which a creator reaches later
+    // (doctor is the thing they're told to run FIRST).
+    const remotes = listConfiguredRemotes();
+    if (remotes.length) {
+        opt('remotes', remotes.map((r) => `${r.name.toLowerCase()}${r.hasToken ? '' : ` ${c.orange}(no token)${c.reset}`}`).join(' · '));
+    }
+    for (const bad of misnamedRemoteVars()) {
+        check('remote key', false, `${bad.key} is set but is NOT read — the convention is ${bold(bad.suggestion)} (only _URL and _TOKEN). Rename it.`);
     }
     console.log('');
 }
@@ -4273,7 +5272,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 ──────────
@@ -4404,7 +5409,8 @@ async function cmdDeployResolver(flags) {
     const url = art.baseUrl;
     info(`abx deploy --image <art> --name … --public-base-url ${url}   (or export ABX_PUBLIC_BASE_URL=${url})`);
     info(`the contract derives ${url}/t/${resolveChain(CHAIN).id}/{address}/{tokenId} from that base.`);
-    info(`${bold('then')} abx add <clone> --remote   ${dim('# tell the hosted resolver to index it — a LOCAL deploy does NOT')}`);
+    info(`${bold('then')} abx add <clone> --remote   ${dim('# tell the remote resolver to index it — a LOCAL deploy does NOT')}`);
+    info(dim(`prefer addressing it by name? add ABX_REMOTE_<NAME>_URL=${url} (+ ABX_REMOTE_<NAME>_TOKEN=<the same token>) to .env → abx add <clone> --remote <name>`));
     console.log('');
 }
 // ── deploy-effects: scaffold the render runner (the resolver's browser-bearing companion) ─────
@@ -4558,12 +5564,15 @@ function keepAlive() {
 // ── per-command usage (printed by `<cmd> --help` / `abx help <cmd>`; read-only) ──
 const COMMAND_HELP = {
     skill: `
-  ${bold('abx skill')} ${dim('— install the abx agent skill so your coding agent can drive abx')}
-    ${g('abx skill install')}     copy the skill into ${bold('.claude/skills/abx-self-host')} in the current project
-                          ${g('--global')}          install into your home dir (~/.claude/skills) instead of the project
-                          ${g('--target <dir>')}    install under a different base dir (writes <dir>/.claude/skills/abx-self-host)
+  ${bold('abx skill')} ${dim('— install the version-locked abx agent skill so your coding agent can drive abx')}
+    ${g('abx skill install')}     copy the bundled skill (version-locked to this CLI) into your agent(s)
+                          ${dim('default: both')} ${bold('.claude/skills')} ${dim('(Claude Code) and')} ${bold('.agents/skills')} ${dim('(Cursor · Codex · Gemini · Copilot)')}
+                          ${g('--agent <name>')}    only one agent: ${dim('claude | cursor | codex | gemini | copilot')}
+                          ${g('--global')}          install into your home dir (~) instead of the current project
+                          ${g('--target <dir>')}    install the skill folder straight under <dir> (writes <dir>/abx-self-host)
     ${g('abx skill path')}        print the absolute path to the bundled skill (for ${g('npx skills add <path>')} or manual copy)
-    ${dim('Restart your agent after installing so it picks up the skill. Cross-agent install:')} ${g('npx skills add ArtBlocks/abx')}`,
+    ${dim('Restart your agent after installing so it picks up the skill. Once the repo is public, the git-based')}
+    ${dim('cross-agent installer also works (not version-locked):')} ${g('npx skills add ArtBlocks/abx --skill abx-self-host')}`,
     deploy: `
   ${bold('abx deploy')} ${dim('— deploy + index a 1/1 (no server). Sends a tx in the chosen lane.')}
     --image <path>        custody your own image (png · jpg · gif · svg · webp); else generative demo art
@@ -4620,6 +5629,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)
@@ -4686,8 +5709,9 @@ 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 [url]')}        publish each render to a HOSTED resolver (the locator bridge: upload to ${bold('ABX_STORAGE_BACKEND')}, POST /admin/effect-artifacts).
-                          Idempotent; a re-run restores a resolver that lost its volume. Needs ${g('ABX_RESOLVER_ADMIN_TOKEN')}.
+    ${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('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')}
     ${dim(`view of ${g('ABX_RESOLVER_URL')} (else your configured base / local ${g('abx serve')}), and stores to the resolved backend.`)}
@@ -4703,8 +5727,8 @@ 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 HOSTED resolver: ABX_RESOLVER_URL +')}
-    ${dim('ABX_RESOLVER_ADMIN_TOKEN (publish renders + report status). PUBLIC runner? set ABX_EFFECTS_TOKEN — it gates /run + /notify.')}
+    ${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('To HOST the runner (fly/docker), use `abx deploy-effects`.')}`,
     'configure-param': `
   ${bold('abx configure-param')} <address> <tokenId|-> <key> <value> ${dim('— set a PostParam (typed, canonical encode). Sends a tx.')}
@@ -4715,7 +5739,7 @@ const COMMAND_HELP = {
                           like ${g('params.keys')} / ${g('display.gateway')}. ≤31 printable-ASCII chars ride as a literal bytes32; longer takes the data path.
                           After a token write, a project whose ${g('params.keys')} doesn't list the key gets a one-line fix suggestion.
     --file <path>         read the value from a file (String / Bytes payloads)
-    ${g('--remote [url]')}       nudge a HOSTED resolver to re-index IMMEDIATELY after the change (else ABX_PUBLIC_BASE_URL) — it pings
+    ${g('--remote [name|url]')}  nudge a REMOTE resolver to re-index IMMEDIATELY after the change (else ABX_PUBLIC_BASE_URL) — it pings
                           the resolver's effect runner, so the thumbnail re-renders without waiting. Usually OPTIONAL now: a
                           resolver running the chain watcher (the ${g('abx serve')} default) sees the change on its next poll (~12s)
                           and auto-re-renders on its own. Keep --remote for a watcher-disabled resolver or when seconds matter.
@@ -4752,7 +5776,8 @@ const COMMAND_HELP = {
   ${bold('abx state')} <address> ${dim('— read-only, on-chain operational snapshot (no tx, no local index).')}
     Shows owner · supply (minted / max, nextTokenId) · paused · minter · primary payee · royalty · renderer.
     Series-only fields are shown for a Series; a 1/1 shows just supply + royalty + renderer.
-    Handy before/after owner ops (mint · pause/unpause · set-minter · set-primary-payee).`,
+    Handy before/after owner ops (mint · pause/unpause · set-minter · set-primary-payee).
+    ${dim('state = what the CHAIN says. For who is SERVING it and how fresh that is, see `abx status`.')}`,
     predict: `
   ${bold('abx predict')} ${dim('— pre-compute a deploy address (read-only).')}
     --salt 0x..<64hex>    a fixed / vanity salt   --for 0x..   reserve to a deployer   --factory 0x..`,
@@ -4866,18 +5891,31 @@ 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.')}`,
+  ${bold('abx status')} [address] ${dim('— INDEXING status: where a project is in the lifecycle, and how fresh. Read-only.')}
+    ${dim('bare')}                  this node: chain · factory · storage · data dir, then one line per project
+    ${dim('<address>')}             one project in detail: lifecycle · scan floor · blocks indexed vs head · why, if unhappy
+    ${g('--remote')} [name|url]    ask a SERVICE instead (your hosted node, or a managed provider) — same five words
+    ${g('--watch')}               poll until everything reaches a terminal state (${g('live')} or ${c.orange}failed${c.reset})
+    lifecycle: ${dim('queued')} → ${dim('backfilling')} → ${g('live')}  ·  ${c.orange}stale${c.reset} ${dim('(was live, now lagging — still serving)')}  ·  ${c.orange}failed${c.reset} ${dim('(carries a cause; retried with backoff)')}
+    ${dim('status = who is SERVING it and how fresh. For what the CHAIN says (owner, royalty, locks), see `abx state`.')}`,
     storage: `
   ${bold('abx storage')} <show|upload|balance|topup|backup-key> ${dim('— inspect / operate byte custody. Mostly read-only.')}
     ${g('show')}                  the resolved backend (fs | cloud | ipfs | arweave) + where each value came from
     ${g('upload')} <path>         upload ONE file → prints its locator (the URI ${g('abx attach')} wants)   [--backend …] [--dry-run]
     ${g('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)')}
@@ -4892,13 +5930,20 @@ const COMMAND_HELP = {
   ${bold('abx add')} <address> ${dim('— register + index a project. Also edits off-chain display metadata + traits.')}
     --from-block <n> --factory 0x.. --label "<s>" --description "<s>" --external-url <url> [--full] [--yes]
     --traits "K=V; K2=V2" / --attributes <file.json>   set the off-chain operator traits (on-chain attributes always win)
-    ${g('--remote [url]')}   target a HOSTED resolver instead of this machine — bridges the image locator (ipfs://…) + traits to it`,
+    ${g('--remote [name|url]')}  target a REMOTE resolver instead of this machine — bridges the image locator (ipfs://…) + traits to it.
+                          A ${bold('name')} reads ${g('ABX_REMOTE_<NAME>_URL')} + ${g('ABX_REMOTE_<NAME>_TOKEN')} from .env (a managed provider's API key);
+                          a URL (or bare --remote = ${g('ABX_PUBLIC_BASE_URL')}) uses ${g('ABX_RESOLVER_ADMIN_TOKEN')}. Inspect first: ${g('abx remote <name>')}
+    --remote-token <t>    override the token for this invocation (--token means a token ID elsewhere, hence the name)
+    ${g('--no-wait')}             ${dim('with --remote: return as soon as the service accepts it, instead of waiting out its catch-up.')}
+                          ${dim('A service may answer "accepted, still indexing" (202) for a long backfill; by default abx polls')}
+                          ${dim('to')} ${g('live')} ${dim('and prints the same summary. The registration is durable either way —')} ${g('abx status <addr> --remote')} ${dim('checks later.')}`,
     index: `
   ${bold('abx index')} [<address>] ${dim('— re-index from chain (read-only). Incremental by default.')}
-    ${g('--full')}   force a full replay from the deploy block (the durability proof)   --yes   allow a very large scan`,
+    ${g('--full')}   force a full replay from the deploy block (the durability proof)   --yes   allow a very large scan
+    ${g('--remote [name|url]')}  re-index on a REMOTE resolver (the post-deploy nudge)   ${g('--no-wait')}  don't wait out a deferred catch-up`,
     verify: `
   ${bold('abx verify')} <address> ${dim('— re-hash the served bytes against the on-chain commitment (read-only; no server).')}
-    ${g('--remote [url]')}       verify what a HOSTED resolver actually serves (else ABX_PUBLIC_BASE_URL) — probes its \`/image\` (302→locator
+    ${g('--remote [name|url]')}  verify what a REMOTE resolver actually serves (else ABX_PUBLIC_BASE_URL) — probes its \`/image\` (302→locator
                           or 200 bytes), so it accounts for a render PUBLISHED to that resolver. ${bold('Use this for a code project whose')}
                           ${bold('renders were published to a hosted resolver')} — a plain \`abx verify\` only checks THIS machine's store and will
                           report a false placeholder for a render that lives on the resolver.
@@ -4908,11 +5953,21 @@ const COMMAND_HELP = {
   ${bold('abx tokenuri')} <address> [--token <id>] ${dim('— read tokenURI(id) straight from the contract on-chain + decode the JSON (read-only; no server).')}
     ${dim('The proof a fully on-chain token self-resolves: any RPC returns the renderer-assembled metadata. Default token 0.')}`,
     forget: `
-  ${bold('abx forget')} <address> ${dim('— drop a project’s local registration + projection. On-chain data is untouched.')}`,
+  ${bold('abx forget')} <address> ${dim('— drop a project’s local registration + projection. On-chain data is untouched.')}
+    ${g('--remote [name|url]')}  deregister on a REMOTE resolver instead (it stops serving the project; re-add any time)`,
+    remote: `
+  ${bold('abx remote')} [<name|url>] ${dim('— inspect a remote service (read-only; registers nothing).')}
+    Bare: list the named remotes in .env (${g('ABX_REMOTE_<NAME>_URL')} / ${g('_TOKEN')} — token shown as set/unset, never printed)
+    plus the self-host default (bare --remote = ${g('ABX_PUBLIC_BASE_URL')} + ${g('ABX_RESOLVER_ADMIN_TOKEN')}).
+    With a target: fetch its PUBLIC ${g('/.well-known/abx-service')} descriptor — what it serves (interfaces), which chains
+    (flags a mismatch with your ${g('ABX_CHAIN')}), whether ${bold('rendering is managed')} behind it (code drops then need no effects
+    runner), and where a human gets an API key (${g('auth.signupUrl')}). With a token: lists the projects visible to it —
+    ${bold('the one-command "is my provider key valid?" check')} (401 = fix the key · 403 = provider-side scoping, not a typo).`,
     migrate: `
   ${bold('abx migrate')} <address> ${dim('— move a contract\'s OFF-CHAIN state to another resolver (read-only on both; no cutover).')}
-    --from <url>          the SOURCE resolver (currently serving the contract)
-    --to <url>            the DESTINATION resolver (its admin control plane) — needs ${g('ABX_RESOLVER_ADMIN_TOKEN')} in .env (the dest's token, from ${g('deploy-resolver')})
+    --from <name|url>     the SOURCE resolver (currently serving the contract) — read via its PUBLIC api; no source credential needed
+    --to <name|url>       the DESTINATION resolver (its control plane) — the ONE credential migrate needs: a named remote's
+                          ${g('ABX_REMOTE_<NAME>_TOKEN')}, else ${g('ABX_RESOLVER_ADMIN_TOKEN')} (your own node's, from ${g('deploy-resolver')}), else --remote-token
     --from-block <n>      chain scan floor for the local read (default: the deploy block, discovered on-chain — never genesis)   --yes   allow a very large scan
     --backend <id>        durable custody for re-pinning source-only images (ipfs · arweave); else config/env
     ${dim('replays on-chain state on the dest from chain, then bridges description / external_url / off-chain')}
@@ -4962,7 +6017,8 @@ function help() {
                             --minter 0x.. · --primary-payee 0x.. · --unpaused · ${g('--dry-run')}   ·   see ${g('abx help deploy-series')}
     ${g('abx predict')}             pre-compute a deploy address   flags: [--salt 0x..] [--for 0x..] [--factory 0x..]
     ${g('abx add')} <address>       register + index a project this node didn't deploy
-                            flags: --from-block --factory --label
+                            flags: --from-block --factory --label   ·   ${g('--remote <name|url>')} registers on a REMOTE resolver instead
+    ${g('abx remote')} [<name|url>]  inspect a remote service: its descriptor (chains · managed rendering · where to get a key) + your projects there
     ${g('abx index')} [<address>]   re-index from chain (incremental by default; ${g('--full')} forces a replay from deploy)
     ${g('abx verify')} <addr>       re-hash served bytes vs the on-chain commitment (no server needed)
     ${g('abx tokenuri')} <addr>     read tokenURI(0) on-chain + decode the JSON (proof a self-resolving token works)
@@ -4971,7 +6027,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) ·
@@ -5017,13 +6075,13 @@ function help() {
     ${g('abx storage')} topup       buy Turbo credits by card   --usd <n>   (one-time; <100 KB is always free)
     ${g('abx storage')} backup-key  copy the managed Turbo/Arweave key (holds credits) to a safe path   --out <path>
     ${g('abx forget')} <address>    drop a project's local registration + projection (on-chain untouched)
-    ${g('abx status')}              list indexed projects + node info
+    ${g('abx status')} [address]     indexing status: lifecycle + freshness (bare = this node; ${g('--remote')} [name] = a service; ${g('--watch')} to tail)
     ${g('abx doctor')}              check environment (key, RPC, balance, factory, storage)
-    ${g('abx skill install')}       install the abx agent skill into your agent   [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
+    ${g('abx skill install')}       install the version-locked abx skill into your agent(s)   [--agent <name>] [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
     ${g('abx version')}             print the installed CLI version
 
   ${dim('Run')} ${g('abx <command> --help')} ${dim('for per-command usage. --help / -h never executes — it only prints usage.')}
-  ${dim('abx checks npm for a newer release (once a day, notify-only). Silence with')} ${g('ABX_NO_UPDATE_CHECK=1')} ${dim('or')} ${g('--no-update-check')}${dim('.')}
+  ${dim('abx checks npm for a newer release (every 6h, notify-only). Silence with')} ${g('ABX_NO_UPDATE_CHECK=1')} ${dim('or')} ${g('--no-update-check')}${dim('.')}
 `);
 }
 /** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
@@ -5041,8 +6099,13 @@ function parseSaltFlag(raw) {
 // ── skill: install the abx agent skill into the user's coding agent ───────────────────────
 // The skill is the agentic half of the toolkit — the CLI is only useful once an agent knows how
 // to drive it. It ships bundled inside the published package (packages/cli/skill/, created at
-// prepack); in dev the same command reads the canonical copy straight from the repo. A separate
-// cross-agent channel is `npx skills add ArtBlocks/abx` (the Agent Skills standard, git-based).
+// prepack); in dev the same command reads the canonical copy straight from the repo. This is the
+// CANONICAL install path precisely because the bundle is version-locked to the CLI it ships inside
+// (the version lives in SKILL.md frontmatter — see update-check.ts). By default it writes to BOTH
+// `.claude/skills` (Claude Code) and the neutral `.agents/skills` (Cursor · Codex · Gemini ·
+// Copilot all read it), so one command covers the whole ecosystem; `--agent` narrows it. A separate
+// git-based channel, `npx skills add ArtBlocks/abx --skill abx-self-host`, works once the repo is public but is NOT
+// version-locked to a local CLI — prefer `abx skill install`.
 /** 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() {
@@ -5106,37 +6169,86 @@ function cmdScaffoldRenderer(rest, flags) {
     console.log(`    ${g('abx deploy-code --image-renderer <MyRenderer> --attributes-renderer <MyTraits> --onchain-uri --schema palette:HexColor:TokenOwner --name "…" --symbol …')}`);
     info(`full walkthrough: ${bold(`${basename(dir)}/README.md`)} · interface + invariants: https://abx.docs.artblocks.io/protocol/renderers/`);
 }
+/** Human label for each skills-parent dir — which agents pick the skill up from there. */
+const SKILL_PARENT_LABELS = {
+    '.claude/skills': 'Claude Code',
+    '.agents/skills': 'Cursor · Codex · Gemini · Copilot',
+};
+/** Resolve which skills-parent dirs `install` should write to. No `--agent` → the whole-ecosystem
+ *  default (Claude Code + the neutral `.agents/skills` everyone else reads). `--agent a,b` narrows
+ *  to those agents' dirs (de-duped, since several share `.agents/skills`). */
+function resolveInstallParents(agentFlag) {
+    if (!agentFlag || agentFlag === 'true')
+        return ['.claude/skills', '.agents/skills'];
+    const parents = new Set();
+    for (const raw of agentFlag.split(',')) {
+        const a = raw.trim().toLowerCase();
+        const parent = AGENT_SKILL_PARENTS[a];
+        if (!parent) {
+            throw new Error(`unknown --agent '${a}'. Use one of: ${Object.keys(AGENT_SKILL_PARENTS).join(', ')} (or omit --agent to install for every agent).`);
+        }
+        parents.add(parent);
+    }
+    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. */
+function installSkillTo(src, dest) {
+    mkdirSync(joinPath(dest, '..'), { recursive: true });
+    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();
     if (!src) {
         throw new Error('bundled skill not found (expected <pkg>/skill or .claude/skills/abx-self-host). ' +
-            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx');
+            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx --skill abx-self-host');
     }
     if (sub === 'path') {
         console.log(src);
         return;
     }
     if (sub === 'install') {
-        const base = flags.global !== undefined ? homedir() : flags.target ?? process.cwd();
-        const destParent = joinPath(base, '.claude', 'skills');
-        const dest = joinPath(destParent, 'abx-self-host');
-        mkdirSync(destParent, { recursive: true });
-        cpSync(src, dest, { recursive: true });
-        // Stamp the CLI version so a later run can notice the skill has drifted behind an upgraded CLI
-        // (the two are co-versioned). Best-effort — a missing marker just means "no drift nudge".
-        try {
-            writeFileSync(joinPath(dest, SKILL_VERSION_MARKER), readCliVersion());
-        }
-        catch {
-            /* non-fatal */
+        const version = readSkillVersion(joinPath(src, 'SKILL.md')) ?? readCliVersion();
+        // Escape hatch: --target <dir> writes the skill folder straight under <dir> (for an agent
+        // 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);
+            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;
         }
-        ok(`installed the abx skill → ${dest}`);
-        info('restart your agent (Claude Code / Cursor) so it loads the skill, then ask it to launch an NFT with abx.');
-        info('cross-agent alternative (git-based): npx skills add ArtBlocks/abx');
+        installSkillToDefaults(src, { global: flags.global !== undefined, agent: flags.agent });
         return;
     }
-    throw new Error('usage: abx skill <install|path> [--global] [--target <dir>]');
+    throw new Error('usage: abx skill <install|path> [--agent claude|cursor|codex|gemini|copilot] [--global] [--target <dir>]');
 }
 main().catch((err) => {
     // Keep the actionable message; strip viem's verbose boilerplate trailer (Docs:/Version: lines) so