@feralfile/cli 2.10.1 → 3.0.0

package/README.md

@@ -26,7 +26,8 @@ npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-ch
 ```bash
 ff-cli setup
 ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
-ff-cli play "https://example.com/video.mp4" --skip-verify
+ff-cli play "https://example.com/video.mp4"
+ff-cli play "https://example.com/"          # any web page
 ```
 
 If you need manual config actions instead of guided setup:
@@ -41,9 +42,9 @@ ff-cli config validate
 `ff-cli setup` is fully scriptable — no TTY required. It runs non-interactively when stdin is not a terminal, or when you pass `-y/--non-interactive`, and takes flags for every step:
 
 ```bash
-# Generate a signing key and register a device in one shot, no prompts
+# Register a device, no prompts. Generates a signing key only when none is configured,
+# and keeps one that is.
 ff-cli setup --non-interactive \
-  --generate-key \
   --device-host http://192.168.1.50:1111 \
   --device-name "Living Room"
 
@@ -51,6 +52,10 @@ ff-cli setup --non-interactive \
 ff-cli setup -y --key "<private-key>" --role agent
 ```
 
+`--generate-key`, `--key`, and `--key-file` refuse to replace a signing key that is already configured, because that key owns the playlists you published. Add `--force` only when you mean to replace it.
+
+Without a terminal, `find` needs `-y` (it plays by default; add `--no-play` to only save). A question with no terminal to answer it exits 1 and names the flag.
+
 Device pairing is also scriptable on its own: `ff-cli device add --host http://<ip>:1111 --name <name>` skips mDNS discovery entirely.
 
 ## Find an artwork
@@ -75,18 +80,18 @@ Sources: Art Blocks, Objkt, fxhash (canonical `/gentk/...`, live `/iteration/{sl
 
 **Known limitations**
 
-- **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)).
+- **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)). The opt-in Raster token source resolves them.
 - **Mainstream PFPs** (Azuki, BAYC, Pudgy Penguins) build a single-item playlist instead of a series — Raster's curation is effectively the series allowlist.
 - **Indexer 502s on burst load** are intermittent ([ff-indexer-v2#82](https://github.com/feral-file/ff-indexer-v2/issues/82)) — retry clears or use `--limit N`.
+- **The Raster token source is opt-in and under evaluation** (`tokenSource: "raster"`). It cannot list a contract, its Feral File metadata is a snapshot (an evolving work plays the version Raster recorded), and some Feral File works point at a retired image host and play black. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#tokensource).
 
 ## Use with Claude Code
 
 ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) skill at `skills/ff-control/SKILL.md`. Install it once:
 
 ```bash
-git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
-  && mkdir -p ~/.claude/skills \
-  && cp -r /tmp/ff-cli/skills/ff-control ~/.claude/skills/
+d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d" \
+  && mkdir -p ~/.claude/skills && cp -r "$d/skills/ff-control" ~/.claude/skills/
 ```
 
 Claude Code will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
@@ -96,9 +101,8 @@ Claude Code will surface it when you ask to build a playlist, play an artwork or
 ff-cli ships the same `ff-control` skill in Codex's native skill format. Install it once:
 
 ```bash
-git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
-  && mkdir -p ~/.codex/skills \
-  && cp -r /tmp/ff-cli/skills/ff-control ~/.codex/skills/
+d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d" \
+  && mkdir -p ~/.codex/skills && cp -r "$d/skills/ff-control" ~/.codex/skills/
 ```
 
 Codex will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
@@ -109,8 +113,9 @@ Codex will surface it when you ask to build a playlist, play an artwork or URL o
 npm ci
 npm run dev -- setup
 npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
-npm run dev -- play "https://example.com/video.mp4" --skip-verify
+npm run dev -- play "https://example.com/video.mp4"
 ```
+
 ## Documentation
 
 - Getting started and usage: `./docs/README.md`

package/config.json.example

@@ -18,6 +18,11 @@
     "role": "curator",
     "curatorName": "YOUR_CURATOR_NAME"
   },
