@artblocks/abx-cli 0.1.0-alpha.8 → 0.1.0-alpha.9

package/dist/main.js

@@ -17,8 +17,9 @@
  *   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
@@ -70,13 +71,13 @@ 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, explorerUrl, 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, 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 } from './remote.js';
 import { buildMigrationPlan, repinNodeCustody, verifyParity } from './migrate.js';
 import { activeBackendId, arweaveKeyFilePath, backendResolution, ensureArweaveJwk, factoryAddress, seriesFactoryAddress, fixedPriceMinterAddress, loadArweaveJwk, loopbackBaseUrl, faucetHint, rendererAddress, storageOptions, storageSignerChoice, } from './config.js';
 const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY;
@@ -207,6 +208,7 @@ 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 'state': return cmdState(rest[0], flags);
@@ -223,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).
@@ -1010,23 +1071,20 @@ async function cmdDeploy(flags, serveAfter) {
         }
     }
     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;
@@ -1055,6 +1113,8 @@ async function cmdDeploy(flags, serveAfter) {
             return;
         }
         factory = existing;
+        if (!(await previewFactoryLive(publicClient, factory, 'factory')))
+            return;
         info(`would reuse canonical factory ${factory}`);
     }
     else {
@@ -1561,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)
@@ -1619,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 {
@@ -2080,18 +2136,11 @@ 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');
-    }
-    return base;
+// 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']);
 }
 /**
  * Ensure a resolver admin token exists locally, generating + persisting one to `.env`
@@ -2124,22 +2173,13 @@ 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);
     }
     // `--attributes` is lane-aware here exactly as at deploy: a PER-TOKEN payload edits a Series'
@@ -2153,10 +2193,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);
@@ -2165,7 +2205,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;
@@ -2191,6 +2231,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),
@@ -2202,12 +2243,18 @@ 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);
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject(body);
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote add');
+        }
         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`);
+        info(`it now serves ${remote.url}/t/${body.chainId}/${address.toLowerCase()}/0`);
         return;
     }
     allowLargeScan(flags);
@@ -2790,17 +2837,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)
@@ -3641,7 +3678,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
@@ -3678,12 +3715,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.
@@ -3718,8 +3755,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.
@@ -3759,15 +3799,21 @@ 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 });
+        requireRemoteToken(remote);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(re-indexing on the remote resolver — the post-deploy nudge)')}`);
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject({ chainId: resolveChain(CHAIN).id, address, full: flags.full ? true : undefined });
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote index');
+        }
         ok(`remote resolver re-indexed ${r.project.name ?? address}: ${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
         return;
     }
@@ -3798,9 +3844,9 @@ async function cmdVerify(address, flags) {
         process.exit(1);
     }
     allowLargeScan(flags);
-    const remote = remoteTarget(flags);
+    const remote = remoteFlag(flags);
     if (remote)
-        return cmdVerifyRemote(address, remote);
+        return cmdVerifyRemote(address, remote.url);
     const indexer = new SelfHostIndexer();
     let state = indexer.getProject(address);
     if (indexer.store.getRegistration(address)) {
@@ -4072,7 +4118,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`);
@@ -4415,15 +4466,24 @@ async function cmdStatus() {
 // 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();
@@ -4434,6 +4494,94 @@ 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)`)}`);
+        }
+        if (projects.length > 10)
+            console.log(dim(`    … and ${projects.length - 10} more`));
+    }
+    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
@@ -4442,13 +4590,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)')}`));
@@ -4505,6 +4657,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).
@@ -4517,8 +4670,14 @@ 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);
+    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');
+    }
     ok(`destination indexed ${r.project.name ?? address}: ${r.project.eventCount} events ${dim(`(${r.mode}, ${r.elapsedMs}ms)`)}`);
     // 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
@@ -4854,7 +5013,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) ─────
@@ -5153,8 +5313,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.`)}
@@ -5170,8 +5331,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.')}
@@ -5182,7 +5343,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.
@@ -5366,13 +5527,16 @@ 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)`,
     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`,
     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.
@@ -5382,11 +5546,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')}
@@ -5436,7 +5610,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)