@feralfile/cli 2.5.0 → 2.6.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",
@@ -60,7 +60,7 @@
     "dependencies": {
         "@feralfile/source-resolver": "^1.0.0",
         "@napi-rs/keyring": "1.3.0",
-        "axios": "^1.6.2",
+        "axios": "^1.20.0",
         "bonjour-service": "^1.3.0",
         "chalk": "^4.1.2",
         "commander": "^11.1.0",
@@ -68,7 +68,7 @@
         "dp1-js": "2.3.1",
         "ff1": "^1.0.0",
         "fuzzysort": "^3.1.0",
-        "viem": "^2.38.2"
+        "viem": "^2.56.3"
     },
     "devDependencies": {
         "@types/node": "^24.7.1",

package/dist/src/commands/enrich.js

@@ -12,7 +12,7 @@ const path_1 = require("path");
 const enrich_playlist_1 = require("../utilities/enrich-playlist");
 const playlist_verifier_1 = require("../utilities/playlist-verifier");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
+const { resolveTokenBatch } = require('../utilities/nft-indexer');
 /**
  * writePlaylistAtomically replaces a file only once the new bytes are safely on
  * disk.
@@ -63,7 +63,16 @@ async function writePlaylistAtomically(destination, contents, expectedDigest) {
             // of it, or widen who can reach it. Carry the ownership across, and when
             // that is not permitted refuse the in-place replacement instead of
             // completing it with different access than the file had.
-            if (current && (current.uid !== process.getuid?.() || current.gid !== process.getgid?.())) {
+            //
+            // Only where POSIX identity exists. Windows has no getuid/getgid and
+            // reports uid and gid as 0 on every stat, so the comparison there would
+            // always "differ" and chown a file whose ownership never moved. (libuv
+            // makes fchown a no-op on Windows, so nothing would break — but the
+            // branch would be asserting something it cannot know.)
+            const uid = process.getuid?.();
+            const gid = process.getgid?.();
+            const canCompareOwnership = uid !== undefined && gid !== undefined;
+            if (current && canCompareOwnership && (current.uid !== uid || current.gid !== gid)) {
                 try {
                     await handle.chown(current.uid, current.gid);
                 }
@@ -230,12 +239,22 @@ exports.enrichCommand = new commander_1.Command('enrich')
             printedProgress = true;
             process.stdout.write(chalk_1.default.dim(`\r  ${done}/${count} looked up...`));
         };
-        // getNFTTokenInfoBatch is (tokens, duration, onProgress) — the second
+        // 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.
-        const lookup = (tokens, onProgressCallback) => getNFTTokenInfoBatch(tokens, undefined, onProgressCallback);
+        //
+        // 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
+        // needs it against the curator's source instead.
+        const lookup = async (tokens, onProgressCallback) => {
+            const results = await resolveTokenBatch(tokens, undefined, onProgressCallback);
+            return results
+                .filter((result) => result.success && result.item)
+                .map((result) => ({ ...result.item, still: result.still }));
+        };
         const result = await (0, enrich_playlist_1.enrichPlaylistManifests)(playlist, lookup, {
             force: options.force,
             assumeEthereum: options.assumeEthereum,

package/dist/src/utilities/enrich-playlist.js

@@ -129,7 +129,43 @@ function coordinateKeyOf(provenance) {
     if (token.length === 0) {
         return null;
     }
-    return `${canonicalChain(chain)}:${address.trim().toLowerCase()}:${token}`;
+    const canonical = canonicalChain(chain);
+    const standard = effectiveStandard(canonical, address, contract.standard);
+    return `${canonical}:${standard}:${address.trim().toLowerCase()}:${token}`;
+}
+/**
+ * Standards the indexer keys CIDs on. Mirrors CID_STANDARDS in nft-indexer.js.
+ */
+const CID_STANDARDS = new Set(['erc721', 'erc1155', 'fa2']);
+/**
+ * effectiveStandard names the standard a coordinate is looked up under, so the
+ * correlation key separates what the indexer separates.
+ *
+ * The indexer keys ERC-721 and ERC-1155 tokens at one address under different
+ * CIDs, so a hybrid contract can hold both standards at one token id. Two
+ * playlist items asserting different standards for one coordinate are two
+ * lookups, and each answer must reach only the item that asked for it.
+ *
+ * When the playlist asserts nothing the client detects, and this mirrors that
+ * detection (resolveTokenStandard in nft-indexer.js) so the request key and
+ * the key read off the response agree. The mirror is deliberate rather than
+ * an import: this module takes its lookup by injection and stays free of the
+ * indexer client. If the two ever drift, correlation fails closed — the item
+ * reports not-indexed — rather than attributing one token's metadata to
+ * another.
+ */
+function effectiveStandard(canonicalChainName, address, asserted) {
+    const normalized = typeof asserted === 'string' ? asserted.trim().toLowerCase() : '';
+    if (CID_STANDARDS.has(normalized)) {
+        return normalized;
+    }
+    if (canonicalChainName === 'tezos' || address.trim().startsWith('KT')) {
+        return 'fa2';
+    }
+    if (canonicalChainName === 'evm') {
+        return 'erc721';
+    }
+    return 'other';
 }
 /**
  * describeItem names an item for operator output, preferring its title.
@@ -160,14 +196,22 @@ function coordinateFor(item) {
         return null;
     }
     const normalized = chain.trim().toLowerCase();
-    return {
+    const coordinate = {
         chain: CHAIN_ALIASES[normalized] ?? normalized,
         contractAddress: address,
         tokenId: token,
     };
+    // Carried as written. The indexer client accepts the standards its CIDs
+    // are keyed on and falls back to detection for anything else, so an
+    // unexpected value costs nothing beyond the lookup it would have lost anyway.
+    const standard = contract.standard;
+    if (typeof standard === 'string' && standard.trim().length > 0) {
+        coordinate.standard = standard.trim().toLowerCase();
+    }
+    return coordinate;
 }
 /**
- * stillFromIndexerSource recovers a thumbnail the manifest builder suppressed.
+ * stillFor recovers a thumbnail the manifest builder suppressed.
  *
  * `resolveStillUri` blanks a still that equals the source it was given, on the
  * reasonable ground that pointing a thumbnail at the artwork itself adds
@@ -179,64 +223,26 @@ function coordinateFor(item) {
  * exists to repair: a live work the app cannot rasterize, whose grid tile
  * stays empty.
  *
- * Recovering it is the inverse of the suppression. When the indexer's source
- * differs from the item's and is an http(s) URL, that source IS the still that
- * was elided, so it becomes the thumbnail relative to the item's own source.
+ * Recovery is the same rule applied against the curator's source instead of
+ * the indexer's: the still the indexer names for the token (`resolved.still`,
+ * its `display.image_url`) is used whenever it differs from the item's own
+ * source. It is the same field `find` and `build` write into
+ * `thumbnails.default`, and it is taken on the indexer's word, as they take
+ * it. No guess is made from a URL's shape — the indexer's source is often a
+ * live rendition and its stills are often extensionless CDN URLs, so a
+ * suffix check gets both cases wrong — and a lookup that names no still
+ * leaves the item without one.
  */
-function stillFromIndexerSource(item, resolved) {
-    const indexerSource = typeof resolved.source === 'string' ? resolved.source.trim() : '';
+function stillFor(item, resolved) {
+    const still = typeof resolved.still === 'string' ? resolved.still.trim() : '';
     const itemSource = typeof item.source === 'string' ? item.source.trim() : '';
-    if (!indexerSource || indexerSource === itemSource) {
+    if (!still || still === itemSource) {
         return '';
     }
-    if (!indexerSource.startsWith('http://') && !indexerSource.startsWith('https://')) {
+    if (!still.startsWith('http://') && !still.startsWith('https://')) {
         return '';
     }
-    // The indexer's source is not necessarily a still. getBestMediaUrl prefers
-    // display.animation_url and media assets over display.image_url, so it is
-    // frequently a live HTML rendition — and writing one into the thumbnail slot
-    // is worse than leaving the slot empty: the grid still cannot rasterize it,
-    // and the item now claims a still it does not have.
-    //
-    // Only a URL that is demonstrably an image is used. The indexer exposes no
-    // separately identified still on the item this command receives, so the file
-    // extension is the evidence available; carrying a real image field through
-    // the batch result would be the better fix and belongs upstream.
-    return looksLikeImage(indexerSource) ? indexerSource : '';
-}
-/**
- * Media the app can draw a grid tile from, matching the types
- * playlist-builder.js already recognizes. SVG and video belong here: the app
- * rasterizes both, and excluding them left works with the empty tile this
- * command exists to remove. HTML is deliberately absent — an unrasterizable
- * page in the thumbnail slot is worse than an empty slot, because the item
- * then claims a still it does not have.
- */
-const RASTERIZABLE_EXTENSIONS = [
-    '.png',
-    '.jpg',
-    '.jpeg',
-    '.gif',
-    '.webp',
-    '.avif',
-    '.bmp',
-    '.svg',
-    '.mp4',
-    '.webm',
-];
-/**
- * looksLikeImage tests a URL's path extension, ignoring query and fragment.
- */
-function looksLikeImage(url) {
-    let pathname = url;
-    try {
-        pathname = new URL(url).pathname;
-    }
-    catch {
-        pathname = url.split('?')[0].split('#')[0];
-    }
-    const lower = pathname.toLowerCase();
-    return RASTERIZABLE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+    return still;
 }
 /**
  * hasThumbnail reports whether a manifest already carries a default still.
@@ -258,9 +264,10 @@ function hasThumbnail(manifest) {
  * thumbnails) is what enrichment exists to fetch and is taken as given.
  */
 function manifestFor(item, resolved) {
-    const still = stillFromIndexerSource(item, resolved);
+    const still = stillFor(item, resolved);
+    const curatorTitle = typeof item.title === 'string' ? item.title.trim() : '';
+    const resolvedTitle = typeof resolved.title === 'string' ? resolved.title.trim() : '';
     let manifest = resolved.inlineManifest;
-    let rekey = false;
     if (manifest && still && !hasThumbnail(manifest)) {
         manifest = {
             ...manifest,
@@ -269,30 +276,36 @@ function manifestFor(item, resolved) {
                 thumbnails: { default: { uri: still } },
             },
         };
-        rekey = true;
     }
-    else if (!manifest && still) {
-        // Nothing was emitted because the still was the only content the token
-        // had, and it had been suppressed. A thumbnail-only manifest is worth its
-        // payload in a way a title-only one is not: it is the difference between
-        // a grid tile and an empty square.
-        const synthesizedTitle = typeof item.title === 'string' ? item.title.trim() : '';
-        manifest = {
-            refVersion: '1.1.0',
-            id: derivedManifestId('', `${synthesizedTitle}\n${still}`),
-            created: MANIFEST_CREATED,
-            locale: 'en',
-            metadata: {
-                ...(synthesizedTitle ? { title: synthesizedTitle } : {}),
-                thumbnails: { default: { uri: still } },
-            },
-        };
+    else if (!manifest) {
+        // Nothing was emitted because the token had only a title, or only a still
+        // that was suppressed against the indexer's source. Either can still be
+        // worth a manifest here, for a reason `find` and `build` never meet: their
+        // items always carry the token's title, so a title-only manifest would
+        // repeat what the item already says. A curator's item may carry no title
+        // at all, and the tombstone then shows nothing — so a substantiated title
+        // is written when the item lacks one, and a still is written whenever
+        // there is one, because it is the difference between a grid tile and an
+        // empty square.
+        const synthesizedTitle = curatorTitle || resolvedTitle;
+        const titleWorthCarrying = !curatorTitle && resolvedTitle.length > 0;
+        if (still || titleWorthCarrying) {
+            manifest = {
+                refVersion: '1.1.0',
+                id: derivedManifestId('', `${synthesizedTitle}\n${still}`),
+                created: MANIFEST_CREATED,
+                locale: 'en',
+                metadata: {
+                    ...(synthesizedTitle ? { title: synthesizedTitle } : {}),
+                    ...(still ? { thumbnails: { default: { uri: still } } } : {}),
+                },
+            };
+        }
     }
     if (!manifest) {
         return undefined;
     }
     const metadata = manifest.metadata ?? {};
-    const curatorTitle = typeof item.title === 'string' ? item.title.trim() : '';
     const overrideTitle = curatorTitle.length > 0 && metadata.title !== curatorTitle;
     // The id is derived from the finished payload every time, not only when this
     // command changed something. The indexer keys its id on the token
@@ -304,10 +317,6 @@ function manifestFor(item, resolved) {
     //
     // The original id is folded in, so the result stays anchored to the token
     // rather than floating free of it, and stays deterministic across runs.
-    //
-    // `rekey` is read only to record that a thumbnail was recovered; the
-    // derivation below covers it either way.
-    void rekey;
     const finalMetadata = overrideTitle ? { ...metadata, title: curatorTitle } : metadata;
     return {
         ...manifest,

package/dist/src/utilities/nft-indexer.js

@@ -128,6 +128,33 @@ function detectTokenStandard(chain, contractAddress) {
     }
     return 'other';
 }
+/**
+ * Token standards the indexer keys CIDs on. An asserted standard outside this
+ * set says nothing the CID can carry, so detection decides instead.
+ */
+const CID_STANDARDS = new Set(['erc721', 'erc1155', 'fa2']);
+/**
+ * resolveTokenStandard picks the standard a CID is built with.
+ *
+ * detectTokenStandard cannot tell ERC-721 from ERC-1155 — it has only a chain
+ * and an address, and answers erc721 for every EVM contract. The indexer keys
+ * the two differently (`eip155:1:erc721:…` and `eip155:1:erc1155:…`), so an
+ * ERC-1155 token looked up by detection alone is simply never found. When the
+ * caller knows the standard — a DP-1 playlist carries it in
+ * `provenance.contract.standard` — that assertion wins.
+ *
+ * @param {string} chain - Blockchain network
+ * @param {string} contractAddress - Contract address
+ * @param {string} [asserted] - Standard the caller vouches for, if any
+ * @returns {string} Token standard for the CID
+ */
+function resolveTokenStandard(chain, contractAddress, asserted) {
+    const normalized = typeof asserted === 'string' ? asserted.trim().toLowerCase() : '';
+    if (CID_STANDARDS.has(normalized)) {
+        return normalized;
+    }
+    return detectTokenStandard(chain, contractAddress);
+}
 /**
  * Build CAIP-2 token CID for indexer v2
  *
@@ -137,15 +164,19 @@ function detectTokenStandard(chain, contractAddress) {
  * @param {string} chain - Blockchain network (ethereum, polygon, tezos, etc)
  * @param {string} contractAddress - Contract address
  * @param {string} tokenId - Token ID
+ * @param {string} [standard] - Asserted token standard; detected when omitted
  * @returns {string} Token CID in CAIP-2 format
  * @example
  * // Returns: eip155:1:erc721:0xabc123:456
  * const cid = buildTokenCID('ethereum', '0xabc123', '456');
  * @example
+ * // Returns: eip155:1:erc1155:0xabc123:456
+ * const cid = buildTokenCID('ethereum', '0xabc123', '456', 'erc1155');
+ * @example
  * // Returns: tezos:mainnet:fa2:KT1abc:789
  * const cid = buildTokenCID('tezos', 'KT1abc', '789');
  */
-function buildTokenCID(chain, contractAddress, tokenId) {
+function buildTokenCID(chain, contractAddress, tokenId, standard) {
     // Map chain names to CAIP-2 format (supports only Ethereum and Tezos)
     const caip2Map = {
         ethereum: 'eip155:1',
@@ -157,8 +188,8 @@ function buildTokenCID(chain, contractAddress, tokenId) {
     if (!caip2Chain) {
         throw new Error(`Unsupported chain: ${chain}. Only ethereum and tezos are supported.`);
     }
-    const standard = detectTokenStandard(chain, contractAddress);
-    return `${caip2Chain}:${standard}:${contractAddress}:${tokenId}`;
+    const resolvedStandard = resolveTokenStandard(chain, contractAddress, standard);
+    return `${caip2Chain}:${resolvedStandard}:${contractAddress}:${tokenId}`;
 }
 /**
  * Unified GraphQL query for tokens from indexer v2
@@ -319,9 +350,10 @@ function getBestMediaUrl(display = {}, mediaAssets = []) {
  *
  * @param {Object} indexerData - Token fields from indexer GraphQL
  * @param {string} chain - Blockchain network
+ * @param {string} [standard] - Asserted token standard; detected when omitted
  * @returns {Object} Standardized token data
  */
-function mapIndexerDataToStandardFormat(indexerData, chain) {
+function mapIndexerDataToStandardFormat(indexerData, chain, standard) {
     if (!indexerData) {
         return {
             success: false,
@@ -334,14 +366,14 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
     const artistName = extractArtistName(display.artists);
     const name = display.name || `Token #${indexerData.token_number}`;
     const description = display.description || '';
-    const standard = detectTokenStandard(chain, indexerData.contract_address);
+    const resolvedStandard = resolveTokenStandard(chain, indexerData.contract_address, standard);
     return {
         success: true,
         token: {
             chain,
             contractAddress: indexerData.contract_address,
             tokenId: indexerData.token_number,
-            standard,
+            standard: resolvedStandard,
             name,
             description,
             image: {
@@ -492,8 +524,34 @@ function convertToDP1Item(tokenData, duration) {
     return {
         success: true,
         item: dp1Item,
+        still: stillOf(token),
     };
 }
+/**
+ * stillOf names the token's still image as the indexer identifies it, or ''.
+ *
+ * This is `display.image_url`, the field the indexer reserves for a still and
+ * the same one `buildInlineManifestForToken` writes into `thumbnails.default`.
+ * It is returned beside the DP-1 item rather than inside it because the item
+ * only carries the still when it differs from the item's own source, and a
+ * consumer building a manifest against a *different* source (see
+ * enrich-playlist.ts) needs the still regardless. Nothing about the URL's
+ * shape is inspected: the indexer's word that it is an image is the evidence,
+ * and a suffix check would reject the extensionless CDN URLs it commonly
+ * returns.
+ *
+ * @param {Object} token - Token in the internal standard format
+ * @returns {string} http(s) still URL, or '' when the indexer named none
+ */
+function stillOf(token) {
+    const image = token.image;
+    // Only `thumbnail` qualifies. `image.url` is the media getBestMediaUrl
+    // selected as the source, which is the live rendition whenever one exists —
+    // exactly what must never land in a thumbnail slot.
+    const candidate = typeof image === 'string' ? image : typeof image === 'object' && image ? image.thumbnail : '';
+    const trimmed = String(candidate || '').trim();
+    return trimmed.startsWith('http://') || trimmed.startsWith('https://') ? trimmed : '';
+}
 /**
  * Get NFT token information from indexer and return as DP1 item (supports single or batch)
  * @param {Object|Array} params - Token parameters (single object or array)
@@ -507,8 +565,8 @@ async function getNFTTokenInfo(params) {
         return await getNFTTokenInfoBatch(params.tokens, duration);
     }
     // Handle single token
-    const { chain, contractAddress, tokenId } = params;
-    const result = await getNFTTokenInfoSingle({ chain, contractAddress, tokenId }, duration);
+    const { chain, contractAddress, tokenId, standard } = params;
+    const result = await getNFTTokenInfoSingle({ chain, contractAddress, tokenId, standard }, duration);
     return result;
 }
 /**
@@ -530,7 +588,7 @@ async function getNFTTokenInfo(params) {
  */
 async function getNFTTokenInfoSingle(params, duration, options = {}) {
     let chain = params.chain;
-    const { contractAddress, tokenId } = params;
+    const { contractAddress, tokenId, standard } = params;
     // DEFENSIVE: Auto-detect and correct chain based on contract address format
     if (contractAddress.startsWith('KT') && chain !== 'tezos') {
         logger.warn(`[NFT Indexer] Chain mismatch detected! Contract ${contractAddress} starts with KT but chain="${chain}". Auto-correcting to "tezos".`);
@@ -547,7 +605,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
     });
     try {
         // Build token CID in CAIP-2 format
-        const tokenCID = buildTokenCID(chain, contractAddress, tokenId);
+        const tokenCID = buildTokenCID(chain, contractAddress, tokenId, standard);
         logger.info(`[NFT Indexer] Built token CID: ${tokenCID}`);
         // Query the indexer
         logger.info(`[NFT Indexer] Querying indexer GraphQL for token...`);
@@ -556,7 +614,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
         if (!indexerData) {
             logger.info(`[NFT Indexer] Token not in database, triggering async indexing...`);
             // Trigger background indexing workflow
-            const indexResult = await triggerIndexingAsync(chain, contractAddress, tokenId);
+            const indexResult = await triggerIndexingAsync(chain, contractAddress, tokenId, standard);
             if (!indexResult.success) {
                 logger.debug(`[NFT Indexer] Failed to trigger indexing:`, indexResult.error);
                 return {
@@ -609,7 +667,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
             }
         }
         // Map to standard format and convert to DP1
-        const tokenData = mapIndexerDataToStandardFormat(indexerData, chain);
+        const tokenData = mapIndexerDataToStandardFormat(indexerData, chain, standard);
         return convertToDP1Item(tokenData, duration);
     }
     catch (error) {
@@ -621,15 +679,21 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
     }
 }
 /**
- * Get NFT token information in batch and return as DP1 items (parallel processing)
+ * Resolve a batch of tokens and return every outcome (parallel processing)
  *
  * For missing tokens: triggers indexing per token, polls by job_id, then fetches again.
  *
- * @param {Array} tokens - Array of token parameters
+ * Unlike getNFTTokenInfoBatch this keeps one result per input token, in input
+ * order: a resolved token as `{ success: true, item, still }`, a failed one as
+ * `{ success: false, error, token }`. Callers that must know which request an
+ * answer belongs to, or that need the still beside the item, use this.
+ *
+ * @param {Array} tokens - Array of token parameters (chain, contractAddress, tokenId, standard?)
  * @param {number} duration - Display duration in seconds
- * @returns {Promise<Array>} Array of DP1 items
+ * @param {Function} [onProgress] - Called with (done, total) after each batch
+ * @returns {Promise<Array>} One result per input token
  */
-async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
+async function resolveTokenBatch(tokens, duration, onProgress) {
     logger.info(`[NFT Indexer] 📦 Starting batch processing for ${tokens.length} token(s)...`);
     logger.debug('[NFT Indexer] Batch tokens:', tokens);
     const results = [];
@@ -669,6 +733,23 @@ async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
     const successCount = results.filter((r) => r.success && r.item).length;
     const failedCount = results.length - successCount;
     logger.info(`[NFT Indexer] Final: ${successCount} items with data, ${failedCount} without`);
+    return results;
+}
+/**
+ * Get NFT token information in batch and return as DP1 items (parallel processing)
+ *
+ * For missing tokens: triggers indexing per token, polls by job_id, then fetches again.
+ *
+ * Returns only the resolved items. Failures are dropped, not represented, so
+ * the result is neither aligned with nor as long as the input; a caller that
+ * needs the association uses resolveTokenBatch.
+ *
+ * @param {Array} tokens - Array of token parameters
+ * @param {number} duration - Display duration in seconds
+ * @returns {Promise<Array>} Array of DP1 items
+ */
+async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
+    const results = await resolveTokenBatch(tokens, duration, onProgress);
     // Return only items (not error objects)
     const items = results.filter((r) => r.success && r.item).map((r) => r.item);
     logger.info(`[NFT Indexer] Returning ${items.length} items`);
@@ -719,10 +800,10 @@ async function getCollectionInfo(params) {
  * @returns {number} [returns.job_id] - Postgres queue job id; use with jobStatus / pollForJobCompletion
  * @returns {string} [returns.error] - Error message if failed
  */
-async function triggerIndexingAsync(chain, contractAddress, tokenId) {
+async function triggerIndexingAsync(chain, contractAddress, tokenId, standard) {
     try {
         // Build token CID
-        const tokenCID = buildTokenCID(chain, contractAddress, tokenId);
+        const tokenCID = buildTokenCID(chain, contractAddress, tokenId, standard);
         logger.debug('[NFT Indexer] Triggering token indexing job via GraphQL mutation:', {
             tokenCID,
         });
@@ -1050,6 +1131,7 @@ module.exports = {
     getNFTTokenInfo,
     // Batch processing
     getNFTTokenInfoBatch,
+    resolveTokenBatch,
     // Single token processing
     getNFTTokenInfoSingle,
     // Additional functions

package/dist/src/utilities/playlist-builder.js

@@ -14,6 +14,14 @@ const { playlistSigningDidKey } = require('./signing-identity');
 const { buildInlineManifestForToken } = require('./ref-manifest');
 /** Default display background that passes DP-1 hex color validation. */
 const DEFAULT_BACKGROUND = '#111111';
+/**
+ * DP-1 signature role that carries ownership of a playlist.
+ *
+ * The feed derives a playlist's owners from `curators[]` and then requires one of those keys to have
+ * signed as `curator`: being named is a claim, signing in this role is the proof. Playlist groups use
+ * the same role; channels use `publisher`, which ff-cli does not publish.
+ */
+const PLAYLIST_OWNER_ROLE = 'curator';
 /**
  * isTimeBasedMedia reports whether an item's media has an intrinsic runtime
  * (video or audio) per DP-1 §4.1 "time-based sources".
@@ -497,7 +505,16 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
             if (!declared.some((curator) => curator && curator.key === key)) {
                 playlist.curators = [...declared, { name: playlistConfig.curatorName || 'ff-cli', key }];
             }
-            playlist.signatures = [await signPlaylist(playlist, playlistConfig.privateKey)];
+            // Sign in the `curator` role, not the configured one. Declaring the key in curators[] is the
+            // document claiming that key is an owner; the feed treats a declared key as an owner only when the
+            // same key also signed in the owner role, so any other role leaves the document declared, verified
+            // and unpublishable — the exact shape that made every ff-cli playlist fail before (#107). The role
+            // has to follow the claim the builder just wrote. `playlist.role` still governs `ff-cli sign`,
+            // where the user chooses what claim to make; to build under a different role, build without a
+            // configured key and sign the result explicitly.
+            playlist.signatures = [
+                await signPlaylist(playlist, playlistConfig.privateKey, PLAYLIST_OWNER_ROLE),
+            ];
             delete playlist.signature;
         }
     }

package/dist/src/utilities/playlist-cast.js

@@ -34,6 +34,25 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.castPlaylist = castPlaylist;
+/**
+ * DP-1 signature role used when signing a playlist for playback.
+ *
+ * A cast never passes through a feed, so a document signed here carries no `feed` signature and its own
+ * entry is the only one a player could judge. DP-1 §7.1.1 rule 1 has players verify a `feed` or `curator`
+ * signature, so the configured role (shipped default `agent`) is the weakest choice available for a
+ * document this CLI is minting itself.
+ *
+ * Scope: this governs only the envelope the CLI *creates* — direct media, which arrives unsigned and must
+ * be signed before delivery. A playlist that already carries signatures is cast verbatim whatever its
+ * roles, because rewriting someone else's envelope is not this function's business. No player in this
+ * ecosystem enforces rule 1 today (ff-player performs no signature verification at all), so this is about
+ * not minting the weakest document we could, rather than about a failure observed on a device.
+ *
+ * This also has to match what the builder wrote: a wrapped media URL arrives here already declaring the
+ * signing key in `curators[]` and signed as `curator`, and signing REPLACES `signatures[]` rather than
+ * appending — so any other role here silently downgrades that envelope on its way to the device.
+ */
+const PLAYBACK_SIGNING_ROLE = 'curator';
 // playlist-signer and ff1-device are still CommonJS; require keeps interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { signPlaylist } = require('./playlist-signer');
@@ -68,7 +87,7 @@ async function castPlaylist(playlist, options = {}) {
                 };
             }
             try {
-                const signature = await signPlaylist(current, options.signingKey);
+                const signature = await signPlaylist(current, options.signingKey, PLAYBACK_SIGNING_ROLE);
                 current = {
                     ...current,
                     signature: undefined,

package/dist/src/utilities/playlist-publisher.js

@@ -7,6 +7,12 @@ exports.publishPlaylist = publishPlaylist;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = __importDefault(require("fs"));
 const playlist_verifier_1 = require("./playlist-verifier");
+/**
+ * DP-1 signature role that carries ownership of a playlist.
+ *
+ * Mirrors the feed's owner role for playlists (channels use `publisher`, which ff-cli does not publish).
+ */
+const OWNER_ROLE = 'curator';
 /**
  * Publish a verified playlist to a DP-1 feed server
  *
@@ -68,7 +74,9 @@ async function publishPlaylist(filePath, feedServerUrl) {
                     `  Re-sign it as a DP-1 v1.1 envelope:\n` +
                     `    1. remove the "signature" field\n` +
                     `    2. declare your key: "curators": [{ "name": "Your name", "key": "<did:key from ff-cli status>" }]\n` +
-                    `    3. ff-cli sign <file>`,
+                    `    3. ff-cli sign <file> -r ${OWNER_ROLE}\n` +
+                    `  The role matters: a declared key counts as an owner only when it also signed as "${OWNER_ROLE}",\n` +
+                    `  and plain "ff-cli sign" uses playlist.role, which defaults to "agent".`,
             };
         }
         // Step 3: Verify signature integrity before publishing.
@@ -92,20 +100,81 @@ async function publishPlaylist(filePath, feedServerUrl) {
             .map((c) => (typeof c?.key === 'string' ? c.key.trim() : ''))
             .filter((k) => k.length > 0));
         const signatures = Array.isArray(playlist.signatures)
-            ? (playlist.signatures ?? [])
+            ? (playlist
+                .signatures ?? [])
             : [];
         const signingKids = signatures
             .map((sig) => (typeof sig?.kid === 'string' ? sig.kid.trim() : ''))
             .filter((k) => k.length > 0);
-        if (signingKids.length > 0 && !signingKids.some((kid) => curatorKeys.has(kid))) {
+        const declaredSignatures = signatures.filter((sig) => curatorKeys.has(typeof sig?.kid === 'string' ? sig.kid.trim() : ''));
+        // Same predicate as `no declared signature`, expressed through the set the next gate also needs.
+        if (signingKids.length > 0 && declaredSignatures.length === 0) {
             return {
                 success: false,
                 error: 'Playlist is signed, but the signing key is not declared as a curator.',
                 message: `The feed accepts a publish when a signature's kid appears in the playlist's own curators[].\n` +
                     `  Add this to the playlist before signing:\n` +
                     `    "curators": [{ "name": "Your name", "key": "${signingKids[0]}" }]\n` +
-                    `  then sign again from the unsigned file — signing appends, so re-signing an already-signed\n` +
-                    `  playlist leaves the earlier signature covering a document that no longer exists.`,
+                    `  then sign again from the unsigned file, with the same key you just declared:\n` +
+                    `    ff-cli sign <file> -r ${OWNER_ROLE} --key <private key for ${signingKids[0]}>\n` +
+                    `  Drop --key if that key is your configured one; "sign" uses the configured key otherwise, and a\n` +
+                    `  signature from an undeclared key would not satisfy the feed. The role is ff-cli's requirement\n` +
+                    `  rather than every feed's: see the owner-role check for why publishing without it is refused.\n` +
+                    `  Start from the unsigned file\n` +
+                    `  because declaring curators[] changes the signed payload: signing appends, so the earlier\n` +
+                    `  signature would be left covering a document that no longer exists.`,
+            };
+        }
+        // Step 4b: a declared key must also have signed AS curator.
+        //
+        // Being named in curators[] is a claim; signing in the owner role is the proof, and the feed requires
+        // both before it treats a key as an owner. A document that is declared but signed under another role
+        // (ff-cli's own default was `agent`) verifies cleanly and is still refused, and the server answers in
+        // terms of ownership — which reads as "fix curators[]", the one part that is already correct. Naming
+        // the role and the remedy here is the difference between a one-flag fix and a wrong-end search.
+        //
+        // This is deliberately stricter than a feed that ignores the role: such a feed accepts the document
+        // today and freezes it the moment role-aware ownership lands, because a replace and a delete both
+        // need an owner signature the document does not carry. Refusing now keeps that document from being
+        // created at all.
+        if (declaredSignatures.length > 0 &&
+            !declaredSignatures.some((sig) => sig.role === OWNER_ROLE)) {
+            const rolesUsed = [
+                ...new Set(declaredSignatures
+                    .map((sig) => (typeof sig.role === 'string' ? sig.role.trim() : ''))
+                    .filter((role) => role.length > 0)),
+            ];
+            const seen = rolesUsed.length > 0 ? rolesUsed.map((role) => `"${role}"`).join(', ') : 'no role';
+            // List every key eligible to repair this, not the one that happens to have signed.
+            //
+            // The gate above accepts an owner-role signature from ANY declared key, so on a playlist declaring
+            // several curators the holder of any one of them can append it. Naming only the key that signed
+            // under the wrong role describes an impossible fix to everyone else — they may not hold it — while
+            // a key they do hold would have worked. `sign` still defaults to the configured key, which need not
+            // be declared at all, so the eligible set has to be stated rather than assumed.
+            const eligibleKeys = [...curatorKeys];
+            const eligibleList = eligibleKeys.length > 0 ? eligibleKeys.join(', ') : 'a key declared in curators[]';
+            return {
+                success: false,
+                error: `Playlist is signed by a declared curator, but under a non-owner role (${seen}).`,
+                message: `This is ff-cli's check, not a feed's answer. Feeds are moving to role-aware ownership, where\n` +
+                    `  a key in curators[] counts as an owner only if it also signed as "${OWNER_ROLE}". A feed that\n` +
+                    `  does not check the role yet will accept this document, and then be unable to authorize a\n` +
+                    `  replace or a delete for it: both need an owner signature it does not carry. Publishing it is\n` +
+                    `  what makes that permanent, so ff-cli refuses here instead.\n` +
+                    `\n` +
+                    `  curators[] is already correct — only the role is missing, so add that signature to this file:\n` +
+                    `    ff-cli sign <file> -r ${OWNER_ROLE} --key <private key for a declared curator>\n` +
+                    `  Any key this playlist declares will do — you do not need the one that signed under the wrong\n` +
+                    `  role. Declared: ${eligibleList}\n` +
+                    `  It must be one of those: a ${OWNER_ROLE} signature from an undeclared key satisfies neither\n` +
+                    `  this check nor role-aware ownership, since both read roles only from declared keys. "sign"\n` +
+                    `  uses the configured key unless --key says otherwise; drop --key if a declared key is already\n` +
+                    `  your configured one, and confirm which identity a key carries with\n` +
+                    `  "ff-cli status --key <private key>".\n` +
+                    `  Signing appends, and the payload hash excludes signatures, so the existing entry stays valid\n` +
+                    `  and the document ends up carrying both. No unsigned copy is needed: you only have to start\n` +
+                    `  from one when changing signed content such as curators[] itself.`,
             };
         }
         // Step 5: Send validated playlist to feed server.

package/docs/CONFIGURATION.md

@@ -63,7 +63,7 @@ Used for signing DP‑1 playlists.
   `PLAYLIST_PRIVATE_KEY` even when no config file exists yet, and `ff-cli status --key <privateKey>`
   reports it for an explicit key — the one `sign --key` would use.
 
-- `playlist.role` (string): DP-1 signing role that travels with the private key. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`).
+- `playlist.role` (string): DP-1 signing role used by `ff-cli sign`. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`). It does **not** apply to `find` and `build`, which always sign as `curator` — see [Signing role and ownership](#signing-role-and-ownership).
 
 ### Generate an Ed25519 private key
 
@@ -88,6 +88,33 @@ Paste the value into `playlist.privateKey`. Any of these are accepted:
 
 If you need a different role, set `playlist.role` to one of the DP-1 signing roles such as `agent`, `feed`, `curator`, `institution`, or `licensor`. The CLI rejects any other string before it reaches `dp1-js`.
 
+### Signing role and ownership
+
+A feed decides who owns a playlist from the document itself: the keys in `curators[]` are the owner set.
+Under **role-aware ownership**, a key counts as an owner only when that same key *also signed in the
+`curator` role* — being named is a claim, signing as `curator` is the proof.
+
+`ff-cli publish` requires that role. **This is ff-cli's check, not every feed's answer today**: a feed that
+does not yet enforce roles accepts an `agent`-signed document, so a manual upload of the same file can
+still succeed. It is refused here because once accepted, such a document can never be replaced or deleted —
+both need an owner signature it does not carry, and the only way to add one is to replace it. Publishing is
+what makes that permanent.
+
+The `kid`-to-`curators[]` match is different: feeds enforce that today, and a playlist failing it is
+rejected by the server regardless of ff-cli.
+
+Two consequences:
+
+- `find` and `build` declare your key in `curators[]` and therefore always sign as `curator`, whatever
+  `playlist.role` says. To build under a different role, build without a configured signing key and sign the
+  result yourself with `ff-cli sign --role`.
+- `ff-cli publish` refuses a playlist whose declared key signed under another role, and names the fix
+  (`ff-cli sign <file> -r curator`, from any key declared in `curators[]`). This runs before any request,
+  so it costs nothing — and deliberately does not defer to a feed that would accept the document today,
+  because acceptance is what makes it unfixable.
+
+Channels use `publisher` as the owner role instead of `curator`; ff-cli does not publish channels.
+
 If you already have a base64 key and want hex, convert it:
 
 ```bash

package/docs/EXAMPLES.md

@@ -239,7 +239,7 @@ title-only on the FF1 tombstone, and shows empty tiles in the app for every
 live HTML work. `enrich` repairs it in place.
 
 ```bash
-ff-cli enrich playlist.json
+ff-cli enrich playlist.json --assume-ethereum
 ```
 
 ```text
@@ -251,25 +251,37 @@ Enrich playlist
   Output: playlist.json
 ```
 
+`--assume-ethereum` is the operator's assertion that the playlist's `evm`
+coordinates are Ethereum. DP-1 records every EVM network as `chain: "evm"`,
+and `find` writes that for Ethereum works too, so an Ethereum playlist needs
+the flag; without it those items are skipped rather than guessed at, because
+the wrong network returns a different artwork's metadata. A Tezos playlist
+needs no flag.
+
 Items the indexer cannot resolve are listed rather than guessed at:
 
 ```text
 Nothing to enrich
 
-  Skipped 2:
+  Skipped 3:
     Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
     Untitled — the indexer returned nothing for it
+    Pre-Process — chain "evm" names a family; pass --assume-ethereum to assert the network
 ```
 
 Enrichment changes the document, so a signed playlist loses its envelope and
 has to be re-signed:
 
 ```bash
-ff-cli enrich playlist.json
+ff-cli enrich playlist.json --assume-ethereum
 ff-cli sign playlist.json
 ff-cli play playlist.json -d "living room"
 ```
 
+Casting does not care about the signing role. Add `-r curator` to that `sign` if the playlist is also
+going to a feed: `ff-cli publish` requires the owner role, for the reasons in
+[Publish to Feed Server](#publish-to-feed-server).
+
 ## Validate / Sign / Play
 
 ```bash
@@ -390,7 +402,17 @@ Publish failed
   Playlist verification failed: Playlist signature verification failed
 ```
 
-Run `ff-cli sign <file>` before publishing. (Posting the same document straight to the feed answers
+Declare your key in `curators[]`, then sign it as the owner before publishing:
+
+```bash
+ff-cli status                          # the did:key to declare
+ff-cli sign <file> -r curator
+```
+
+Plain `ff-cli sign` would use `playlist.role` (default `agent`), producing a document the next two checks
+refuse — under role-aware ownership a declared key counts as an owner only when it signed as `curator`, and
+`ff-cli publish` requires that whether or not the target feed enforces it yet. (Posting the unsigned
+document straight to the feed answers
 `{"error":"unauthorized","message":"missing authentication: request body must carry signatures"}`.)
 
 **Signed, but the signer is not declared as a curator:**
@@ -402,8 +424,12 @@ Publish failed
 The feed accepts a publish when a signature's kid appears in the playlist's own curators[].
   Add this to the playlist before signing:
     "curators": [{ "name": "Your name", "key": "did:key:z6Mkv7qJ..." }]
-  then sign again from the unsigned file — signing appends, so re-signing an already-signed
-  playlist leaves the earlier signature covering a document that no longer exists.
+  then sign again from the unsigned file, with the same key you just declared:
+    ff-cli sign <file> -r curator --key <private key for did:key:z6Mkv7qJ...>
+  Drop --key if that key is your configured one; "sign" uses the configured key otherwise, and a
+  signature from an undeclared key would not satisfy the feed. Start from the unsigned file
+  because declaring curators[] changes the signed payload: signing appends, so the earlier
+  signature would be left covering a document that no longer exists.
 ```
 
 This is the most common publish failure, and it is not about credentials. The feed accepts a create when
@@ -425,8 +451,8 @@ ff-cli status          # → Signing identity (did:key)  did:key:z6Mk...
 #    "curators": [{ "name": "Your Name", "key": "did:key:z6Mk..." }]
 #    DP-1 requires `name` alongside `key`.
 
-# 3. Sign once, then publish.
-ff-cli sign playlist.json
+# 3. Sign once as curator, then publish. The role must match the claim in curators[].
+ff-cli sign playlist.json -r curator
 ff-cli publish playlist.json
 ```
 
@@ -436,6 +462,63 @@ rather than re-signing: remove `signatures`, declare the curator, then sign.
 `ff-cli publish` checks this before uploading, so a missing declaration fails immediately with the key to
 add rather than as a server error. No API key is involved: the feed does not accept one.
 
+**Declared, but signed under a non-owner role:**
+
+```
+Publish failed
+  Playlist is signed by a declared curator, but under a non-owner role ("agent").
+
+This is ff-cli's check, not a feed's answer. Feeds are moving to role-aware ownership, where
+  a key in curators[] counts as an owner only if it also signed as "curator". A feed that
+  does not check the role yet will accept this document, and then be unable to authorize a
+  replace or a delete for it: both need an owner signature it does not carry. Publishing it is
+  what makes that permanent, so ff-cli refuses here instead.
+
+  curators[] is already correct — only the role is missing, so add that signature to this file:
+    ff-cli sign <file> -r curator --key <private key for a declared curator>
+  Any key this playlist declares will do — you do not need the one that signed under the wrong
+  role. Declared: did:key:z6Mkv7qJ...
+  It must be one of those: a curator signature from an undeclared key satisfies neither
+  this check nor role-aware ownership, since both read roles only from declared keys. "sign"
+  uses the configured key unless --key says otherwise; drop --key if a declared key is already
+  your configured one, and confirm which identity a key carries with
+  "ff-cli status --key <private key>".
+  Signing appends, and the payload hash excludes signatures, so the existing entry stays valid
+  and the document ends up carrying both. No unsigned copy is needed: you only have to start
+  from one when changing signed content such as curators[] itself.
+```
+
+Declaring a key in `curators[]` is a claim that it owns the playlist; signing as `curator` is the proof.
+This failure means the document is right and the signature is not — the fix is the role, not `curators[]`.
+
+**This one is repairable in place**, unlike the two above. Nothing signed needs to change, so appending is
+enough — the payload hash covers the document with `signature`/`signatures` stripped, which leaves the
+earlier entry valid over bytes that did not move:
+
+```bash
+# --key only when the declared curator is not your configured key; `ff-cli status --key <k>`
+# reports which identity a key carries.
+ff-cli sign playlist.json -r curator --key <declared curator's key>   # ["agent"] -> ["agent","curator"]
+ff-cli publish playlist.json
+```
+
+The signature has to come from a key the playlist already declares — **any** of them, not specifically the
+one that signed under the wrong role. On a playlist with several curators, whoever holds one of the other
+declared keys can repair it. `sign` uses the configured key unless `--key` says otherwise, so on a machine
+whose configured key is not declared, the plain command appends a `curator` signature the feed ignores and
+the publish fails identically.
+
+Start again from an unsigned document only when the fix changes signed content — adding `curators[]`, for
+instance. There the earlier signature would cover a document that no longer exists.
+
+**This is a CLI preflight, not a report of what a feed said.** A feed that does not yet check the role
+accepts such a document, so uploading it by hand can still succeed. It is refused here because once
+accepted it can never be replaced **or** deleted: both need an owner signature it does not carry, and the
+only way to add one is to replace the document. Publishing is what makes that permanent.
+
+`find` and `build` sign as `curator` automatically, since they declare the key themselves. This applies to
+documents you sign by hand, where `playlist.role` (default `agent`) decides the role.
+
 ## Complete Flow (build → validate → sign → play → publish)
 
 ```bash
@@ -448,7 +531,9 @@ npm run dev -- validate playlist.json
 # 3. Sign it. Declare curators[] BEFORE this step: the signature covers it, and the feed only
 #    accepts a publish when a signature's kid matches a declared curator key.
 #    Run `ff-cli status` for the kid (add -k <key> if you sign with `sign --key`).
-npm run dev -- sign playlist.json -o signed.json
+#    -r curator: ff-cli publish requires the owner role (role-aware ownership); the kid match is
+#    what feeds enforce today.
+npm run dev -- sign playlist.json -r curator -o signed.json
 
 # 4. Play it on a device
 npm run dev -- play signed.json -d "Living Room Display"

package/docs/PROJECT_SPEC.md

@@ -237,28 +237,41 @@ and nothing else. `enrich` is the repair path for those.
   changing the title would produce two documents claiming to be the same cached
   manifest. The replacement is derived from the original id and the title, so
   it is deterministic across runs.
+- The token standard the playlist asserts (`provenance.contract.standard`)
+  rides the lookup. The indexer keys ERC-721 and ERC-1155 tokens under
+  different CIDs (`eip155:1:erc721:…`, `eip155:1:erc1155:…`) and the client's
+  detection, having only an address, answers erc721 for every EVM contract —
+  so without the assertion an ERC-1155 work is queried as ERC-721 and never
+  found. A value outside the standards the CID can carry falls back to
+  detection.
 - The indexer resolving a token and having something worth attaching are
   different outcomes: `buildInlineManifestForToken` returns nothing when it has
-  only a title, since a title-only manifest adds payload without adding
-  information. Enrichment reports those separately from tokens it could not
-  resolve at all.
+  only a title, since on the items `find` and `build` create a title-only
+  manifest repeats what the item already says. A curator's item may carry no
+  title at all, and the tombstone then shows nothing, so enrichment does
+  synthesize a title-only manifest in that one case — the indexer's title is
+  substantiated, and `item.title` itself is still never written. An item that
+  has a title and resolves to nothing more is reported as resolved-without-
+  metadata, separately from tokens the indexer could not resolve at all.
 - A still the manifest builder suppressed is recovered against the item's own
   source. `resolveStillUri` blanks a thumbnail equal to the source it was
   handed, which is the source the *indexer* chose; for a static work that is
   often the still itself. When the curator kept a live HTML source instead, the
   item would otherwise end up with no thumbnail — the empty grid tile this
-  command exists to remove. When the indexer's source differs from the item's
-  and is http(s) **and is media the app can rasterize**, it is that suppressed
-  still
-  and becomes the thumbnail. The type check matters: `getBestMediaUrl` prefers
-  `display.animation_url` and media assets over `display.image_url`, so the
-  indexer's source is frequently a live HTML rendition, and putting one in the
-  thumbnail slot is worse than leaving it empty — the grid still cannot
-  rasterize it and the item now claims a still it does not have. The predicate
-  matches the media types `playlist-builder.js` already recognizes, images plus
-  SVG and video, and rejects HTML. A
-  thumbnail-only manifest is emitted where none was, unlike a title-only one:
-  it is the difference between a tile and an empty square.
+  command exists to remove. The lookup therefore carries the still the indexer
+  names for the token (`display.image_url`, returned beside the DP-1 item by
+  `resolveTokenBatch`), and enrichment applies the same rule against the
+  curator's source: when that still differs from the item's source it becomes
+  the thumbnail. It is the same field `find` and `build` write into
+  `thumbnails.default`, taken on the indexer's word as they take it. Nothing is
+  inferred from the indexer's *source*: `getBestMediaUrl` prefers
+  `display.animation_url` and media assets over `display.image_url`, so that
+  source is frequently a live HTML rendition, and a file-suffix check would
+  reject the extensionless CDN URLs the indexer commonly returns as stills
+  while `display.mime_type` describes the primary rendition rather than the
+  still (a live work reports `text/html` beside a PNG `image_url`). A
+  thumbnail-only manifest is emitted where none was: it is the difference
+  between a tile and an empty square.
 - `evm` names a family, and enrichment refuses to guess which member. DP-1 §6
   carries no network identity, and the indexer maps Ethereum, Polygon,
   Arbitrum, Optimism, Base, and Zora all back to `evm`, so neither the request

package/docs/README.md

@@ -193,8 +193,8 @@ image, video, or SVG source, but not from a live HTML work.
 
 ```bash
 ff-cli enrich playlist.json --assume-ethereum
-ff-cli enrich playlist.json -o labelled.json
-ff-cli enrich playlist.json --force        # replace existing manifests
+ff-cli enrich playlist.json --assume-ethereum -o labelled.json
+ff-cli enrich playlist.json --assume-ethereum --force   # replace existing manifests
 ```
 
 `--assume-ethereum` is needed for most playlists. DP-1 records an EVM
@@ -212,9 +212,12 @@ changes the document, so the signature is removed and the playlist must be
 re-signed before playing:
 
 ```bash
-ff-cli enrich playlist.json && ff-cli sign playlist.json
+ff-cli enrich playlist.json --assume-ethereum && ff-cli sign playlist.json
 ```
 
+That role is fine for casting. Use `ff-cli sign playlist.json -r curator` if the enriched playlist is
+also going to a feed.
+
 ### Validate, sign, and play
 
 ```bash
@@ -282,12 +285,30 @@ Configure feed servers in `config.json`:
 Publishing needs no credentials. The feed authorizes a create from the signatures inside the playlist:
 it requires a signature whose `kid` matches a key the document declares in `curators[]`.
 
+`ff-cli publish` additionally requires that signature to carry the **`curator` role**. That is ff-cli's
+check, not every feed's answer today: feeds are moving to role-aware ownership, where being named in
+`curators[]` is a claim and signing as `curator` is the proof. A feed that does not check the role yet
+accepts an `agent`-signed document — and can then authorize neither a replace nor a delete for it, since
+both need an owner signature it does not carry. Publishing is what makes that permanent, so the CLI
+refuses first.
+
 Declare it before signing, not after: a signature covers `curators[]`, so adding the entry to an
 already-signed playlist invalidates it, and signing again appends rather than replaces. Run
 `ff-cli status` to read the `did:key` your signatures will carry, put it in `curators[]`, then sign
-once. If you sign with `sign --key <privateKey>`, read that key's identity with
-`ff-cli status --key <privateKey>` — the configured identity would be the wrong one to declare. `find` and `build` do this for you when a signing key is configured. An `apiKey` left over in
-an existing config is ignored.
+once **with the owner role**:
+
+```bash
+ff-cli sign playlist.json -r curator
+```
+
+The flag is needed because plain `ff-cli sign` uses `playlist.role`, which defaults to `agent` — a
+document `ff-cli publish` then refuses. Set `"role": "curator"` under `playlist` in `config.json` to make
+that the default for hand-signed playlists.
+
+If you sign with `sign --key <privateKey>`, read that key's identity with
+`ff-cli status --key <privateKey>` — the configured identity would be the wrong one to declare. `find`
+and `build` need none of this: they declare the key and sign it as `curator` for you when a signing key
+is configured. An `apiKey` left over in an existing config is ignored.
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
   "dependencies": {
     "@feralfile/source-resolver": "^1.0.0",
     "@napi-rs/keyring": "1.3.0",
-    "axios": "^1.6.2",
+    "axios": "^1.20.0",
     "bonjour-service": "^1.3.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
@@ -68,7 +68,7 @@
     "dp1-js": "2.3.1",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
-    "viem": "^2.38.2"
+    "viem": "^2.56.3"
   },
   "devDependencies": {
     "@types/node": "^24.7.1",