+  "tokenSource": "indexer",
+  "ipfsGateways": {
+    "feralFile": "https://ipfs.feralfile.com/ipfs/",
+    "default": "https://ipfs.filebase.io/ipfs/"
+  },
   "ff1Relayer": {
     "baseUrl": "https://tv-cast-coordination.autonomy-system.workers.dev"
   },

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.10.1",
+    "version": "3.0.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",

package/dist/src/commands/build.js

@@ -8,11 +8,43 @@ const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
 const main_1 = require("../main");
+/**
+ * BUILD_PARAMS_HELP documents the params file in `build --help`.
+ *
+ * The schema used to live only in docs/README.md and the agent skill, so a
+ * caller working from `--help` (the first thing an agent reads) had to guess
+ * requirement types. Keep it in step with validateRequirements in src/main.ts.
+ */
+const BUILD_PARAMS_HELP = `
+Params (JSON file, or piped on stdin):
+  {"requirements": [ ...one or more... ], "playlistSettings": { ... }}
+
+Requirement types:
+  query_address       What a wallet owns. ownerAddress (0x… or tz…), optional quantity (number up to 100, or "all").
+                      {"type":"query_address","ownerAddress":"0x…","quantity":5}
+  build_playlist      Tokens from a contract. blockchain ("ethereum" or "tezos"), contractAddress, tokenIds.
+                      {"type":"build_playlist","blockchain":"ethereum","contractAddress":"0x…","tokenIds":["1","2"]}
+  fetch_feed          A feed playlist by title. playlistName, optional quantity.
+                      {"type":"fetch_feed","playlistName":"Unsupervised","quantity":3}
+  feral_file_artwork  One Feral File artwork. artworkId (public id or /exhibitions/artwork/{id} URL).
+
+playlistSettings (all optional):
+  title, durationPerItem (seconds), preserveOrder (default true; false shuffles),
+  deviceName (play on that FF1 after building)
+
+Exit status: 1 when a requirement finds nothing or fails, when named tokenIds
+do not all resolve, or when the send to deviceName fails. The playlist is still
+saved when anything was collected.
+
+Example:
+  echo '{"requirements":[{"type":"query_address","ownerAddress":"0x…","quantity":5}],"playlistSettings":{"title":"My collection"}}' | ff-cli build -o wallet.json
+`;
 exports.buildCommand = new commander_1.Command('build')
     .description('Build playlist from structured parameters (JSON file or stdin)')
     .argument('[params-file]', 'Path to JSON parameters file (or use stdin)')
     .option('-o, --output <filename>', 'Output filename for the playlist', 'playlist.json')
     .option('-v, --verbose', 'Show detailed output', false)
