@feralfile/cli 2.2.3 → 2.3.0

package/README.md

@@ -12,15 +12,7 @@ ff-cli is a set of deterministic commands for building DP-1–conformant playlis
 npm i -g @feralfile/cli
 ```
 
-This is the recommended path and the most reliable for the agent workflow — it installs a complete package (including `config.json.example` and the bundled `dp1-js`). Requires Node.js 22+.
-
-## Install (curl)
-
-```bash
-curl -fsSL https://feralfile.com/ff-cli-install | bash
-```
-
-Installs a prebuilt binary for macOS/Linux. Node.js 22+ must still be on your PATH (the bundle runs under `node`). If a command fails right after install, prefer the npm install above.
+This installs a complete package (including `config.json.example` and the bundled `dp1-js`). Requires Node.js 22+.
 
 ## One-off Usage (npx)
 
@@ -138,8 +130,7 @@ Run the same command locally before opening a PR. It checks formatting, lint, te
 
 Other GitHub Actions workflows:
 
-- `.github/workflows/build.yml` builds release assets when called by release automation or manually dispatched.
-- `.github/workflows/release.yml` reuses CI, verifies the release version, publishes npm, uploads assets, and checks the published release.
+- `.github/workflows/release.yml` reuses CI, verifies the release version, publishes to npm, and checks the published package.
 - `.github/workflows/dependency-review.yml` reviews dependency changes on pull requests.
 - `.github/workflows/codeql.yml` runs CodeQL analysis on pull requests and pushes to `main`/`master`.
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.2.3",
+    "version": "2.3.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",
@@ -58,14 +58,14 @@
     "author": "",
     "license": "MIT",
     "dependencies": {
-        "@napi-rs/keyring": "1.3.0",
         "@feralfile/source-resolver": "^1.0.0",
+        "@napi-rs/keyring": "1.3.0",
         "axios": "^1.6.2",
         "bonjour-service": "^1.3.0",
         "chalk": "^4.1.2",
         "commander": "^11.1.0",
         "dotenv": "^16.3.1",
-        "dp1-js": "2.0.0",
+        "dp1-js": "2.3.1",
         "ff1": "^1.0.0",
         "fuzzysort": "^3.1.0",
         "viem": "^2.38.2"

package/dist/src/utilities/feed-fetcher.js

@@ -329,6 +329,25 @@ function shuffleArray(array) {
     }
     return shuffled;
 }
+/**
+ * Normalize a legacy item `provenance` block to the DP-1 schema shape.
+ *
+ * A prior `buildUrlItem` stamped off-chain URL items with
+ * `provenance: { type: 'offChainURI', uri }`, but the DP-1 ProvenanceBlock has
+ * no top-level `uri` — a `uri` only exists under `provenance.contract`. Drop the
+ * stray top-level `uri` so rebuilding a legacy feed playlist produces the same
+ * clean shape as freshly-built items; every other provenance field is preserved.
+ *
+ * @param {Object} provenance - Item provenance block (already known to be an object)
+ * @returns {Object} Provenance without a stray top-level `uri`
+ */
+function normalizeProvenance(provenance) {
+    if (!('uri' in provenance)) {
+        return provenance;
+    }
+    const { uri: _uri, ...rest } = provenance;
+    return rest;
+}
 /**
  * Get playlist items from a playlist
  *
@@ -352,11 +371,22 @@ function extractPlaylistItems(playlist, quantity, duration, shuffle = true) {
     // Apply an explicit duration override when one was requested; otherwise
     // keep each item's own timing (including intentionally absent duration,
     // which DP-1 §4.1 uses for natural-length playback of video/audio).
+    //
+    // Strip any item-level `created`: the DP-1 PlaylistItem schema has no
+    // `created` field (it lives only at the playlist level), so drop it here —
+    // including from legacy feed entries that may still carry it — before the
+    // items reach PlaylistBuilder for construction.
+    //
+    // Also normalize legacy `offChainURI` provenance: an earlier `buildUrlItem`
+    // emitted `provenance: { type: 'offChainURI', uri }`, but the DP-1 schema has
+    // no top-level `provenance.uri` (a `uri` only lives under `provenance.contract`).
+    // Rebuilding a legacy feed playlist would otherwise carry that stray field
+    // through PlaylistBuilder into the output, so drop it during extraction.
     items = items.map((item) => {
-        const next = {
-            ...item,
-            created: item.created || new Date().toISOString(), // Ensure created field exists
-        };
+        const { created: _created, ...next } = item;
+        if (next.provenance && typeof next.provenance === 'object') {
+            next.provenance = normalizeProvenance(next.provenance);
+        }
         if (typeof duration === 'number') {
             next.duration = duration;
         }

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

@@ -3,10 +3,15 @@
  * This module provides functions to interact with NFT indexing services
  * to retrieve comprehensive token information.
  */
-const GRAPHQL_ENDPOINT = 'https://indexer.feralfile.com/graphql';
+const { PlaylistItemBuilder, ProvenanceBuilder, ContractBuilder } = require('dp1-js');
+// Production by default. INDEXER_API_URL exists so tests can point the
+// client at a local mock, the same way RASTER_API_URL already works — it
+// is not user-facing configuration, which stays removed (initializeIndexer).
+const GRAPHQL_ENDPOINT = process.env.INDEXER_API_URL || 'https://indexer.feralfile.com/graphql';
 const { fetchWithTimeout } = require('./http');
 const logger = require('../logger');
-const { applyItemTiming } = require('./playlist-builder');
+const { applyTimingToItemBuilder, buildDefaultDisplay } = require('./playlist-builder');
+const { buildInlineManifestForToken } = require('./ref-manifest');
 // Polling configuration (in milliseconds)
 const POLLING_INTERVAL_MS = 2000; // Poll every 2 seconds
 const POLLING_TIMEOUT_MS = 60000; // Max poll for 1 minute
@@ -355,6 +360,9 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
  * Extracts source URL from indexer data with proper priority:
  * animation_url > image.url, ensuring the best quality media is used.
  *
+ * When the token carries description, artist, or a still image distinct from
+ * the source, the item also gets an inline Ref Manifest (see ref-manifest.ts).
+ *
  * @param {Object} tokenData - Token data in standard format
  * @param {number} [duration] - Explicit display seconds; omit for auto timing
  *   (video/audio play natural length per DP-1 §4.1)
@@ -434,27 +442,40 @@ function convertToDP1Item(tokenData, duration) {
         tezos: 'tezos', // DP1 spec uses 'tezos', not 'tez'
         bitmark: 'bitmark', // DP1 spec uses 'bitmark', not 'bmk'
     };
-    // Build DP1 item structure (strict DP1 v1.0.0 compliance)
-    const dp1Item = {
-        id: itemId,
-        source: sourceUrl,
-        license: 'open',
-        created: new Date().toISOString(),
-        provenance: {
-            type: 'onChain',
-            contract: {
-                chain: chainMap[token.chain.toLowerCase()] || 'other',
-                standard: token.standard || detectTokenStandard(token.chain, token.contractAddress),
-                address: token.contractAddress,
-                tokenId: String(token.tokenId),
-            },
-        },
-    };
+    // Build via dp1-js PlaylistItemBuilder so leaf blocks match DP-1 AJV schema.
+    const itemBuilder = new PlaylistItemBuilder()
+        .id(itemId)
+        .source(sourceUrl)
+        .license('open')
+        .provenance(new ProvenanceBuilder().type('onChain').contract(new ContractBuilder()
+        .chain(chainMap[token.chain.toLowerCase()] || 'other')
+        .standard(token.standard || detectTokenStandard(token.chain, token.contractAddress))
+        .address(token.contractAddress)
+        .tokenId(String(token.tokenId))));
     // Add title if available (valid DP1 field)
     if (token.name) {
-        dp1Item.title = token.name;
+        itemBuilder.title(token.name);
+    }
+    // Carry description, artist, and still image inline (DP-1 Playlist Extension
+    // §3.6). These are the fields the indexer returns that have no PlaylistItem
+    // home; before inline manifests existed they were mapped and then dropped on
+    // the floor here. The helper returns undefined when the token has nothing
+    // beyond its title, so thin tokens stay thin.
+    const inlineManifest = buildInlineManifestForToken(token, { sourceUrl });
+    if (inlineManifest) {
+        itemBuilder.inlineManifest(inlineManifest);
+    }
+    applyTimingToItemBuilder(itemBuilder, { mimeType: token.image?.mimeType, sourceUrl }, duration, buildDefaultDisplay());
+    let dp1Item;
+    try {
+        dp1Item = itemBuilder.build();
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
     }
-    applyItemTiming(dp1Item, { mimeType: token.image?.mimeType, sourceUrl }, duration);
     logger.debug('[NFT Indexer] ✓ Converted to DP1:', {
         title: token.name,
         source: sourceUrl ? sourceUrl.substring(0, 60) + '...' : '(no source URL)',

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

@@ -1,9 +1,18 @@
 /**
  * Playlist Builder Utilities
- * Core functions for building and validating DP1 playlists
+ *
+ * Constructs DP-1 playlists and items via dp1-js document/leaf builders so
+ * every generated object is schema-validated against the DP-1 AJV defs before
+ * optional signing. Domain timing heuristics (DP-1 §4.1) stay in this module;
+ * leaf shapes (display, provenance, contract) come from dp1-js, and inline Ref
+ * Manifests (Playlist Extension §3.6) come from ./ref-manifest.
  */
+const { PlaylistBuilder, PlaylistItemBuilder, DisplayPrefsBuilder, ProvenanceBuilder, ContractBuilder, ValidatePlaylist, slugify: dp1Slugify, generateId, } = require('dp1-js');
 const { getPlaylistConfig, getConfig } = require('../config');
 const { signPlaylist } = require('./playlist-signer');
+const { buildInlineManifestForToken } = require('./ref-manifest');
+/** Default display background that passes DP-1 hex color validation. */
+const DEFAULT_BACKGROUND = '#111111';
 /**
  * isTimeBasedMedia reports whether an item's media has an intrinsic runtime
  * (video or audio) per DP-1 §4.1 "time-based sources".
@@ -41,41 +50,21 @@ function isInteractiveWeb(mimeType, sourceUrl) {
     return candidates.some((mime) => mime.startsWith('text/html'));
 }
 /**
- * applyItemTiming sets a DP1 item's playback timing per DP-1 §4.1.
- *
- * Invariant this function owns: an explicit numeric `duration` always wins
- * and is stamped as-is. When `duration` is undefined/null ("auto"):
- *   - a time-based source (video/audio) gets NO duration and
- *     `display.loop: false`, so a conformant player MUST advance at
- *     end-of-stream — the media plays its natural length;
- *   - an interactive web page (HTML) — generative art with no intrinsic
- *     runtime and no end-of-stream event — gets the configured
- *     `generativeDuration` (default 60s) so the playlist rotates. Set
- *     `generativeDuration` to 0 to omit it and have a conformant player park
- *     on the work open-ended instead;
- *   - static and code-based sources fall back to the configured
- *     `defaultDuration` because they have no intrinsic runtime to play out.
- *
- * Do not stamp a duration on video/audio: it silently truncates or pads them.
- * (Earlier this also omitted duration for HTML works, which left them with no
- * duration field. Players that require the field — notably FF1 — then rejected
- * the entire playlist, so generative works now carry an explicit duration.)
+ * resolveItemTiming computes duration/loop decisions per DP-1 §4.1 without
+ * mutating a playlist item. Callers stamp the result through PlaylistItemBuilder.
  *
- * @param {Object} item - DP1 playlist item (mutated in place)
  * @param {Object} mediaHints - Media signals for the time-based check
  * @param {string} [mediaHints.mimeType] - Indexer-reported MIME type
  * @param {string} [mediaHints.sourceUrl] - Item source URL
  * @param {number} [duration] - Explicit display seconds; omit for auto
- * @returns {Object} The same item, for chaining
+ * @returns {{ duration?: number, loopFalse?: boolean }}
  */
-function applyItemTiming(item, mediaHints = {}, duration) {
+function resolveItemTiming(mediaHints = {}, duration) {
     if (typeof duration === 'number') {
-        item.duration = duration;
-        return item;
+        return { duration };
     }
     if (isTimeBasedMedia(mediaHints.mimeType, mediaHints.sourceUrl)) {
-        item.display = { ...(item.display || {}), loop: false };
-        return item;
+        return { loopFalse: true };
     }
     if (isInteractiveWeb(mediaHints.mimeType, mediaHints.sourceUrl)) {
         // Generative/interactive works have no intrinsic runtime, so stamp the
@@ -83,13 +72,71 @@ function applyItemTiming(item, mediaHints = {}, duration) {
         // value of 0 means "omit" — a conformant player then parks open-ended.
         const generativeDuration = getGenerativeDuration();
         if (generativeDuration > 0) {
-            item.duration = generativeDuration;
+            return { duration: generativeDuration };
         }
-        return item;
+        return {};
+    }
+    return { duration: getDefaultStaticDuration() };
+}
+/**
+ * applyItemTiming sets a DP1 item's playback timing per DP-1 §4.1.
+ *
+ * Kept for unit tests and callers that mutate plain objects. New construction
+ * paths prefer resolveItemTiming + PlaylistItemBuilder so the final item is
+ * schema-validated by dp1-js.
+ *
+ * @param {Object} item - DP1 playlist item (mutated in place)
+ * @param {Object} mediaHints - Media signals for the time-based check
+ * @param {string} [mediaHints.mimeType] - Indexer-reported MIME type
+ * @param {string} [mediaHints.sourceUrl] - Item source URL
+ * @param {number} [duration] - Explicit display seconds; omit for auto
+ * @returns {Object} The same item, for chaining
+ */
+function applyItemTiming(item, mediaHints = {}, duration) {
+    const timing = resolveItemTiming(mediaHints, duration);
+    if (typeof timing.duration === 'number') {
+        item.duration = timing.duration;
+    }
+    if (timing.loopFalse) {
+        item.display = { ...(item.display || {}), loop: false };
     }
-    item.duration = getDefaultStaticDuration();
     return item;
 }
+/**
+ * buildDefaultDisplay builds schema-valid DisplayPrefs via dp1-js.
+ *
+ * @param {{ loopFalse?: boolean }} [opts]
+ * @returns {object} Validated DisplayPrefs
+ */
+function buildDefaultDisplay(opts = {}) {
+    const builder = new DisplayPrefsBuilder().scaling('fit').background(DEFAULT_BACKGROUND).margin(0);
+    if (opts.loopFalse) {
+        builder.loop(false);
+    }
+    return builder.build();
+}
+/**
+ * applyTimingToItemBuilder stamps resolveItemTiming results onto a builder.
+ *
+ * @param {InstanceType<typeof PlaylistItemBuilder>} itemBuilder
+ * @param {Object} mediaHints
+ * @param {number} [duration]
+ * @param {object} [baseDisplay] - Already-built DisplayPrefs without loop
+ * @returns {InstanceType<typeof PlaylistItemBuilder>}
+ */
+function applyTimingToItemBuilder(itemBuilder, mediaHints, duration, baseDisplay) {
+    const timing = resolveItemTiming(mediaHints, duration);
+    if (typeof timing.duration === 'number') {
+        itemBuilder.durationSeconds(timing.duration);
+    }
+    if (timing.loopFalse) {
+        itemBuilder.display(buildDefaultDisplay({ loopFalse: true }));
+    }
+    else if (baseDisplay) {
+        itemBuilder.display(baseDisplay);
+    }
+    return itemBuilder;
+}
 /**
  * getDefaultStaticDuration returns the configured per-item display seconds
  * for media without an intrinsic runtime. Falls back to 10 when config is
@@ -123,31 +170,30 @@ function getGenerativeDuration() {
     }
 }
 /**
- * Convert a string to a URL-friendly slug
- *
- * Lowercases, trims, replaces whitespace with dashes, and strips invalid chars.
- * Falls back to a short id when input is empty.
+ * slugify converts free text to a kebab-case slug via dp1-js.
+ * Falls back to a short id when input is empty (dp1-js slugify throws then).
  *
  * @param {string} value - Source string to slugify
  * @returns {string} Slugified string
  */
 function slugify(value) {
-    const base = (value || '').toString().trim().toLowerCase();
+    const base = (value || '').toString().trim();
     if (!base) {
-        const crypto = require('crypto');
-        return `playlist-${crypto.randomUUID().split('-')[0]}`;
-    }
-    return base
-        .normalize('NFD')
-        .replace(/[\u0300-\u036f]/g, '') // strip diacritics
-        .replace(/[^a-z0-9\s-]/g, '') // remove invalid chars
-        .replace(/\s+/g, '-') // spaces -> dashes
-        .replace(/-+/g, '-') // collapse dashes
-        .replace(/^-|-$/g, ''); // trim dashes
+        return `playlist-${generateId().split('-')[0]}`;
+    }
+    try {
+        return dp1Slugify(base);
+    }
+    catch (_error) {
+        return `playlist-${generateId().split('-')[0]}`;
+    }
 }
 /**
  * Convert single NFT token info to DP1 playlist item
  *
+ * When the token carries description, artist, or a still image distinct from
+ * the source, the item also gets an inline Ref Manifest (see ref-manifest.ts).
+ *
  * @param {Object} tokenInfo - Token information from NFT indexer
  * @param {number} [duration] - Explicit display seconds; omit for auto timing
  *   (video/audio play natural length per DP-1 §4.1, static media uses the
@@ -187,41 +233,41 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration) {
         fa2: 'fa2',
     };
     const standard = standardMap[token.standard?.toLowerCase()] || 'other';
-    // Generate unique ID for the item (UUID v4 format)
-    const crypto = require('crypto');
-    const itemId = crypto.randomUUID();
-    // Build DP1 item structure according to OpenAPI spec
-    const dp1Item = {
-        id: itemId,
-        title: token.name || `Token #${token.tokenId}`,
-        source: sourceUrl,
-        license: 'token', // NFTs are token-gated by default
-        created: new Date().toISOString(),
-        provenance: {
-            type: 'onChain',
-            contract: {
-                chain: chain,
-                standard: standard,
-                address: token.contractAddress,
-                tokenId: String(token.tokenId),
-            },
-        },
-    };
-    // Add display preferences if available
-    dp1Item.display = {
-        scaling: 'fit',
-        background: '#111',
-        margin: 0,
-    };
-    // Add metadata URI if available
-    if (token.metadata?.uri || token.tokenURI) {
-        dp1Item.provenance.contract.uri = token.metadata?.uri || token.tokenURI;
-    }
-    // Add reference to image if animation_url was used as source
-    if ((token.animation_url || token.animationUrl) && (token.image?.url || token.image)) {
-        dp1Item.ref = token.image?.url || token.image;
-    }
-    return applyItemTiming(dp1Item, { mimeType: token.image?.mimeType, sourceUrl }, duration);
+    const contractBuilder = new ContractBuilder()
+        .chain(chain)
+        .standard(standard)
+        .address(token.contractAddress)
+        .tokenId(String(token.tokenId));
+    // Add metadata URI if available (contract.uri is the DP-1 field)
+    const metadataUri = token.metadata?.uri || token.tokenURI;
+    if (metadataUri) {
+        contractBuilder.uri(metadataUri);
+    }
+    const itemBuilder = new PlaylistItemBuilder()
+        .id(generateId())
+        .title(token.name || `Token #${token.tokenId}`)
+        .source(sourceUrl)
+        .license('token')
+        .provenance(new ProvenanceBuilder().type('onChain').contract(contractBuilder));
+    // No `ref`. This used to set `ref` to `token.image.url` under a comment
+    // claiming it referenced the still image, but on the indexer path
+    // `image.url` is getBestMediaUrl's pick, which prefers `animation_url` —
+    // so for a dynamic work `ref` resolved to the animation URL, byte-identical
+    // to `source`. It never carried a poster frame. The still image lives in
+    // `image.thumbnail`, which that branch never read, and which the inline
+    // manifest below now carries as `metadata.thumbnails.default`.
+    //
+    // Emitting nothing is also the honest reading of DP-1: `ref` is a URI to an
+    // external Ref Manifest (and needs `refHash` over HTTPS), which a locally
+    // built playlist has nowhere to host — Playlist Extension §3.6 names this
+    // CLI as exactly that case. Add `ref` back only when there is a real
+    // manifest to point it at.
+    const inlineManifest = buildInlineManifestForToken(token, { sourceUrl });
+    if (inlineManifest) {
+        itemBuilder.inlineManifest(inlineManifest);
+    }
+    applyTimingToItemBuilder(itemBuilder, { mimeType: token.image?.mimeType, sourceUrl }, duration, buildDefaultDisplay());
+    return itemBuilder.build();
 }
 /**
  * Convert NFT token info(s) to DP1 playlist item(s)
@@ -340,10 +386,11 @@ function generatePlaylistTitle(items) {
     return `DP-1 Playlist (${items.length} ${items.length === 1 ? 'item' : 'items'})`;
 }
 /**
- * Build complete DP1 v1.0.0 compliant playlist
+ * Build a complete DP-1 v1.1.0 playlist via PlaylistBuilder.
  *
- * Creates a complete playlist structure with metadata, defaults, and optional signature.
- * Supports both object parameter and legacy separate parameters for backward compatibility.
+ * Creates a schema-validated unsigned playlist, then optionally signs when a
+ * private key is configured. Supports both object parameter and legacy
+ * separate parameters.
  *
  * @param {Object|Array} paramsOrItems - Playlist parameters object or items array (legacy)
  * @param {Array} [paramsOrItems.items] - Array of DP1 items
@@ -372,7 +419,7 @@ function generatePlaylistTitle(items) {
  *   title: 'Test',
  *   deterministicMode: true,
  *   fixedTimestamp: '2024-01-01T00:00:00.000Z',
- *   fixedId: 'playlist_test_123'
+ *   fixedId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  * });
  */
 async function buildDP1Playlist(paramsOrItems, options = {}) {
@@ -390,7 +437,7 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
         items = paramsOrItems;
         ({ title, slug, deterministicMode, fixedTimestamp, fixedId } = options);
     }