+    .addHelpText('after', BUILD_PARAMS_HELP)
     .action(async (paramsFile, options) => {
     try {
         let params;
@@ -58,6 +90,14 @@ exports.buildCommand = new commander_1.Command('build')
             console.log(chalk_1.default.dim(`  Items: ${result.playlist.items?.length || 0}`));
             console.log(chalk_1.default.dim(`  Output: ${options.output}\n`));
         }
+        const failures = result?.failures ?? [];
+        if (failures.length > 0) {
+            console.error(chalk_1.default.red('Not everything you asked for happened:'));
+            for (const failure of failures) {
+                console.error(chalk_1.default.red(`  ${failure}`));
+            }
+            process.exit(1);
+        }
     }
     catch (error) {
         console.error(chalk_1.default.red('\nError:'), error.message);

package/dist/src/commands/config.js

@@ -26,6 +26,7 @@ exports.configCommand = new commander_1.Command('config')
             const config = (0, config_1.getConfig)();
             console.log(chalk_1.default.blue('\nCurrent configuration\n'));
             console.log(chalk_1.default.bold('Default duration:'), chalk_1.default.white(config.defaultDuration + 's'));
+            console.log(chalk_1.default.bold('Token source:'), chalk_1.default.white((0, config_1.getTokenSourceConfig)().source));
             // The effective list, numbered. `-s <index>` on publish, fetch, replace
             // and unpublish is an index into exactly this list — whichever of
             // config.feedServers, the legacy feed.baseURLs, FEED_BASE_URLS, or the

package/dist/src/commands/device.js

@@ -120,7 +120,7 @@ deviceCommand
     let prompt = null;
     const ask = async (question) => {
         if (!prompt) {
-            prompt = (0, prompt_1.createPrompt)();
+            prompt = (0, prompt_1.createPrompt)('Pass --host http://<device-ip>:1111 and --name <name> to add or update a device without questions.');
         }
         return prompt.ask(question);
     };

package/dist/src/commands/enrich.js

@@ -18,15 +18,14 @@ const playlist_verifier_1 = require("../utilities/playlist-verifier");
 // distinct output here, and treating it as in-place makes the stale-input guard below refuse a write
 // that was never unsafe. The signer's direct-write path needs the opposite predicate; see same-file.ts.
 const same_file_1 = require("../utilities/same-file");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { resolveTokenBatch } = require('../utilities/nft-indexer');
+const token_source_1 = require("../utilities/token-source");
 /**
  * writePlaylistAtomically replaces a file only once the new bytes are safely on
  * disk.
  *
  * The default destination is the input file, and a plain write truncates it
- * first. Enrichment runs after a lookup that can take minutes while the indexer
- * warms tokens, so the window between truncation and a complete write is a
+ * first. Enrichment runs after a network lookup that can be slow (minutes on
+ * the indexer, which warms unseen tokens), so the window between truncation and a complete write is a
  * window in which an interruption, a full disk, or an I/O error leaves the
  * curator with an empty or half-written playlist and no copy of what they had.
  * A rename within the same directory is atomic, so the original file survives
@@ -295,10 +294,10 @@ const SKIP_COPY = {
     'external-ref': 'carries an external ref, which outranks an inline manifest',
     'no-provenance': 'no provenance.contract chain/address/tokenId to look up',
     'ambiguous-chain': 'chain "evm" names a family; pass --assume-ethereum to assert the network',
-    // The indexer drops unresolved tokens from its response rather than
-    // reporting why, so there is no per-item reason to relay here.
-    'not-indexed': 'the indexer returned nothing for it',
-    'no-metadata': 'the indexer resolved it but has no artist, description, or still image',
+    // The lookup adapter keeps only resolved tokens, so there is no per-item
+    // reason to relay here.
+    'not-indexed': 'the token source returned nothing for it',
+    'no-metadata': 'the token source resolved it but has no artist, description, or still image',
 };
 exports.enrichCommand = new commander_1.Command('enrich')
     .description('Add missing artist, title, and thumbnail metadata to a playlist')
@@ -322,7 +321,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
             console.error(chalk_1.default.red('That playlist has no items.'));
             process.exit(1);
         }
-        // Validate before spending minutes on indexer lookups for a document
+        // Validate before spending time on token lookups for a document
         // that was never going to be writable.
         const before = await (0, playlist_verifier_1.validatePlaylist)(playlist);
         if (!before.valid) {
@@ -335,20 +334,16 @@ exports.enrichCommand = new commander_1.Command('enrich')
             printedProgress = true;
             process.stdout.write(chalk_1.default.dim(`\r  ${done}/${count} looked up...`));
         };
-        // resolveTokenBatch is (tokens, duration, onProgress) — the second
-        // positional is DP-1 display seconds, not the callback. Enrichment never
-        // sets duration (the curator's timing is not ours to touch), so it is
-        // passed undefined and the callback goes third. find.ts carries the same
-        // warning; getting this wrong silently returns unusable results.
-        //
-        // The raw results are used rather than getNFTTokenInfoBatch's items so
-        // the indexer's still rides beside each item: the item itself drops the
-        // still whenever it equals the indexer's chosen source, and enrichment
+        // Enrichment never sets duration (the curator's timing is not ours to
+        // touch). The raw results are used rather than bare items so the token
+        // source's still rides beside each item: the item itself drops the still
+        // whenever it equals the source the token source chose, and enrichment
         // needs it against the curator's source instead.
+        const source = (0, token_source_1.getTokenSource)();
         const lookup = async (tokens, onProgressCallback) => {
-            const results = await resolveTokenBatch(tokens, undefined, onProgressCallback);
+            const results = await source.resolveTokens(tokens, { onProgress: onProgressCallback });
             return results
-                .filter((result) => result.success && result.item)
+                .filter(token_source_1.isResolved)
                 .map((result) => ({ ...result.item, still: result.still }));
         };
         const result = await (0, enrich_playlist_1.enrichPlaylistManifests)(playlist, lookup, {
@@ -375,7 +370,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
         if (shouldWrite) {
             // Re-validate the enriched candidate. An inline manifest is schema-
             // checked the same way a fetched one is (playlists extension §3.6), so
-            // a malformed manifest from the indexer must not reach the file.
+            // a malformed manifest from the token source must not reach the file.
             const after = await (0, playlist_verifier_1.validatePlaylist)(result.playlist);
             if (!after.valid) {
                 reportInvalid('Enrichment produced an invalid playlist:', after);

package/dist/src/commands/find.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCommand = void 0;
-exports.buildRasterMediaItems = buildRasterMediaItems;
 exports.parseLimitOption = parseLimitOption;
 exports.decideActions = decideActions;
 const commander_1 = require("commander");
@@ -22,9 +21,10 @@ const neort_marketplace_1 = require("../utilities/neort-marketplace");
 const verse_marketplace_1 = require("../utilities/verse-marketplace");
 const raster_client_1 = require("../utilities/raster-client");
 const playlist_cast_1 = require("../utilities/playlist-cast");
-// nft-indexer + playlist-builder are still CommonJS; require keeps interop simple.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
+const token_source_1 = require("../utilities/token-source");
+const token_source_raster_1 = require("../utilities/token-source-raster");
+const config_1 = require("../config");
+// playlist-builder is still CommonJS; require keeps interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { buildDP1Playlist, buildUrlItem } = require('../utilities/playlist-builder');
 /**
@@ -35,9 +35,26 @@ const { buildDP1Playlist, buildUrlItem } = require('../utilities/playlist-builde
  */
 const DP1_MAX_ITEMS = 1024;
 const RASTER_PAGE_SIZE = 100;
+/**
+ * FIND_NON_INTERACTIVE_HINT is what `find` tells a caller without a terminal
+ * when one of its questions comes up. `-y` answers every question with its
+ * default, and that default is Play, so the hint names `--no-play` in the same
+ * breath for a caller that only wants the file.
+ */
+const FIND_NON_INTERACTIVE_HINT = 'Re-run with -y to accept the defaults (it builds the playlist and plays it on your FF1); add --no-play to only save it.';
+/**
+ * playAPageHint points a caller who handed `find` a page it cannot resolve to
+ * the command that shows a page as it is.
+ *
+ * @param {string} input - The URL the caller gave `find`
+ * @returns {string} One line naming `ff-cli play --web`
+ */
+function playAPageHint(input) {
+    return `To show this page itself on your FF1, run: ff-cli play --web "${input}"`;
+}
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
-    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
+    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address (picks one work by the artist at that address; for what a wallet owns, see `ff-cli build --help`)')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
     .option('-p, --play', 'Play the playlist on an FF1 device after building')
@@ -56,6 +73,11 @@ exports.findCommand = new commander_1.Command('find')
             console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse, Raster. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
+            // A plain web page or media URL is not an artwork lookup at all; `play`
+            // casts those directly, so name it rather than leave the caller stuck.
+            if (/^https?:\/\//i.test(input.trim())) {
+                console.error(chalk_1.default.dim(`To play a web page or media URL as it is, run: ff-cli play "${input}"`));
+            }
             process.exit(1);
         }
         if (parsed.kind === 'unsupported') {
@@ -65,9 +87,12 @@ exports.findCommand = new commander_1.Command('find')
                 return;
             }
             console.error(chalk_1.default.red(parsed.reason));
+            // `play` sends unrecognized pages on these hosts here, so the way out
+            // of that loop has to be printed on this side too.
+            console.error(chalk_1.default.dim(playAPageHint(input)));
             process.exit(1);
         }
-        // Neort is off-chain; its items skip Raster + FF indexer entirely and
+        // Neort is off-chain; its items skip the token source entirely and
         // build a DP-1 entry directly from Neort's API response.
         if (parsed.kind === 'neort-art') {
             await runNeortFind(parsed.id, options);
@@ -113,14 +138,13 @@ async function runResolvedTarget(target, options) {
     else if (target.kind === 'token-list') {
         const allTokens = target.coords.map((coords) => ({
             ...coords,
-            mediaUrl: null,
-            mediaType: null,
+            rasterToken: null,
         }));
         tokens = allTokens.slice(0, limit);
         seriesHasMore = allTokens.length > limit || !!target.hasMore;
     }
     else {
-        tokens = [{ ...target.coords, mediaUrl: null, mediaType: null }];
+        tokens = [{ ...target.coords, rasterToken: null }];
     }
     if (tokens.length === 0) {
         console.error(chalk_1.default.red('Series has no tokens on supported chains (Ethereum + Tezos mainnet).'));
@@ -136,48 +160,21 @@ async function runResolvedTarget(target, options) {
         console.log(chalk_1.default.dim('Cancelled.'));
         return;
     }
-    console.log(chalk_1.default.dim(`Indexing ${tokens.length} token${tokens.length === 1 ? '' : 's'} via FF indexer...`));
-    // Previously-unseen tokens make the indexer warm renditions by polling —
-    // minutes of wall time on a large series. Say so upfront (the --limit
-    // warming hint used to appear only after a failure) and render per-batch
-    // progress so a long index never reads as a hang.
-    if (tokens.length > 10) {
+    const source = (0, token_source_1.getTokenSource)();
+    const label = source.name === 'raster' ? 'Raster' : 'FF indexer';
+    console.log(chalk_1.default.dim(`Resolving ${tokens.length} token${tokens.length === 1 ? '' : 's'} via ${label}...`));
+    // The indexer warms previously-unseen tokens by polling, which
+    // takes minutes on a large series; Raster answers from its own index.
+    if (source.name === 'indexer' && tokens.length > 10) {
         console.log(chalk_1.default.dim('  First-time tokens can take the indexer a while to warm; use `--limit 5` for a faster first pass.'));
     }
-    // Second positional arg on getNFTTokenInfoBatch is `duration` (DP-1 item
-    // display seconds), not concurrency — concurrency is hardcoded inside.
-    // Omit it for auto timing: video/audio items carry no duration and play
-    // their natural length (DP-1 §4.1); static items get the config default.
-    let items = await getNFTTokenInfoBatch(tokens.map((t) => ({
-        chain: t.chain,
-        contractAddress: t.contract,
-        tokenId: t.tokenId,
-    })), undefined, 
-    // Unconditional: suppressing the done===total call meant a one-batch
-    // index (including the recommended --limit 5 warm-up) printed nothing
-    // and multi-batch runs never showed completion. The final N/N line IS
-    // the "indexing finished" signal.
-    (done, total) => {
-        console.log(chalk_1.default.dim(`  ${done}/${total} tokens indexed...`));
-    });
-    // FF-indexer bypass for Raster-minted tokens. The indexer doesn't carry
-    // Raster's tokens, so it returns nothing — but Raster handed us each
-    // token's playable `media.contentUrl`. Build DP-1 items straight from
-    // that (off-chain provenance, same shape as the Neort path), so the
-    // series still builds into a signable, verifiable playlist instead of
-    // failing the way it did before. The indexer is tried first so tokens
-    // it *can* resolve keep their richer on-chain provenance.
-    if (!Array.isArray(items) || items.length === 0) {
-        const rasterItems = buildRasterMediaItems(tokens, target);
-        if (rasterItems.length > 0) {
-            console.log(chalk_1.default.dim(`  FF indexer returned nothing; building ${rasterItems.length} item${rasterItems.length === 1 ? '' : 's'} directly from Raster media.`));
-            items = rasterItems;
+    const results = await resolveBuildTokens(source, tokens);
+    const items = (0, token_source_1.itemsOf)(results);
+    if (items.length === 0) {
+        console.error(chalk_1.default.red(`No tokens could be resolved via ${label}; cannot build playlist.`));
+        for (const message of (0, token_source_1.failureMessages)(results)) {
+            console.error(chalk_1.default.dim(`  ${message}`));
         }
-    }
-    if (!Array.isArray(items) || items.length === 0) {
-        console.error(chalk_1.default.red('No tokens could be indexed; cannot build playlist.'));
-        console.error(chalk_1.default.dim('  The FF indexer may be under load when warming a series of previously-unseen tokens.'));
-        console.error(chalk_1.default.dim('  Try `--limit 5` first to warm the cache, then re-run without --limit.'));
         process.exit(1);
     }
     const title = playlistTitleFor(target, items);
@@ -188,7 +185,10 @@ async function runResolvedTarget(target, options) {
     console.log(chalk_1.default.dim(`  ${items.length} item${items.length === 1 ? '' : 's'}`));
     const dropped = tokens.length - items.length;
     if (dropped > 0) {
-        console.log(chalk_1.default.dim(`  ${dropped} token${dropped === 1 ? '' : 's'} dropped during indexing`));
+        console.log(chalk_1.default.dim(`  ${dropped} token${dropped === 1 ? '' : 's'} could not be resolved:`));
+        for (const message of (0, token_source_1.failureMessages)(results)) {
+            console.log(chalk_1.default.dim(`    ${message}`));
+        }
     }
     console.log();
     const actions = await decideActions(options);
@@ -279,6 +279,11 @@ async function resolveTarget(input, parsed, skipPrompt, limitOption) {
         if (catalog.length === 0) {
             throw new Error('Artist has no artworks indexed on Raster.');
         }
+        // A wallet address reads naturally as "what this wallet owns", and this
+        // path builds something else: one work by the artist at the address. Say
+        // so every time, so neither a person nor an agent mistakes the result.
+        console.log(chalk_1.default.dim('find on an address plays one work by the artist at that address. ' +
+            'For what the wallet owns, use build with a query_address requirement (ff-cli build --help).'));
         const picked = await pickFromCatalog(catalog, skipPrompt);
         return {
             kind: 'series',
@@ -345,7 +350,7 @@ async function resolveCoords(coords) {
 }
 /**
  * Build the playlist title. For series, "Artist — Series Title". For a
- * one-item fallback, use the indexer's token name (already in the item)
+ * one-item fallback, use the token source's name (already in the item)
  * with a fall-through to coords if name is missing.
  */
 function playlistTitleFor(target, items) {
@@ -359,30 +364,30 @@ function playlistTitleFor(target, items) {
     return items[0]?.title ?? `Token ${target.coords.tokenId}`;
 }
 /**
- * Build DP-1 items directly from Raster's per-token media, bypassing the FF
- * indexer. Used as a fallback when the indexer resolves nothing — tokens
- * without a Raster `mediaUrl` are dropped (nothing playable to point at).
+ * resolveBuildTokens turns the tokens to build into results, one per token.
  *
- * Item shape matches the Neort off-chain path (`buildUrlItem` →
- * `provenance.offChainURI`), so the resulting playlist signs and verifies
- * normally. Titles are "<Series> #<tokenId>" for series, falling back to the
- * series/coords title for a single token.
+ * When every token already carries its Raster row (a Raster series page) and
+ * Raster is the token source, the rows are mapped directly: the page already
+ * paid for every field, so asking again would double the requests. Any other
+ * mix goes through the token source by coordinate.
  */
-function buildRasterMediaItems(tokens, target) {
-    const seriesTitle = target.kind === 'series' ? target.summary.title : undefined;
-    const items = [];
-    for (const t of tokens) {
-        if (!t.mediaUrl) {
-            continue;
-        }
-        const title = seriesTitle ? `${seriesTitle} #${t.tokenId}` : `Token ${t.tokenId}`;
-        // No explicit duration: auto timing (video/audio play their natural
-        // length). `mediaType` carries Raster's type so an extensionless IPFS
-        // contentUrl is still classified correctly — otherwise a video would be
-        // stamped a fixed duration and play as a still.
-        items.push(buildUrlItem(t.mediaUrl, undefined, { title, mimeType: t.mediaType ?? undefined }));
-    }
-    return items;
+async function resolveBuildTokens(source, tokens) {
+    const rows = tokens.map((t) => t.rasterToken);
+    if (source.name === 'raster' && rows.every((row) => row !== null)) {
+        const entries = tokens.map((t, i) => ({ token: rows[i], requested: coordinateOf(t) }));
+        return (0, token_source_raster_1.itemsFromRasterTokens)(entries, (0, config_1.getTokenSourceConfig)().ipfsGateways);
+    }
+    // Unconditional progress: the final N/N line IS the "resolution finished"
+    // signal, including for a single-batch run.
+    return source.resolveTokens(tokens.map(coordinateOf), {
+        onProgress: (done, total) => {
+            console.log(chalk_1.default.dim(`  ${done}/${total} tokens resolved...`));
+        },
+    });
+}
+/** coordinateOf converts a find token to the token source's coordinate shape. */
+function coordinateOf(token) {
+    return { chain: token.chain, contractAddress: token.contract, tokenId: token.tokenId };
 }
 function parseLimitOption(limitStr) {
     if (limitStr === undefined) {
@@ -425,8 +430,7 @@ async function fetchTokens(summary, limit) {
                 chain: t.chain,
                 contract: t.contractAddress,
                 tokenId: t.tokenId,
-                mediaUrl: t.mediaUrl,
-                mediaType: t.mediaType,
+                rasterToken: t.token,
             });
         }
         if (hasMore || page.nextCursor === null) {
@@ -439,7 +443,7 @@ async function fetchTokens(summary, limit) {
         cursor = page.nextCursor;
     }
     if (skipped > 0) {
-        console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (FF indexer covers eth + tezos mainnet only).`));
+        console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (ff-cli builds Ethereum and Tezos mainnet only).`));
     }
     return { tokens: collected, hasMore };
 }
@@ -452,7 +456,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
         console.log(chalk_1.default.dim(`  ${i}: ${row.title}`));
     });
     console.log();
-    const prompt = (0, prompt_1.createPrompt)();
+    const prompt = (0, prompt_1.createPrompt)(FIND_NON_INTERACTIVE_HINT);
     const answer = await prompt.ask(`Pick one (0-${catalog.length - 1}, default 0): `);
     prompt.close();
     console.log();
@@ -467,7 +471,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
 async function confirmMakePlaylist(count, hasMore) {
     const noun = count === 1 ? 'token' : 'tokens';
     const label = hasMore ? `the first ${count} ${noun}` : `${count} ${noun}`;
-    const prompt = (0, prompt_1.createPrompt)();
+    const prompt = (0, prompt_1.createPrompt)(FIND_NON_INTERACTIVE_HINT);
     const yes = await (0, prompt_1.promptYesNo)(prompt.ask, `Build playlist with ${label}?`, true);
     prompt.close();
     console.log();
@@ -510,7 +514,7 @@ async function decideActions(options) {
     return [await promptNextAction()];
 }
 async function promptNextAction() {
-    const prompt = (0, prompt_1.createPrompt)();
+    const prompt = (0, prompt_1.createPrompt)('The playlist is saved. Pass --play to cast it, or --publish to publish it.');
     const answer = (await prompt.ask('Next? [P]lay on FF1 / just [S]ave / pub[L]ish to feed (default: Play): '))
         .trim()
         .toLowerCase();
@@ -610,7 +614,7 @@ async function doPublish(savedPath, serverArg, nonInteractive) {
 }
 /**
  * Neort flow. Off-chain platform with no on-chain coords, so we bypass
- * Raster + FF indexer and construct a single-item DP-1 playlist directly
+ * the token source and construct a single-item DP-1 playlist directly
  * from Neort's API response using the off-chain `provenance.offChainURI`
  * shape produced by `buildUrlItem`.
  */