-    // Validate items
+    // Validate items early (PlaylistBuilder also rejects empty items without dynamicQuery)
     if (!Array.isArray(items) || items.length === 0) {
         throw new Error('Playlist must contain at least one item');
     }
@@ -414,32 +461,26 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
     if (!slug) {
         slug = slugify(title);
     }
-    // Build DP1 playlist structure using the v1.1.0 envelope.
-    // Support deterministic mode for testing (freeze timestamp and ID)
-    const timestamp = deterministicMode && fixedTimestamp ? fixedTimestamp : new Date().toISOString();
-    const crypto = require('crypto');
-    const playlistId = deterministicMode && fixedId ? fixedId : crypto.randomUUID();
-    const playlist = {
-        dpVersion: '1.1.0',
-        id: playlistId,
-        title,
-        created: timestamp,
-        items,
-        defaults: {
-            display: {
-                scaling: 'fit',
-                background: '#111',
-                margin: 0,
-            },
-            license: 'token',
-            // No defaults.duration: items that should be timed carry an explicit
-            // duration already, and a playlist-level default would make conformant
-            // players time-cut items that intentionally omit duration to play
-            // their natural length (DP-1 §4.1 end-of-stream advance).
-        },
-    };
-    // Always include slug (auto-generated when missing)
-    playlist.slug = slug;
+    // Build DP1 playlist structure using the v1.1.0 envelope via dp1-js.
+    // Support deterministic mode for testing (freeze timestamp and ID).
+    // No defaults.duration: items that should be timed carry an explicit
+    // duration already, and a playlist-level default would make conformant
+    // players time-cut items that intentionally omit duration to play
+    // their natural length (DP-1 §4.1 end-of-stream advance).
+    const playlistBuilder = new PlaylistBuilder()
+        .dpVersion('1.1.0')
+        .title(title)
+        .slug(slug)
+        .defaultDisplay(buildDefaultDisplay())
+        .defaultLicense('token')
+        .items(items);
+    if (deterministicMode && fixedId) {
+        playlistBuilder.id(fixedId);
+    }
+    if (deterministicMode && fixedTimestamp) {
+        playlistBuilder.created(fixedTimestamp);
+    }
+    const playlist = playlistBuilder.build();
     // Sign the playlist if private key is configured.
     try {
         const playlistConfig = getPlaylistConfig();
@@ -455,10 +496,10 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
     return playlist;
 }
 /**
- * Validate DP1 playlist structure according to OpenAPI spec
+ * validateDP1Playlist schema-validates a playlist via dp1-js ValidatePlaylist.
  *
- * Performs comprehensive validation of playlist structure, fields, and item requirements.
- * Returns detailed errors for each validation failure.
+ * Unsigned drafts are accepted (`requireSignatures: false`). Returns the
+ * historical `{ valid, errors }` shape for CLI/tests.
  *
  * @param {Object} playlist - DP1 playlist to validate
  * @returns {Object} Validation result
@@ -471,83 +512,21 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
  * }
  */
 function validateDP1Playlist(playlist) {
-    const errors = [];
-    // Check required playlist fields
-    if (!playlist.dpVersion) {
-        errors.push('Missing required field: dpVersion');
-    }
-    else if (typeof playlist.dpVersion !== 'string') {
-        errors.push('Field "dpVersion" must be a string');
-    }
-    if (!playlist.title) {
-        errors.push('Missing required field: title');
-    }
-    else if (playlist.title.length > 256) {
-        errors.push('Field "title" must not exceed 256 characters');
-    }
-    if (!playlist.items) {
-        errors.push('Missing required field: items');
-    }
-    else if (!Array.isArray(playlist.items)) {
-        errors.push('Field "items" must be an array');
-    }
-    else if (playlist.items.length === 0) {
-        errors.push('Playlist must contain at least one item');
-    }
-    else if (playlist.items.length > 1024) {
-        errors.push('Playlist cannot contain more than 1024 items');
+    try {
+        ValidatePlaylist(playlist, { requireSignatures: false });
+        return { valid: true, errors: [] };
     }
-    else {
-        // Validate each item according to PlaylistItem schema
-        playlist.items.forEach((item, index) => {
-            if (!item.source) {
-                errors.push(`Item ${index}: Missing required field "source"`);
-            }
-            else if (typeof item.source !== 'string') {
-                errors.push(`Item ${index}: Field "source" must be a string (URI)`);
-            }
-            // Duration is OPTIONAL per the DP-1 v1.1.0 schema (PlaylistItem requires
-            // only `source`; duration has `minimum: 0`). Absent duration is meaningful:
-            // time-based sources advance at end-of-stream (§4.1). Do not tighten this
-            // back to required — it would reject spec-valid playlists.
-            if (item.duration !== undefined && item.duration !== null) {
-                if (typeof item.duration !== 'number' || item.duration < 0) {
-                    errors.push(`Item ${index}: Field "duration" must be a number >= 0`);
-                }
-            }
-            if (!item.license) {
-                errors.push(`Item ${index}: Missing required field "license"`);
-            }
-            else if (!['open', 'token', 'subscription'].includes(item.license)) {
-                errors.push(`Item ${index}: Field "license" must be one of: open, token, subscription`);
-            }
-            // Validate optional title length
-            if (item.title && item.title.length > 256) {
-                errors.push(`Item ${index}: Field "title" must not exceed 256 characters`);
-            }
-            // Validate optional provenance structure
-            if (item.provenance) {
-                if (!item.provenance.type) {
-                    errors.push(`Item ${index}: provenance.type is required when provenance is present`);
-                }
-                else if (!['onChain', 'seriesRegistry', 'offChainURI'].includes(item.provenance.type)) {
-                    errors.push(`Item ${index}: provenance.type must be one of: onChain, seriesRegistry, offChainURI`);
-                }
-                if (item.provenance.contract) {
-                    if (!item.provenance.contract.chain) {
-                        errors.push(`Item ${index}: provenance.contract.chain is required`);
-                    }
-                    else if (!['evm', 'tezos', 'bitmark', 'other'].includes(item.provenance.contract.chain)) {
-                        errors.push(`Item ${index}: provenance.contract.chain must be one of: evm, tezos, bitmark, other`);
-                    }
-                }
-            }
-        });
+    catch (error) {
+        const details = Array.isArray(error?.details) ? error.details : [];
+        const errors = details.length > 0
+            ? details.map((detail) => {
+                const path = detail?.path ? String(detail.path) : '/';
+                const message = detail?.message ? String(detail.message) : 'validation failed';
+                return `${path}: ${message}`;
+            })
+            : [error instanceof Error ? error.message : String(error)];
+        return { valid: false, errors };
     }
-    return {
-        valid: errors.length === 0,
-        errors,
-    };
 }
 /**
  * Detect MIME type from a URL or file extension.
@@ -608,7 +587,7 @@ function detectMimeType(url) {
     return mimeTypes[extension] || '';
 }
 /**
- * Build a single DP1 playlist item from a URL
+ * Build a single DP1 playlist item from a URL via PlaylistItemBuilder.
  *
  * @param {string} url - Media URL
  * @param {number} [duration] - Explicit display seconds; omit for auto timing
@@ -645,31 +624,27 @@ function buildUrlItem(url, duration, options = {}) {
             title = 'URL Playback';
         }
     }
-    const crypto = require('crypto');
-    const itemId = crypto.randomUUID();
-    const item = {
-        id: itemId,
-        title,
-        source: sourceUrl,
-        license: 'open',
-        created: new Date().toISOString(),
-        provenance: {
-            type: 'offChainURI',
-            uri: sourceUrl,
-        },
-        display: {
-            scaling: 'fit',
-            background: '#111',
-            margin: 0,
-        },
-    };
+    // No inline Ref Manifest here, deliberately: an off-chain URL item holds only
+    // url, title, and mimeType. `mimeType` is a timing hint with no place in
+    // DP-1 Metadata, and `title` is already written to the item below — so a
+    // manifest would carry nothing the item does not already say. If a resolver
+    // ever supplies a real description or artist, route it through
+    // buildInlineManifestForToken rather than lowering that bar.
+    const itemBuilder = new PlaylistItemBuilder()
+        .id(generateId())
+        .title(title)
+        .source(sourceUrl)
+        .license('open')
+        // offChainURI has no provenance.uri in the DP-1 schema — only type.
+        .provenance(new ProvenanceBuilder().type('offChainURI'));
     // A URL handed to `play` that isn't a recognized media file is treated as an
     // interactive web page: the FF1 renders unknown URLs in a sandboxed iframe,
     // so an explicit caller hint aside, "unknown" means web, not static image.
     // This routes such items through the open-ended (no-duration) timing path
     // instead of the static-image default.
     const mimeHint = options.mimeType || (detectMimeType(sourceUrl) === '' ? 'text/html' : undefined);
-    return applyItemTiming(item, { sourceUrl, mimeType: mimeHint }, duration);
+    applyTimingToItemBuilder(itemBuilder, { sourceUrl, mimeType: mimeHint }, duration, buildDefaultDisplay());
+    return itemBuilder.build();
 }
 module.exports = {
     convertTokenToDP1Item,
@@ -682,5 +657,8 @@ module.exports = {
     isTimeBasedMedia,
     isInteractiveWeb,
     applyItemTiming,
+    resolveItemTiming,
+    applyTimingToItemBuilder,
     buildUrlItem,
+    buildDefaultDisplay,
 };

package/dist/src/utilities/ref-manifest.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Inline Ref Manifest construction for DP-1 playlist items.
+ *
+ * DP-1 Playlist Extension §3.6 lets an item carry a complete Ref Manifest
+ * inline instead of behind a `ref` URL. That matters here because ff-cli has
+ * nowhere to host a manifest document: it emits a playlist file and hands it
+ * to an FF1 device. Before dp1-js 2.3.0 there was no item-level home for the
+ * artwork description, artist, or still image the indexer already returns, so
+ * `nft-indexer.js` discarded all three. Inline manifests give them a home.
+ *
+ * This module is a leaf on purpose: it imports only `dp1-js` and the logger,
+ * never another `src/utilities/` module. `nft-indexer.js` already requires
+ * `playlist-builder.js`, so putting this logic in either of them would make
+ * the require graph a question that has to be re-answered on every edit.
+ *
+ * Integrity note: an inline manifest is covered by the playlist signature, so
+ * unlike a ref-fetched manifest it carries no `refHash`. Everything written
+ * here therefore ends up inside a signed document — which is why the mapping
+ * below refuses to synthesize fields the CLI cannot actually substantiate.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInlineManifestForToken = buildInlineManifestForToken;
+const node_crypto_1 = require("node:crypto");
+const dp1_js_1 = require("dp1-js");
+const logger = __importStar(require("../logger"));
+/**
+ * DP-1 version this CLI emits. RefManifestBuilder falls back to "0.1.0" when
+ * `refVersion` is unset, which would contradict the `dpVersion: 1.1.0`
+ * envelope playlist-builder.js builds around these items.
+ */
+const REF_VERSION = '1.1.0';
+/**
+ * The Feral File indexer exposes no language tag on `display`, and the schema
+ * requires a locale. Every string we map comes from that one untagged source,
+ * so "en" is an assumption, not an observation. If the indexer ever returns a
+ * language, thread it through rather than widening this constant.
+ */
+const DEFAULT_LOCALE = 'en';
+/**
+ * One CLI invocation stamps one manifest timestamp.
+ *
+ * Freezing at module load keeps a 500-token `build` from writing 500 different
+ * clocks across items of the same playlist, and keeps two runs byte-diffable
+ * except for this single value. The playlist envelope's own `created` already
+ * varies the same way (playlist-builder.js pins it only under the test-only
+ * deterministicMode). This assumes a short-lived process: do not reuse this
+ * module from a daemon without threading `created` in explicitly.
+ */
+const MANIFEST_CREATED_AT = new Date().toISOString();
+/** Namespace prefix keeping manifest ids from aliasing PlaylistItem ids. */
+const ID_NAMESPACE = 'dp1:ref-manifest:v1';
+/** uuidFromSeed formats a sha256 digest UUID-style, mirroring nft-indexer.js. */
+function uuidFromSeed(seed) {
+    const hash = (0, node_crypto_1.createHash)('sha256').update(seed).digest('hex');
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        hash.slice(12, 16),
+        hash.slice(16, 20),
+        hash.slice(20, 32),
+    ].join('-');
+}
+/** text trims a possibly-absent value down to a non-empty string. */
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * resolveStillUri picks the still image that belongs in `metadata.thumbnails`.
+ *
+ * Returns an empty string unless the candidate is genuinely additional
+ * information. Three rejections, each for a distinct reason:
+ *
+ *   - equal to `sourceUrl`: for a static token `image.url` IS the source
+ *     (see getBestMediaUrl in nft-indexer.js), so a thumbnail identical to it
+ *     is pure duplication inside a signed payload;
+ *   - `data:`: both item factories already refuse data-URI sources, and
+ *     inlining base64 into every playlist would dwarf the playlist itself;
+ *   - anything not http(s): `Thumbnail.uri` carries `format: "uri"`, and an
+ *     `ipfs://` value is not resolvable by the FF1 display path today.
+ */
+function resolveStillUri(token, sourceUrl) {
+    const image = token.image;
+    const candidate = typeof image === 'string' ? text(image) : text(image?.thumbnail) || text(image?.url);
+    if (!candidate || candidate === sourceUrl) {
+        return '';
+    }
+    if (!candidate.startsWith('http://') && !candidate.startsWith('https://')) {
+        return '';
+    }
+    return candidate;
+}
+/**
+ * buildInlineManifestForToken builds the Ref Manifest for one playlist item,
+ * or returns undefined when the token carries nothing worth carrying.
+ *
+ * Emission threshold: at least one of description, artists, or thumbnails must
+ * survive normalization. `title` deliberately does NOT count — it is already a
+ * first-class PlaylistItem field, so a title-only manifest adds payload to
+ * every FF1 transfer and every signed envelope while telling a consumer
+ * nothing new. The threshold is expressed here, once, so the item factories
+ * stay a two-line call and cannot drift apart.
+ *
+ * Deliberately not mapped, each for a reason that should survive future edits:
+ *   - `creditLine`: the schema calls it copyright and credit information. The
+ *     CLI has no such string; deriving one from `token.owner` would assert a
+ *     rights claim it has no basis for, inside a signed document.
+ *   - `tags`: `metadata.attributes` is hard-coded to [] upstream, and NFT
+ *     traits are key/value pairs — flattening them yields garbage like
+ *     ["Blue", "Hat"].
+ *   - `collection`: no Metadata field accepts it, and upstream computes its
+ *     name by splitting the token name on '#' — string surgery, not identity.
+ *   - `owner`: not the artist, not credit, and stale the moment the token
+ *     trades.
+ *   - `controls`: display preferences already live on `item.display`, written
+ *     from the DP-1 §4.1 timing heuristics. Duplicating them here would create
+ *     two sources of truth with no rule for which wins.
+ *   - `i18n`: no localized strings exist anywhere in this pipeline.
+ *
+ * Never throws. A manifest is decoration; nft-indexer.js turns a builder throw
+ * into `{ success: false }`, which the build pipeline counts as a dropped
+ * token — so a malformed thumbnail must not silently shorten a user's
+ * playlist.
+ *
+ * @param token - Token in the internal standard format
+ * @param opts - Resolved item source URL, and an optional created override
+ * @returns A schema-valid RefManifest, or undefined when below the threshold
+ */
+function buildInlineManifestForToken(token, opts = {}) {
+    if (!token || typeof token !== 'object') {
+        return undefined;
+    }
+    const sourceUrl = text(opts.sourceUrl);
+    const title = text(token.name);
+    const description = text(token.description);
+    const artistName = text(token.metadata?.artistName);
+    const stillUri = resolveStillUri(token, sourceUrl);
+    if (!description && !artistName && !stillUri) {
+        return undefined;
+    }
+    try {
+        const metadata = new dp1_js_1.MetadataBuilder();
+        if (title) {
+            metadata.title(title);
+        }
+        if (description) {
+            metadata.description(description);
+        }
+        if (artistName) {
+            metadata.addArtist({ name: artistName });
+        }
+        if (stillUri) {
+            // A plain literal, not ThumbnailBuilder: `w`/`h` became optional in
+            // dp1-js 2.3.0 and we never know the intrinsic pixel dimensions, so the
+            // emitted shape must be exactly { uri } with no undefined-valued keys.
+            metadata.addThumbnail('default', { uri: stillUri });
+        }
+        return new dp1_js_1.RefManifestBuilder()
+            .refVersion(REF_VERSION)
+            .id(manifestId(token, sourceUrl))
+            .created(opts.created ?? MANIFEST_CREATED_AT)
+            .locale(DEFAULT_LOCALE)
+            .metadata(metadata)
+            .build();
+    }
+    catch (error) {
+        logger.debug('[Ref Manifest] Skipping inline manifest:', {
+            contractAddress: token.contractAddress,
+            tokenId: token.tokenId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/**
+ * manifestId derives a stable id from token coordinates.
+ *
+ * The manifest describes the artwork, not one playlist entry, so the id must
+ * be identical across runs and across playlists — it is a cache key. The
+ * namespace prefix is load-bearing: nft-indexer.js derives the PlaylistItem id
+ * from the bare `${contract}-${tokenId}` string, and a consumer keying a
+ * manifest cache must never alias a playlist-item cache.
+ */
+function manifestId(token, sourceUrl) {
+    const contract = text(token.contractAddress);
+    const tokenId = text(String(token.tokenId ?? ''));
+    if (contract && tokenId) {
+        return uuidFromSeed(`${ID_NAMESPACE}:${text(token.chain)}:${contract}:${tokenId}`);
+    }
+    // Off-indexer tokens (caller-supplied objects) have no coordinates; the
+    // source URL is the only stable identity available.
+    return uuidFromSeed(`${ID_NAMESPACE}:src:${sourceUrl}`);
+}

package/docs/EXAMPLES.md

@@ -254,6 +254,10 @@ npm run dev -- play signed.json -d "Living Room Display"
 # Play a hosted DP-1 playlist
 npm run dev -- play "https://cdn.example.com/playlist.json"
 
+# Play a playlist straight from a DP-1 feed server (the URL the feed hands out)
+# Wallet-signed (eip191) documents need --skip-verify until #103 lands
+npm run dev -- play "https://feed.feralfile.com/api/v1/playlists/<slug>" --skip-verify
+
 # Play a media URL directly
 npm run dev -- play "https://example.com/video.mp4"
 

package/docs/PROJECT_SPEC.md

@@ -105,7 +105,7 @@ Based on the code today, the CLI is responsible for:
 - resolving marketplace URLs, on-chain coordinates, and wallet addresses into playlists (`find`)
 - running feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and playback
 - supporting a deterministic build path from structured JSON (`build`)
-- building DP-1 playlist envelopes from NFT metadata or direct media URLs
+- building DP-1 playlist envelopes from NFT metadata or direct media URLs via `dp1-js` document and leaf builders (so constructed playlists stay schema-conformant), including inline Ref Manifests on items that carry indexer metadata
 - validating and verifying playlist structure and signatures
 - signing playlists when a private key is configured
 - publishing validated playlists to configured feed servers
@@ -174,6 +174,29 @@ Today the CLI groups into these workflow areas:
 
 - `ssh enable|disable`
 
+### Inline Ref Manifests
+
+Playlist items carry a full Ref Manifest inline (DP-1 Playlist Extension §3.6)
+rather than behind a `ref` URL, because the CLI emits a playlist file and has
+nowhere to host a manifest document. Behavior worth knowing downstream:
+
+- An item gets a manifest whenever the indexer supplies a description, an
+  artist, or a still image distinct from the item source. A token carrying only
+  a title gets none — the item already has a `title` field, so a title-only
+  manifest would add payload to every device transfer and signed envelope
+  without adding information.
+- Manifest ids are derived from the token's chain, contract, and token id, so
+  they are stable across runs and across playlists — that stable `id` is what
+  identifies the manifest. `created` is frozen once per CLI invocation, so every
+  item in one build shares a single timestamp; it moves between builds, which is
+  expected (see "What determinism does not mean here").
+- Items carry no `ref`. `ref` is a URI to an externally hosted Ref Manifest,
+  and requires `refHash` over HTTPS; a locally built playlist has nowhere to
+  host one, which is the case §3.6 exists to serve. A still image distinct from
+  the source is carried at `inlineManifest.metadata.thumbnails.default.uri`.
+- An inline manifest has no `refHash`; its integrity comes from the playlist
+  signature.
+
 ## Deterministic-first behavior
 
 The CLI is deterministic end to end. There is no natural-language interface; any natural-language layer lives in the user's coding agent, which drives these commands:
@@ -182,6 +205,59 @@ The CLI is deterministic end to end. There is no natural-language interface; any
 - utilities perform the real work and are the source of truth for output correctness
 - invalid or malformed outputs fail validation rather than being passed through
 
+### What determinism does not mean here
+
+It does **not** mean two builds of the same input produce identical bytes or an
+identical signature. Every citation below is from
+[`display-protocol/dp1`](https://github.com/display-protocol/dp1) at core
+v1.1.0, so a reader can check each claim rather than take this section's word
+for it.
+
+**Timestamps are wall-clock, by definition.** The schemas define both creation
+fields as the moment the document was made:
+
+- `core/v1.1.0/schemas/playlist.json` — `created`: *"ISO 8601 timestamp when the
+  playlist was created"*
+- `core/v1.1.0/schemas/ref-manifest.json` — `created`: *"RFC3339 timestamp when
+  the manifest was created"*
+
+Building the same playlist twice creates two documents at two different times,
+so those fields legitimately differ.
+
+**Different bytes therefore mean a different signature, by construction.**
+`core/v1.1.0/spec.md` §7: *"Each signature is computed over the canonical form
+of the entire playlist (excluding the `signature` and `signatures` fields
+themselves)"*, where *"Canonical form ≡ JSON Canonicalization Scheme (JCS), RFC
+8785"*. A differing `created` changes the canonical bytes, which changes the
+payload hash, which changes the signature. That is the signature reporting what
+actually happened — not a defect to engineer away.
+
+**Identity is carried by `id`, not by bytes.**
+`core/v1.1.0/schemas/ref-manifest.json` describes `id` as *"Unique identifier
+for the manifest (for caching)"*, echoed in the envelope example at
+`core/v1.1.0/ref-manifest.md` §3: `"id": "ref-7c3d", // unique identifier (for
+caching)`. Two manifests sharing an `id` are the same manifest. This CLI derives
+manifest ids from token coordinates precisely so identity stays stable while
+timestamps move.
+
+**DP-1 states no reproducible-build requirement.** Searching `core/v1.1.0/spec.md`
+and `core/v1.1.0/ref-manifest.md` for reproducibility language turns up the word
+"deterministic" in exactly two places, neither about build-time byte stability:
+
+- `spec.md` §5, *"Deterministic Reproduction (`repro`)"* — reproducing the
+  **rendering** of code-based artwork, via `engineVersion`, `seed`,
+  `assetsSHA256`, and `frameHash`.
+- `ref-manifest.md` §2 Goals, *"Deterministic merging: predictable behavior
+  across devices and players"* — the **merge order** in §7 (player defaults →
+  playlist defaults → `ref.controls` → runtime overrides).
+
+Neither imposes byte-for-byte stability across builds, and no schema field
+requires `created` to be immutable across regenerations of a document.
+
+`buildDP1Playlist` accepts `deterministicMode` with `fixedTimestamp` and
+`fixedId`. Those exist to pin the envelope for tests and are not used by any
+command.
+
 ## Trust, protocol, and rights assumptions
 
 Important constraints from the broader FF system:

package/docs/README.md

@@ -12,14 +12,6 @@ npm i -g @feralfile/cli
 
 `npm` and `npx` require **Node.js 22 or newer** (see `package.json` `engines`). When a release raises the Node floor, that is a **breaking** change for Node 18/20 users; the GitHub Release for that version should say so explicitly (see `./RELEASING.md` for maintainer guidance).
 
-## Install (curl)
-
-```bash
-curl -fsSL https://feralfile.com/ff-cli-install | bash
-```
-
-Installs a prebuilt bundle for macOS/Linux. Node.js 22 or newer must still be available in `PATH`; the bundle avoids a global npm install, not the Node runtime requirement.
-
 ## Configure
 
 ```bash
@@ -302,5 +294,5 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 ## Links
 
 - Examples: `./EXAMPLES.md`
-- Release assets: `./RELEASING.md`
+- Releasing: `./RELEASING.md`
 - DP1 spec: `https://github.com/display-protocol/dp1`

package/docs/RELEASING.md

@@ -7,7 +7,7 @@ How releases happen, how to cut one, and what to do when things go sideways.
 1. **Bump `package.json` version** on `main` (or via a `chore: bump version to X.Y.Z` PR — the project has used both patterns).
 2. **Push to `main`** so the tag created in step 3 points at the bump commit.
 3. **Create a GitHub Release** with the tag equal to the version (e.g. tag `1.2.0` → `"version": "1.2.0"`). Use `gh release create 1.2.0 --title "v1.2.0" --notes "..."` or the web UI.
-4. **The `release.yml` workflow fires automatically**, verifies tag == `package.json` version, runs CI, publishes to npm via OIDC, builds binary assets, uploads them to the release, and verifies the package landed on npm.
+4. **The `release.yml` workflow fires automatically**, verifies tag == `package.json` version, runs CI, publishes to npm via OIDC, and verifies the package landed on npm.
 
 That's it. No tokens, no manual `npm publish`. The whole thing takes ~4 minutes end-to-end.
 
@@ -45,35 +45,12 @@ You will probably never do this again for `@feralfile/cli`, but if you ever publ
 ## GitHub Actions workflows
 
 - **`ci.yml`** — formatting, lint, tests, build on Node 22 across ubuntu/macos/windows. Called by `release.yml` and runs on PRs / pushes to `main`.
-- **`build.yml`** — builds prebuilt binaries (macOS/Linux/Windows) and uploads them as workflow artifacts. Triggered manually or from `release.yml`.
-- **`release.yml`** — orchestrates a release. Verifies version, runs CI, publishes to npm (Node 24 + OIDC + provenance), builds binaries, uploads release assets, verifies the package and assets are live. Triggers on published GitHub Releases or manual dispatch (beta only).
+- **`release.yml`** — orchestrates a release. Verifies version, runs CI, publishes to npm (Node 24 + OIDC + provenance), and verifies the package is live. Triggers on published GitHub Releases or manual dispatch (beta only).
 - **`codeql.yml`**, **`dependency-review.yml`** — security scanning.
 
-## Binary release assets
-
-The curl installer (`https://feralfile.com/ff-cli-install`) downloads prebuilt binaries from GitHub Releases. The release workflow builds and uploads them automatically. To build one locally:
-
-**macOS / Linux:**
-
-```bash
-./scripts/release/build-asset.sh
-```
-
-**Windows (PowerShell):**
-
-```powershell
-.\scripts\release\build-asset-windows.ps1
-```
-
-Produces (names vary by OS/arch):
-
-- `release/ff-cli-darwin-arm64.tar.gz` (and `.sha256`) on macOS
-- `release/ff-cli-linux-x64.tar.gz` (and `.sha256`) on Linux
-- `release/ff-cli-windows-x64.zip` (and `.sha256`) on Windows
-
 ## Release notes and breaking changes
 
-GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm and installers surface it inconsistently, and operators skim release notes first.
+GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm surfaces it inconsistently, and operators skim release notes first.
 
 ### Node.js engine floor (breaking)
 
@@ -89,22 +66,6 @@ GitHub Release text (and any user-facing summary you publish with the version) s
 
 Later releases only need to repeat this block if the engine floor changes again.
 
-## Installer redirect
-
-`https://feralfile.com/ff-cli-install` should redirect to:
-
-```
-https://raw.githubusercontent.com/feral-file/ff-cli/main/scripts/install.sh
-```
-
-The installer script then fetches the release assets from GitHub Releases.
-
-## Environment overrides
-
-- `FF_CLI_VERSION`: overrides the version label in logs
-- `FF_CLI_NODE_VERSION`: Reserved in script headers for future use; current CI, npm `engines`, and release wrappers assume **Node.js 22+** (required by `dp1-js`).
-- `FF_CLI_OUTPUT_DIR`: output directory (default: `./release`)
-
 ## Troubleshooting
 
 ### `404 Not Found - PUT https://registry.npmjs.org/@feralfile%2fcli`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
@@ -58,14 +58,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@napi-rs/keyring": "1.3.0",
     "@feralfile/source-resolver": "^1.0.0",
+    "@napi-rs/keyring": "1.3.0",
     "axios": "^1.6.2",
     "bonjour-service": "^1.3.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "dotenv": "^16.3.1",
-    "dp1-js": "2.0.0",
+    "dp1-js": "2.3.1",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
     "viem": "^2.38.2"