@feralfile/cli 2.0.0 → 2.0.2

package/README.md

@@ -12,13 +12,15 @@ 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 (no Node.js required).
+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.
 
 ## One-off Usage (npx)
 
@@ -42,6 +44,23 @@ ff-cli config init
 ff-cli config validate
 ```
 
+### Non-interactive setup (agents / CI)
+
+`ff-cli setup` is fully scriptable — no TTY required. It runs non-interactively when stdin is not a terminal, or when you pass `-y/--non-interactive`, and takes flags for every step:
+
+```bash
+# Generate a signing key and register a device in one shot, no prompts
+ff-cli setup --non-interactive \
+  --generate-key \
+  --device-host http://192.168.1.50:1111 \
+  --device-name "Living Room"
+
+# Or supply your own key (base64 PKCS#8 DER, 32-byte seed as hex/base64, or PEM)
+ff-cli setup -y --key "<private-key>" --role agent
+```
+
+Device pairing is also scriptable on its own: `ff-cli device add --host http://<ip>:1111 --name <name>` skips mDNS discovery entirely.
+
 ## Find an artwork
 
 `ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or a wallet address into a playable DP-1 playlist. The focus is computational and generative art; PFP collections and pre-ERC-721 contracts have limits noted below.

package/config.json.example

@@ -15,7 +15,7 @@
     }
   ],
   "playlist": {
-    "privateKey": "YOUR_ED25519_PRIVATE_KEY_BASE64_OR_HEX",
+    "privateKey": "YOUR_ED25519_PRIVATE_KEY__base64_PKCS8_DER_recommended__or_32byte_raw_seed_as_hex_or_base64__run_ff-cli_setup_to_generate",
     "role": "agent"
   },
   "ff1Devices": {

package/dist/package.json

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

package/dist/src/commands/find.js

@@ -53,7 +53,7 @@ const fxhash_marketplace_1 = require("../utilities/fxhash-marketplace");
 const neort_marketplace_1 = require("../utilities/neort-marketplace");
 const verse_marketplace_1 = require("../utilities/verse-marketplace");
 const raster_client_1 = require("../utilities/raster-client");
-const ff1_device_1 = require("../utilities/ff1-device");
+const playlist_cast_1 = require("../utilities/playlist-cast");
 // nft-indexer + playlist-builder are still CommonJS; require keeps interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
@@ -444,48 +444,47 @@ async function promptNextAction() {
     throw new Error(`Unrecognized choice: "${answer}". Use P, S, or L.`);
 }
 async function doPlay(playlist, deviceName, skipVerify) {
-    // Match `ff-cli play`'s verification gate: signed playlists are verified
-    // before device delivery; the same surface that play surfaces failures.
-    // `buildDP1Playlist` signs when a playlist private key is configured and
-    // silently continues unsigned otherwise — so when no key is set, the user
-    // sees an actionable error here instead of an unverifiable playlist on
-    // the wall.
+    // Same verify → send gate `ff-cli play` uses, via the shared castPlaylist
+    // helper. `find`'s playlists are already signed by buildDP1Playlist (when a
+    // key is configured), so no signing is requested here — an unsigned one
+    // fails the verify gate with an actionable message instead of reaching the
+    // wall unverifiable.
     if (!skipVerify) {
-        const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('../utilities/playlist-verifier')));
         console.log(chalk_1.default.cyan('Verify playlist'));
-        const verifyResult = await verifyPlaylist(playlist);
-        if (!verifyResult.valid) {
-            console.error(chalk_1.default.red('Playlist verification failed:'), verifyResult.error);
-            if (verifyResult.details && verifyResult.details.length > 0) {
-                for (const d of verifyResult.details) {
+    }
+    const result = await (0, playlist_cast_1.castPlaylist)(playlist, { deviceName, skipVerify });
+    if (!result.success) {
+        if (result.stage === 'verify') {
+            console.error(chalk_1.default.red('Playlist verification failed:'), result.error);
+            if (result.details && result.details.length > 0) {
+                for (const d of result.details) {
                     console.error(chalk_1.default.dim(`  ${d.path}: ${d.message}`));
                 }
             }
             console.error(chalk_1.default.dim('  Tip: configure a playlist signing key (config or PLAYLIST_PRIVATE_KEY), ' +
                 'or pass --skip-verify to bypass.'));
-            process.exitCode = 1;
-            return;
         }
+        else {
+            console.error(chalk_1.default.red('Play failed:'), result.error);
+            if (result.deviceDetails) {
+                console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
+            }
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (result.verified) {
         console.log(chalk_1.default.green('✓ Verified\n'));
     }
     console.log(chalk_1.default.blue('Play on FF1'));
-    const result = await (0, ff1_device_1.sendPlaylistToDevice)({ playlist, deviceName });
-    if (result.success) {
-        console.log(chalk_1.default.green('✓ Playing'));
-        if (result.deviceName) {
-            console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
-        }
-        if (result.device) {
-            console.log(chalk_1.default.dim(`  Host: ${result.device}`));
-        }
-        console.log();
-        return;
+    console.log(chalk_1.default.green('✓ Playing'));
+    if (result.deviceName) {
+        console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
     }
-    console.error(chalk_1.default.red('Play failed:'), result.error);
-    if (result.details) {
-        console.error(chalk_1.default.dim(`  Details: ${result.details}`));
+    if (result.device) {
+        console.log(chalk_1.default.dim(`  Host: ${result.device}`));
     }
-    process.exitCode = 1;
+    console.log();
 }
 async function doPublish(savedPath, serverArg, nonInteractive) {
     console.log(chalk_1.default.blue('Publish to feed'));

package/dist/src/commands/helpers/config-files.js

@@ -17,7 +17,7 @@ async function readConfigFile(configPath) {
 }
 /**
  * Locate an existing config.json. Local (`./config.json`) wins over user
- * (`~/.config/ff1/config.json`). Returns null when neither exists.
+ * (`~/.config/ff-cli/config.json`). Returns null when neither exists.
  */
 async function resolveExistingConfigPath() {
     const { localPath, userPath } = (0, config_1.getConfigPaths)();

package/dist/src/commands/helpers/device-discovery.js

@@ -24,6 +24,8 @@ async function discoverAndSelectDevice(ask, existingDevices, options) {
             ? discoveryResult.error
             : `${discoveryResult.error}.`;
         console.log(chalk_1.default.dim(`mDNS discovery failed: ${errorMessage} Continuing with manual entry.`));
+        console.log(chalk_1.default.dim('  Tip: you can skip discovery entirely with ' +
+            'ff-cli device add --host http://<device-ip>:1111 --name <name>'));
     }
     else if (discoveryResult.error) {
         console.log(chalk_1.default.dim(`mDNS discovery warning: ${discoveryResult.error}`));
@@ -101,6 +103,11 @@ async function discoverAndSelectDevice(ask, existingDevices, options) {
     }
     else if (!discoveryResult.error) {
         console.log(chalk_1.default.dim('No FF1 devices found via mDNS. Continuing with manual entry.'));
+        // mDNS is best-effort and frequently fails across subnets (a common setup
+        // with mesh routers that put wired and Wi-Fi clients on different /24s).
+        // Point users at the reliable fallback.
+        console.log(chalk_1.default.dim('  Tip: mDNS often does not cross subnets. If the device is reachable by IP, ' +
+            'add it directly: ff-cli device add --host http://<device-ip>:1111 --name <name>'));
     }
     // Manual entry fallback
     const idAnswer = await ask('Device ID or host (e.g. ff1-ABCD1234): ');

package/dist/src/commands/play.js

@@ -1,37 +1,4 @@
 "use strict";
-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;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -43,12 +10,8 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../config");
 const playlist_source_1 = require("../utilities/playlist-source");
 const marketplace_url_1 = require("../utilities/marketplace-url");
+const playlist_cast_1 = require("../utilities/playlist-cast");
 const playlist_display_1 = require("./helpers/playlist-display");
-// ff1-device is still CommonJS; require keeps the interop simple.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { sendPlaylistToDevice } = require('../utilities/ff1-device');
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { signPlaylist } = require('../utilities/playlist-signer');
 /**
  * Human label for a discovery input that `play` cannot cast directly.
  *
@@ -59,12 +22,20 @@ const { signPlaylist } = require('../utilities/playlist-signer');
  * can redirect the user instead of silently wrapping, say, an Art Blocks
  * collection *page* as a web item. Returns null for anything `play` should
  * handle itself (plain URLs and file paths parse to null here).
+ *
+ * A recognized-but-`unsupported` result (e.g. a legacy Art Blocks
+ * `/projects/{id}` URL, or an unsupported-chain OpenSea link) is also a
+ * discovery input — it's a marketplace URL, not a playable file — so it is
+ * redirected to `find` too, which surfaces the specific reason.
  */
 function describeDiscoveryInput(source) {
     const parsed = (0, marketplace_url_1.parseFindInput)(source);
-    if (!parsed || parsed.kind === 'unsupported') {
+    if (!parsed) {
         return null;
     }
+    if (parsed.kind === 'unsupported') {
+        return 'a marketplace URL';
+    }
     switch (parsed.kind) {
         case 'token':
             return 'an on-chain token reference';
@@ -118,83 +89,45 @@ exports.playCommand = new commander_1.Command('play')
             ? `${resolved.sourceType}: ${resolved.source}`
             : resolved.source;
         console.log(chalk_1.default.blue('\nPlay on FF1\n'));
-        if (!options.skipVerify) {
-            const playlistConfig = config.playlist;
-            const privateKey = playlistConfig?.privateKey || process.env.PLAYLIST_PRIVATE_KEY;
-            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('../utilities/playlist-verifier')));
-            if (isPlaylistSource) {
-                console.log(chalk_1.default.cyan(`Verify playlist (${sourceLabel})`));
-            }
-            const verifyResult = resolved.kind === 'media'
-                ? await (async () => {
-                    try {
-                        if (!privateKey) {
-                            return {
-                                valid: false,
-                                error: 'Cannot sign playlist for playback: no playlist signing key is configured',
-                            };
-                        }
-                        const signature = await signPlaylist(resolved.playlist, privateKey);
-                        const signedPlaylist = {
-                            ...resolved.playlist,
-                            signature: undefined,
-                            signatures: [signature],
-                        };
-                        const signedVerification = await verifyPlaylist(signedPlaylist);
-                        if (signedVerification.valid) {
-                            resolved.playlist = signedPlaylist;
-                            return { valid: true, playlist: signedPlaylist };
-                        }
-                        return {
-                            valid: false,
-                            error: signedVerification.error,
-                            details: signedVerification.details,
-                        };
-                    }
-                    catch (error) {
-                        return {
-                            valid: false,
-                            error: `Failed to sign playlist for playback: ${error.message}`,
-                        };
-                    }
-                })()
-                : await verifyPlaylist(resolved.playlist);
-            if (!verifyResult.valid) {
-                (0, playlist_display_1.printPlaylistVerificationFailure)({
-                    valid: false,
-                    error: verifyResult.error,
-                    details: verifyResult.details,
-                }, isPlaylistSource ? `source: ${sourceLabel}` : undefined);
-                process.exit(1);
-            }
-            if (resolved.kind === 'media') {
-                console.log(chalk_1.default.green('✓ Signed and verified\n'));
-            }
-            else if (isPlaylistSource) {
-                console.log(chalk_1.default.green('✓ Verified\n'));
-            }
+        if (!options.skipVerify && isPlaylistSource) {
+            console.log(chalk_1.default.cyan(`Verify playlist (${sourceLabel})`));
         }
-        const result = await sendPlaylistToDevice({
-            playlist: resolved.playlist,
+        // A direct media/web URL is wrapped in an unsigned single-item playlist,
+        // so it must be signed before the verify gate; a loaded playlist is sent
+        // as-is. castPlaylist owns the sign → verify → send sequence.
+        const privateKey = config.playlist?.privateKey || process.env.PLAYLIST_PRIVATE_KEY;
+        const result = await (0, playlist_cast_1.castPlaylist)(resolved.playlist, {
             deviceName: options.device,
+            skipVerify: options.skipVerify,
+            requireSignature: resolved.kind === 'media',
+            signingKey: privateKey,
         });
-        if (result.success) {
-            console.log(chalk_1.default.green('✓ Playing'));
-            if (result.deviceName) {
-                console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
+        if (!result.success) {
+            if (result.stage === 'verify') {
+                (0, playlist_display_1.printPlaylistVerificationFailure)({ valid: false, error: result.error, details: result.details }, isPlaylistSource ? `source: ${sourceLabel}` : undefined);
             }
-            if (result.device) {
-                console.log(chalk_1.default.dim(`  Host: ${result.device}`));
+            else if (result.stage === 'sign') {
+                console.error(chalk_1.default.red(`\n${result.error}`));
             }
-            console.log();
-        }
-        else {
-            console.error(chalk_1.default.red('\nPlay failed:'), result.error);
-            if (result.details) {
-                console.error(chalk_1.default.dim(`  Details: ${result.details}`));
+            else {
+                console.error(chalk_1.default.red('\nPlay failed:'), result.error);
+                if (result.deviceDetails) {
+                    console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
+                }
             }
             process.exit(1);
         }
+        if (result.verified) {
+            console.log(chalk_1.default.green(result.signed ? '✓ Signed and verified\n' : '✓ Verified\n'));
+        }
+        console.log(chalk_1.default.green('✓ Playing'));
+        if (result.deviceName) {
+            console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
+        }
+        if (result.device) {
+            console.log(chalk_1.default.dim(`  Host: ${result.device}`));
+        }
+        console.log();
     }
     catch (error) {
         if ((0, playlist_source_1.isPlaylistSourceUrl)(source)) {

package/dist/src/commands/setup.js

@@ -10,59 +10,103 @@ const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = require("fs");
 const device_lookup_1 = require("../utilities/device-lookup");
 const device_upsert_1 = require("../utilities/device-upsert");
+const device_normalize_1 = require("../utilities/device-normalize");
 const config_files_1 = require("./helpers/config-files");
 const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
 const config_placeholders_1 = require("../utilities/config-placeholders");
+const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+/** Generate a fresh Ed25519 signing key as base64 PKCS#8 DER (the recommended form). */
+function generateSigningKeyBase64() {
+    const keyPair = crypto_1.default.generateKeyPairSync('ed25519');
+    return keyPair.privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+}
 exports.setupCommand = new commander_1.Command('setup')
     .description('Guided setup for config, signing key, and device')
-    .action(async () => {
+    .option('-y, --non-interactive', 'Run without prompts (for agents/CI); uses flags and safe defaults. Auto-enabled when stdin is not a TTY.')
+    .option('--key <privateKey>', 'Signing key material (base64 PKCS#8 DER, 32-byte seed as hex/base64, or PEM)')
+    .option('--generate-key', 'Generate a new Ed25519 signing key')
+    .option('--role <role>', `Signing role (${playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ')})`)
+    .option('--device-host <host>', 'FF1 device host, e.g. http://192.168.1.50:1111 (skips mDNS discovery)')
+    .option('--device-name <name>', 'Friendly name for the device')
+    .action(async (options) => {
+    // Treat a non-TTY stdin as non-interactive: agents driving the CLI cannot
+    // answer prompts, and the report shows feeding stdin to the prompts does not
+    // work. The explicit flag forces it even on a TTY.
+    const nonInteractive = Boolean(options.nonInteractive) || !process.stdin.isTTY;
     let prompt = null;
+    // Lazily open the prompt so non-interactive runs never touch stdin.
+    const getAsk = () => (prompt ??= (0, prompt_1.createPrompt)()).ask;
     try {
         const { path: configPath, created } = await (0, config_files_1.ensureConfigFile)();
         if (created) {
             console.log(chalk_1.default.green(`Created ${configPath}`));
         }
         const config = await (0, config_files_1.readConfigFile)(configPath);
-        console.log(chalk_1.default.blue('\nff-cli setup\n'));
-        prompt = (0, prompt_1.createPrompt)();
-        const ask = prompt.ask;
+        console.log(chalk_1.default.blue(`\nff-cli setup${nonInteractive ? ' (non-interactive)' : ''}\n`));
         const currentKey = config.playlist?.privateKey || '';
         const currentRole = config.playlist?.role || '';
         let signingKey = currentKey;
         let signingRole = currentRole;
-        if ((0, config_files_1.isMissingConfigValue)(currentKey)) {
-            const keyPair = crypto_1.default.generateKeyPairSync('ed25519');
-            signingKey = keyPair.privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+        if (nonInteractive) {
+            // Key precedence: explicit --key, then --generate-key, then keep an
+            // existing usable key, otherwise generate one so signing works.
+            if (options.key) {
+                // Validate eagerly so a bad key fails here with a clear message rather
+                // than later inside dp1-js during signing.
+                try {
+                    (0, ed25519_key_derive_1.parsePlaylistPrivateKeyToKeyObject)(options.key);
+                }
+                catch (error) {
+                    throw new Error(`Invalid --key: ${error.message}. ` +
+                        'Expected base64 PKCS#8 DER, a 32-byte raw seed as hex/base64, or PEM.');
+                }
+                signingKey = options.key;
+            }
+            else if (options.generateKey || (0, config_files_1.isMissingConfigValue)(currentKey)) {
+                signingKey = generateSigningKeyBase64();
+                console.log(chalk_1.default.dim('Generated a new Ed25519 signing key.'));
+            }
         }
         else {
-            const keepKey = await (0, prompt_1.promptYesNo)(ask, 'Keep existing signing key?', true);
-            if (!keepKey) {
-                const keyAnswer = await ask('Paste signing key (base64 or hex), or leave blank to regenerate: ');
-                if (keyAnswer) {
-                    signingKey = keyAnswer;
-                }
-                else {
-                    const keyPair = crypto_1.default.generateKeyPairSync('ed25519');
-                    signingKey = keyPair.privateKey
-                        .export({ format: 'der', type: 'pkcs8' })
-                        .toString('base64');
+            if ((0, config_files_1.isMissingConfigValue)(currentKey)) {
+                signingKey = generateSigningKeyBase64();
+            }
+            else {
+                const ask = getAsk();
+                const keepKey = await (0, prompt_1.promptYesNo)(ask, 'Keep existing signing key?', true);
+                if (!keepKey) {
+                    const keyAnswer = await ask('Paste signing key (base64 or hex), or leave blank to regenerate: ');
+                    signingKey = keyAnswer || generateSigningKeyBase64();
                 }
             }
         }
         if (signingKey) {
-            const roleHint = playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ');
-            while (true) {
-                const roleAnswer = await ask(`Signing role (${roleHint}) [${currentRole || 'agent'}]: `);
+            if (nonInteractive) {
+                // Role precedence: --role, then existing role, then 'agent'.
                 try {
-                    signingRole = (0, playlist_signing_role_1.resolveDp1PlaylistSigningRole)(roleAnswer, signingRole || 'agent');
-                    break;
+                    signingRole = (0, playlist_signing_role_1.resolveDp1PlaylistSigningRole)(options.role, signingRole || 'agent');
                 }
                 catch (error) {
-                    console.log(chalk_1.default.red(error.message));
-                    if (!roleAnswer.trim()) {
-                        console.log(chalk_1.default.dim('Enter one of the supported roles above, or fix the stored value.'));
+                    throw new Error(`Invalid --role: ${error.message} ` +
+                        `Supported roles: ${playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ')}.`);
+                }
+            }
+            else {
+                const ask = getAsk();
+                const roleHint = playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ');
+                while (true) {
+                    const roleAnswer = await ask(`Signing role (${roleHint}) [${currentRole || 'agent'}]: `);
+                    try {
+                        signingRole = (0, playlist_signing_role_1.resolveDp1PlaylistSigningRole)(roleAnswer, signingRole || 'agent');
+                        break;
+                    }
+                    catch (error) {
+                        console.log(chalk_1.default.red(error.message));
+                        if (!roleAnswer.trim()) {
+                            console.log(chalk_1.default.dim('Enter one of the supported roles above, or fix the stored value.'));
+                        }
                     }
                 }
             }
@@ -81,57 +125,84 @@ exports.setupCommand = new commander_1.Command('setup')
         if (existingDevices.length > 0) {
             console.log(chalk_1.default.dim(`\nConfigured devices: ${existingDevices.map((d) => d.name || d.host).join(', ')}`));
         }
-        const selection = await (0, device_discovery_1.discoverAndSelectDevice)(ask, existingDevices, { allowSkip: true });
-        if (selection.hostValue) {
-            // Prefer the already-stored label so re-running setup (or re-adding a device
-            // that returned on a new IP) doesn't clobber the friendly name.
-            const existingEntry = (0, device_lookup_1.findExistingDeviceEntry)(existingDevices, selection.hostValue, selection.discoveredName, selection.discoveredId, selection.discoveredAddresses);
-            const existingIndex = existingEntry
-                ? existingDevices.findIndex((d) => d === existingEntry)
-                : -1;
-            const existingName = existingEntry?.name || '';
-            const defaultName = existingName || selection.discoveredName || 'art-computer';
-            const namePrompt = defaultName !== 'art-computer'
-                ? `Device name (kitchen, office, etc.) [${defaultName}]: `
-                : 'Device name (kitchen, office, etc.): ';
-            const nameAnswer = await ask(namePrompt);
-            let deviceName = nameAnswer || defaultName || 'art-computer';
-            // Same name-collision guard as `device add`: reject names that would
-            // clobber a different device entry. Only fires when existingIndex !== -1
-            // (we know the row); when existingIndex === -1, a same-name entry is the
-            // case-3 migration path.
-            const setupNameConflict = existingIndex !== -1
-                ? existingDevices.find((d, i) => d.name === deviceName && i !== existingIndex)
-                : undefined;
-            if (setupNameConflict) {
-                console.log(chalk_1.default.yellow(`"${deviceName}" is already used by another device. Please choose a different name.`));
-                const retryAnswer = await ask('Device name: ');
-                deviceName = retryAnswer || 'art-computer';
-                const retryConflict = existingIndex !== -1
+        if (nonInteractive) {
+            // Non-interactive device step: only act when a host is supplied. mDNS
+            // discovery is interactive and unreliable across subnets, so we never
+            // run it here — agents should pass --device-host.
+            if (options.deviceHost) {
+                const hostValue = (0, device_normalize_1.normalizeDeviceHost)(options.deviceHost);
+                const existingEntry = (0, device_lookup_1.findExistingDeviceEntry)(existingDevices, hostValue, '', undefined, undefined);
+                const existingIndex = existingEntry
+                    ? existingDevices.findIndex((d) => d === existingEntry)
+                    : -1;
+                const deviceName = options.deviceName || existingEntry?.name || 'art-computer';
+                const result = (0, device_upsert_1.upsertDevice)(existingDevices, { name: deviceName, host: hostValue }, existingIndex !== -1 ? existingIndex : undefined);
+                console.log(chalk_1.default.dim(`${result.updated ? 'Updated' : 'Added'} device: ${deviceName}`));
+                config.ff1Devices = { devices: result.devices };
+            }
+            else {
+                config.ff1Devices = { devices: existingDevices };
+                if (existingDevices.length === 0) {
+                    console.log(chalk_1.default.dim('No device configured. Add one with: ff-cli device add --host http://<device-ip>:1111 --name <name>'));
+                }
+            }
+        }
+        else {
+            const ask = getAsk();
+            const selection = await (0, device_discovery_1.discoverAndSelectDevice)(ask, existingDevices, { allowSkip: true });
+            if (selection.hostValue) {
+                // Prefer the already-stored label so re-running setup (or re-adding a device
+                // that returned on a new IP) doesn't clobber the friendly name.
+                const existingEntry = (0, device_lookup_1.findExistingDeviceEntry)(existingDevices, selection.hostValue, selection.discoveredName, selection.discoveredId, selection.discoveredAddresses);
+                const existingIndex = existingEntry
+                    ? existingDevices.findIndex((d) => d === existingEntry)
+                    : -1;
+                const existingName = existingEntry?.name || '';
+                const defaultName = existingName || selection.discoveredName || 'art-computer';
+                const namePrompt = defaultName !== 'art-computer'
+                    ? `Device name (kitchen, office, etc.) [${defaultName}]: `
+                    : 'Device name (kitchen, office, etc.): ';
+                const nameAnswer = await ask(namePrompt);
+                let deviceName = nameAnswer || defaultName || 'art-computer';
+                // Same name-collision guard as `device add`: reject names that would
+                // clobber a different device entry. Only fires when existingIndex !== -1
+                // (we know the row); when existingIndex === -1, a same-name entry is the
+                // case-3 migration path.
+                const setupNameConflict = existingIndex !== -1
                     ? existingDevices.find((d, i) => d.name === deviceName && i !== existingIndex)
                     : undefined;
-                if (retryConflict) {
-                    console.log(chalk_1.default.yellow(`"${deviceName}" is also taken. Skipping device.`));
-                    config.ff1Devices = { devices: existingDevices };
-                    await fs_1.promises.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
-                    return;
+                if (setupNameConflict) {
+                    console.log(chalk_1.default.yellow(`"${deviceName}" is already used by another device. Please choose a different name.`));
+                    const retryAnswer = await ask('Device name: ');
+                    deviceName = retryAnswer || 'art-computer';
+                    const retryConflict = existingIndex !== -1
+                        ? existingDevices.find((d, i) => d.name === deviceName && i !== existingIndex)
+                        : undefined;
+                    if (retryConflict) {
+                        console.log(chalk_1.default.yellow(`"${deviceName}" is also taken. Skipping device.`));
+                        config.ff1Devices = { devices: existingDevices };
+                        await fs_1.promises.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+                        return;
+                    }
                 }
+                const result = (0, device_upsert_1.upsertDevice)(existingDevices, {
+                    name: deviceName,
+                    host: selection.hostValue,
+                    id: selection.discoveredId,
+                    addresses: selection.discoveredAddresses,
+                }, existingIndex !== -1 ? existingIndex : undefined);
+                console.log(chalk_1.default.dim(`${result.updated ? 'Updated' : 'Added'} device: ${deviceName}`));
+                config.ff1Devices = { devices: result.devices };
+            }
+            else if (existingDevices.length > 0) {
+                config.ff1Devices = { devices: existingDevices };
             }
-            const result = (0, device_upsert_1.upsertDevice)(existingDevices, {
-                name: deviceName,
-                host: selection.hostValue,
-                id: selection.discoveredId,
-                addresses: selection.discoveredAddresses,
-            }, existingIndex !== -1 ? existingIndex : undefined);
-            console.log(chalk_1.default.dim(`${result.updated ? 'Updated' : 'Added'} device: ${deviceName}`));
-            config.ff1Devices = { devices: result.devices };
-        }
-        else if (existingDevices.length > 0) {
-            config.ff1Devices = { devices: existingDevices };
         }
         await fs_1.promises.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
-        prompt.close();
-        prompt = null;
+        if (prompt) {
+            prompt.close();
+            prompt = null;
+        }
         console.log(chalk_1.default.green('\nSetup complete'));
         console.log(chalk_1.default.dim(`   Config: ${configPath}`));
         const hasSigningKey = !(0, config_files_1.isMissingConfigValue)(config.playlist?.privateKey || '');

package/dist/src/config.js

@@ -17,39 +17,10 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const playlist_signing_role_1 = require("./utilities/playlist-signing-role");
 const config_placeholders_1 = require("./utilities/config-placeholders");
-// One-shot legacy config migration: copy `$XDG_CONFIG_HOME/ff1/config.json` to
-// `$XDG_CONFIG_HOME/ff-cli/config.json` on first read after upgrading from
-// `ff1-cli`. The check is cheap (two fs.existsSync calls) and the
-// `migrationChecked` flag keeps it to one attempt per process.
-//
-// Remove this block after a release cycle once telemetry suggests no remaining
-// users still have only the legacy path populated.
-let migrationChecked = false;
-function migrateLegacyConfigIfNeeded(newUserPath) {
-    if (migrationChecked) {
-        return;
-    }
-    migrationChecked = true;
-    const configBase = process.env.XDG_CONFIG_HOME || path_1.default.join(os_1.default.homedir(), '.config');
-    const legacyUserPath = path_1.default.join(configBase, 'ff1', 'config.json');
-    if (!fs_1.default.existsSync(legacyUserPath) || fs_1.default.existsSync(newUserPath)) {
-        return;
-    }
-    try {
-        fs_1.default.mkdirSync(path_1.default.dirname(newUserPath), { recursive: true });
-        fs_1.default.copyFileSync(legacyUserPath, newUserPath);
-        console.log(`Migrated config from ${legacyUserPath} to ${newUserPath}`);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn(`Warning: Failed to migrate legacy config from ${legacyUserPath}: ${message}`);
-    }
-}
 function getConfigPaths() {
     const localPath = path_1.default.join(process.cwd(), 'config.json');
     const configBase = process.env.XDG_CONFIG_HOME || path_1.default.join(os_1.default.homedir(), '.config');
     const userPath = path_1.default.join(configBase, 'ff-cli', 'config.json');
-    migrateLegacyConfigIfNeeded(userPath);
     return { localPath, userPath };
 }
 /**
@@ -301,16 +272,21 @@ async function createSampleConfig(targetPath) {
     if (fs_1.default.existsSync(configPath)) {
         throw new Error('config.json already exists');
     }
-    // Look for config.json.example in the package directory
-    // When compiled, this file is in dist/src/config.js
-    // The template is at the package root: ../../config.json.example
+    // Look for config.json.example across the layouts we ship in:
+    //  - cwd: running from a source checkout
+    //  - __dirname/../..: npm install (this file is dist/src/config.js, template
+    //    sits at the package root)
+    //  - __dirname/..: single-file release bundle (this file is bundled into
+    //    lib/ff-cli.js, template sits one level up at the package root)
     const exampleCandidates = [
         path_1.default.join(process.cwd(), 'config.json.example'),
         path_1.default.join(__dirname, '../..', 'config.json.example'),
+        path_1.default.join(__dirname, '..', 'config.json.example'),
     ];
     const examplePath = exampleCandidates.find((candidate) => fs_1.default.existsSync(candidate));
     if (!examplePath) {
-        throw new Error('config.json.example not found. This is likely a package installation issue.');
+        throw new Error('config.json.example not found (likely an incomplete install). ' +
+            'Reinstall with: npm i -g @feralfile/cli');
     }
     const exampleConfig = fs_1.default.readFileSync(examplePath, 'utf-8');
     fs_1.default.mkdirSync(path_1.default.dirname(configPath), { recursive: true });

package/dist/src/utilities/ed25519-key-derive.js

@@ -105,6 +105,20 @@ function parsePlaylistPrivateKeyToKeyObject(material) {
         catch {
             // Continue to other strategies (e.g. hex path may apply for unusual configs)
         }
+        // A 32-byte base64 value is a raw Ed25519 seed (not PKCS#8). The example
+        // config's `_BASE64_OR_HEX` placeholder invites this, so accept it by
+        // wrapping the seed in a PKCS#8 envelope, mirroring the hex-seed path.
+        if (buf.length === 32) {
+            try {
+                const der = ed25519SeedBytesToPkcs8(buf);
+                const key = (0, node_crypto_1.createPrivateKey)({ key: der, format: 'der', type: 'pkcs8' });
+                assertEd25519(key);
+                return key;
+            }
+            catch {
+                // fall through to remaining strategies
+            }
+        }
     }
     if (hexRegex.test(trimmed)) {
         const raw = Buffer.from(trimmed.replace(/^0x/i, ''), 'hex');

package/dist/src/utilities/ff1-device.js

@@ -211,8 +211,14 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
         if (device.apiKey) {
             headers['API-KEY'] = device.apiKey;
         }
-        // Make the API request with bounded retries for transient local network errors.
+        // Make the API request with bounded retries for transient local network
+        // errors, device rate-limiting, and empty/non-JSON bodies (the device can
+        // return an empty response on the first cast after boot).
         let response = null;
+        let responseData = {};
+        // Describes a 2xx response whose body could not be parsed, so the post-loop
+        // handler can report it clearly if every attempt is exhausted.
+        let lastBodyIssue = null;
         for (let attempt = 1; attempt <= SEND_RETRY_ATTEMPTS; attempt += 1) {
             try {
                 response = await fetch(apiUrl, {
@@ -231,6 +237,36 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     await waitForRetry(retryDelay);
                     continue;
                 }
+                // Non-2xx (other than 429 handled above): surface via the post-loop
+                // handler, which re-reads the body as error text.
+                if (!response.ok) {
+                    break;
+                }
+                // 2xx: read the body defensively. An empty or non-JSON body is a known
+                // transient hiccup (commonly the first cast after boot), so retry within
+                // the attempt budget instead of throwing "Unexpected end of JSON input".
+                const bodyText = (await response.text()).trim();
+                if (bodyText === '') {
+                    lastBodyIssue = 'device returned an empty response body';
+                }
+                else {
+                    try {
+                        responseData = JSON.parse(bodyText);
+                        lastBodyIssue = null;
+                        break;
+                    }
+                    catch {
+                        lastBodyIssue = `device returned a non-JSON response body: ${bodyText.slice(0, 200)}`;
+                    }
+                }
+                if (attempt < SEND_RETRY_ATTEMPTS) {
+                    const retryDelay = SEND_RETRY_BASE_DELAY_MS * attempt;
+                    logger.warn(`${lastBodyIssue} (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
+                    response = null;
+                    await waitForRetry(retryDelay);
+                    continue;
+                }
+                // Out of attempts; let the post-loop handler report the body issue.
                 break;
             }
             catch (error) {
@@ -273,8 +309,18 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                 details: errorText,
             };
         }
-        // Parse response
-        const responseData = (await response.json());
+        // 2xx but the body never parsed within the retry budget: report the HTTP
+        // status and what was wrong rather than crashing on a JSON parse error.
+        if (lastBodyIssue) {
+            const deviceLabel = device.name || device.host;
+            logger.error(`Cast to "${deviceLabel}" returned HTTP ${response.status} but ${lastBodyIssue}`);
+            return {
+                success: false,
+                error: `Device "${deviceLabel}" accepted the request (HTTP ${response.status}) but returned no usable response`,
+                details: `${lastBodyIssue}. This is often transient on the first cast after boot — ` +
+                    'wait a few seconds and try again.',
+            };
+        }
         logger.info('Successfully sent playlist to FF1 device');
         logger.debug(`Device response: ${JSON.stringify(responseData)}`);
         return {

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

@@ -534,18 +534,37 @@ function validateDP1Playlist(playlist) {
  * misclassified HTML pages and extensionless URLs as static images, stamping
  * them with a display duration that cut interactive artworks off.)
  *
+ * The extension is taken from the URL *pathname* only — the query string and
+ * fragment are stripped first, so a signed URL like `art.png?sig=a.b` or
+ * `clip.mp4#t=1` still resolves to its real extension instead of parsing `b`
+ * or `mp4#t=1`. Misreading those would mislabel media as undetermined and
+ * (via buildUrlItem) route it through the interactive-web timing path.
+ *
  * @param {string} url - Media or page URL
  * @returns {string} MIME type, or '' when undetermined
  * @example
- * detectMimeType('https://example.com/image.png'); // 'image/png'
- * detectMimeType('https://example.com/art.html');  // 'text/html'
- * detectMimeType('https://example.com/output/abc'); // ''
+ * detectMimeType('https://example.com/image.png');        // 'image/png'
+ * detectMimeType('https://example.com/art.png?sig=a.b');  // 'image/png'
+ * detectMimeType('https://example.com/art.html');         // 'text/html'
+ * detectMimeType('https://example.com/output/abc');       // ''
  */
 function detectMimeType(url) {
     if (!url) {
         return '';
     }
-    const extension = url.split('.').pop()?.toLowerCase().split('?')[0];
+    // Use the pathname only: drop query + fragment so a dot inside `?sig=a.b`
+    // or `#v=1.2` can't masquerade as the file extension.
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        // Not an absolute URL (bare path/filename) — strip fragment then query.
+        pathname = String(url).split('#')[0].split('?')[0];
+    }
+    const lastSegment = pathname.split('/').pop() || '';
+    const dotIndex = lastSegment.lastIndexOf('.');
+    const extension = dotIndex >= 0 ? lastSegment.slice(dotIndex + 1).toLowerCase() : '';
     const mimeTypes = {
         jpg: 'image/jpeg',
         jpeg: 'image/jpeg',

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

@@ -0,0 +1,128 @@
+"use strict";
+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.castPlaylist = castPlaylist;
+// 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');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { sendPlaylistToDevice } = require('./ff1-device');
+/**
+ * Shared "(sign →) verify → send to device" sequence used by `play` and
+ * `find --play`.
+ *
+ * This is the single source of truth for getting a playlist onto an FF1: the
+ * verification gate, the synthesized-media auto-sign (rebuilding the
+ * `signatures[]` envelope), and the device transport. Callers own their
+ * console output and map the returned `stage`/`error` to their own messages —
+ * keeping delivery behavior consistent without coupling the two commands'
+ * UX. Previously this logic was duplicated across `play`, `find`, and the
+ * (now-removed) chat send path, and drifted between them.
+ */
+async function castPlaylist(playlist, options = {}) {
+    let current = playlist;
+    let signed = false;
+    let verified = false;
+    if (!options.skipVerify) {
+        if (options.requireSignature) {
+            if (!options.signingKey) {
+                return {
+                    success: false,
+                    playlist: current,
+                    signed: false,
+                    verified: false,
+                    stage: 'sign',
+                    error: 'Cannot sign playlist for playback: no playlist signing key is configured',
+                };
+            }
+            try {
+                const signature = await signPlaylist(current, options.signingKey);
+                current = {
+                    ...current,
+                    signature: undefined,
+                    signatures: [signature],
+                };
+                signed = true;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    playlist: current,
+                    signed: false,
+                    verified: false,
+                    stage: 'sign',
+                    error: `Failed to sign playlist for playback: ${error.message}`,
+                };
+            }
+        }
+        const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
+        const verifyResult = await verifyPlaylist(current);
+        if (!verifyResult.valid) {
+            return {
+                success: false,
+                playlist: current,
+                signed,
+                verified: false,
+                stage: 'verify',
+                error: verifyResult.error,
+                details: verifyResult.details,
+            };
+        }
+        verified = true;
+    }
+    const sendResult = await sendPlaylistToDevice({
+        playlist: current,
+        deviceName: options.deviceName,
+    });
+    if (sendResult.success) {
+        return {
+            success: true,
+            playlist: current,
+            signed,
+            verified,
+            deviceName: sendResult.deviceName,
+            device: sendResult.device,
+        };
+    }
+    return {
+        success: false,
+        playlist: current,
+        signed,
+        verified,
+        stage: 'send',
+        error: sendResult.error,
+        deviceDetails: sendResult.details,
+    };
+}

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

@@ -2,8 +2,63 @@
  * Playlist Signing Utility.
  * Uses the DP-1 v1.1.0 signing contract via the `dp1-js` package.
  */
+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;
+    };
+})();
 const { getPlaylistConfig } = require('../config');
 const { isDp1PlaylistSigningRole } = require('./playlist-signing-role');
+const { parsePlaylistPrivateKeyToKeyObject } = require('./ed25519-key-derive');
+/**
+ * Normalize any supported signing-key encoding to base64 PKCS#8 DER, the form
+ * dp1-js's signer expects. This makes hex seeds, base64 seeds, and PEM work for
+ * signing (not just base64 PKCS#8), and replaces dp1-js's cryptic OpenSSL error
+ * (e.g. "header too long") with actionable guidance when the key is malformed.
+ *
+ * @param {string} material - Raw key string from config or --key
+ * @returns {string} base64-encoded PKCS#8 DER Ed25519 private key
+ */
+function normalizeSigningKeyToBase64Pkcs8(material) {
+    let keyObject;
+    try {
+        keyObject = parsePlaylistPrivateKeyToKeyObject(material);
+    }
+    catch (error) {
+        throw new Error(`Invalid Ed25519 signing key: ${error.message}. Provide a base64 PKCS#8 DER key ` +
+            '(recommended), a 32-byte raw seed as hex or base64, or a PEM key. ' +
+            'Run `ff-cli setup` to generate one.');
+    }
+    return keyObject.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+}
 /**
  * Sign a playlist using the DP-1 signing API.
  * The signed payload excludes any pre-existing signature fields so the output
@@ -33,8 +88,9 @@ async function signPlaylist(playlist, privateKeyBase64, roleOverride) {
         const raw = Buffer.from(JSON.stringify(playlistToSign));
         const config = getPlaylistConfig();
         const role = resolvePlaylistSigningRole(roleOverride || config.role);
+        const normalizedKey = normalizeSigningKeyToBase64Pkcs8(privateKey);
         if (typeof dp1.SignMultiEd25519 === 'function') {
-            return dp1.SignMultiEd25519(raw, privateKey, role, currentTimestamp());
+            return dp1.SignMultiEd25519(raw, normalizedKey, role, currentTimestamp());
         }
         throw new Error('dp1-js does not expose SignMultiEd25519');
     }
@@ -162,11 +218,15 @@ async function buildSignedPlaylistEnvelope(playlist, privateKey, dp1, role) {
     const playlistToSign = { ...playlist };
     delete playlistToSign.signature;
     delete playlistToSign.signatures;
+    // Normalize to base64 PKCS#8 DER so any supported key encoding (hex/base64
+    // seed, PEM) works and a malformed key surfaces a clear error instead of
+    // dp1-js's cryptic OpenSSL ASN.1 failure ("header too long" / "wrong tag").
+    const normalizedKey = normalizeSigningKeyToBase64Pkcs8(privateKey);
     const existingSignatures = Array.isArray(playlist.signatures)
         ? playlist.signatures.filter((entry) => Boolean(entry))
         : [];
     if (typeof dp1.SignMultiEd25519 === 'function') {
-        const signature = await dp1.SignMultiEd25519(Buffer.from(JSON.stringify(playlistToSign)), privateKey, role, currentTimestamp());
+        const signature = await dp1.SignMultiEd25519(Buffer.from(JSON.stringify(playlistToSign)), normalizedKey, role, currentTimestamp());
         return {
             ...playlist,
             signature: undefined,
@@ -195,9 +255,13 @@ async function verifySignedPlaylistEnvelope(signedPlaylist, dp1) {
     }
     return { valid: true };
 }
-/** Loads `dp1-js`; env overrides are not supported (see playlist-verifier). */
+/**
+ * Loads `dp1-js`; env overrides are not supported (see playlist-verifier).
+ * Uses dynamic `import()` so the single-file release bundle inlines dp1-js
+ * instead of leaving a runtime require that can't resolve.
+ */
 async function loadDp1() {
-    return require('dp1-js');
+    return Promise.resolve().then(() => __importStar(require('dp1-js')));
 }
 function currentTimestamp() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');

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

@@ -47,7 +47,6 @@ exports.verifyPlaylistFile = verifyPlaylistFile;
 exports.printVerificationResult = printVerificationResult;
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
-const module_1 = require("module");
 /**
  * Cryptographically verify a playlist via dp1-js (after parsing succeeds).
  *
@@ -155,10 +154,15 @@ async function parseDp1Playlist(playlist) {
  * Loads the published DP-1 implementation bundled with the CLI (`dp1-js`).
  * Local checkout overrides via environment are intentionally unsupported so
  * resolution stays deterministic across machines and CI.
+ *
+ * Uses a dynamic `import()` (not `createRequire`) so the single-file release
+ * bundle inlines dp1-js: esbuild can follow `import('dp1-js')` and pull the
+ * module into the bundle, whereas a `createRequire(__filename)` require escapes
+ * bundling and fails at runtime with "Cannot find module 'dp1-js'". The import
+ * stays lazy, so dp1-js's transitive deps don't load on unrelated commands.
  */
 async function loadDp1() {
-    const require = (0, module_1.createRequire)(__filename);
-    return require('dp1-js');
+    return (await Promise.resolve().then(() => __importStar(require('dp1-js'))));
 }
 /**
  * Verify playlist file

package/dist/src/utilities/raster-client.js

@@ -226,8 +226,10 @@ async function listArtworkTokens(artworkId, options = {}) {
             contractAddress: raw.contractAddress,
             tokenId: raw.tokenId,
             mediaUrl: raw.media?.contentUrl ?? null,
-            // Prefer a real MIME (`contentType`) when Raster populates it; today it
-            // is usually empty, so fall back to the category-prefixed `previewType`.
+            // Prefer the real MIME (`contentType`); today it is usually empty, so we
+            // fall back to `previewType` as a last resort. NOTE: previewType only
+            // describes the preview encoding, not the work, so this fallback can
+            // misclassify (see the mediaType doc comment above). Tracked for revisit.
             mediaType: raw.media?.contentType || raw.media?.previewType || null,
         });
     }

package/docs/CONFIGURATION.md

@@ -36,32 +36,39 @@ Optional settings used where headless/browser‑like behavior is needed.
 
 Used for signing DP‑1 playlists.
 
-- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`. `play` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `send` and `publish` verify before delivery or upload and reject unsigned or broken playlists.
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`. `play` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `play` and `publish` verify before delivery or upload and reject unsigned or broken playlists.
 
-  **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) pass the private key string through to **`dp1-js`** (`SignMultiEd25519`) without an extra decoding step in ff-cli. `dp1-js` recognizes **hex** (optional `0x`) or **base64** encodings of the PKCS#8 DER blob produced by the OpenSSL examples below, then loads the key for Ed25519. Use those formats; ff-cli does not add a separate normalizer ahead of the library.
+  **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) accept the private key in any of these encodings:
+
+  - **base64 PKCS#8 DER** — recommended; what `ff-cli setup` generates.
+  - **32-byte raw Ed25519 seed** as **hex** (optional `0x`) or **base64**.
+  - **PEM** (`-----BEGIN PRIVATE KEY-----`).
+  - **PKCS#8 DER as hex**.
+
+  ff-cli normalizes whichever form you supply to base64 PKCS#8 DER before handing it to **`dp1-js`** (`SignMultiEd25519`). A malformed key fails with an actionable message (e.g. _"Invalid Ed25519 signing key … run `ff-cli setup` to generate one"_) instead of dp1-js's cryptic OpenSSL ASN.1 error (`header too long` / `wrong tag`).
 
 - `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`).
 
 ### Generate an Ed25519 private key
 
-You can generate a key locally. The CLI accepts either base64 (preferred) or hex
+The simplest path is `ff-cli setup`, which generates a key for you (base64 PKCS#8 DER) and writes it to your config. To generate one yourself:
 
-OpenSSL (recommended):
+OpenSSL (recommended — produces a PKCS#8 DER key):
 
 ```bash
-# Base64 (preferred)
+# Base64 PKCS#8 DER (recommended)
 openssl genpkey -algorithm ED25519 -outform DER | base64 | tr -d '\n'
 
-# Hex (alternative)
+# Hex of the same PKCS#8 DER (alternative)
 openssl genpkey -algorithm ED25519 -outform DER | xxd -p -c 256
 ```
 
-Paste either value into `playlist.privateKey`:
+Paste the value into `playlist.privateKey`. Any of these are accepted:
 
-- Hex example (either is valid):
-  - `0xabc123...` (with prefix)
-  - `abc123...` (without prefix)
-- Base64 example: `uQd9m8S...==`
+- **base64 PKCS#8 DER** (recommended): `MC4CAQAwBQYDK2Vw...`
+- **32-byte raw seed** as hex (`0x`-prefixed or not) or base64 — e.g. the bare seed, not the full PKCS#8 blob.
+- **PEM**: a `-----BEGIN PRIVATE KEY-----` block.
+- **PKCS#8 DER as hex**.
 
 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`.
 
@@ -114,6 +121,12 @@ Configure devices you want to play content on.
 
 During `ff-cli setup`, the CLI will attempt local discovery via mDNS (`_ff1._tcp`). If devices are found, you can pick one and the host will be filled in automatically. If discovery returns nothing, setup falls back to manual entry.
 
+> **mDNS is best-effort.** It frequently does not cross subnets — a common case with mesh routers (e.g. eero) that put wired and Wi-Fi clients on different `/24`s. If discovery comes up empty even though the device is reachable by IP, skip it entirely and add the device directly:
+>
+> ```bash
+> ff-cli device add --host http://<device-ip>:1111 --name <name>
+> ```
+
 You can also manage devices independently with:
 
 - `ff-cli device add` – Add a device interactively (with mDNS discovery), or non-interactively with `--host` and `--name`.
@@ -128,6 +141,28 @@ Selection rules when sending:
 - If you omit `-d`, the first configured device is used.
 - If you pass `-d <name>`, the CLI matches the device by `name` (exact match). If not found, you’ll see an error listing available devices.
 
+Device cast contract:
+
+The device exposes a single HTTP endpoint, `POST http://<device>:1111/api/cast`. `ff-cli play` casts a DP-1 playlist with:
+
+```jsonc
+POST http://<device>:1111/api/cast
+Content-Type: application/json
+// API-KEY: <optional, only if the device requires one>
+
+{
+  "command": "displayPlaylist",
+  "request": {
+    "dp1_call": { /* the full signed DP-1 playlist object */ },
+    "intent": { "action": "now_display" }
+  }
+}
+```
+
+The `intent` field is **required** — without it the device returns `{"message":{"ok":false}}` with no further explanation. `dp1_call` may be the playlist inline (as above) or a hosted playlist URL string; ff-cli sends the resolved playlist object.
+
+On the first cast after boot the device may return an empty body. ff-cli retries this automatically and, if it persists, reports a clear "accepted the request but returned no usable response" error rather than crashing on a JSON parse.
+
 Compatibility checks:
 
 - `play` and `ssh` perform a compatibility preflight before sending commands to FF1. The CLI gets the device version by calling `POST /api/cast` with `{ "command": "getDeviceStatus", "request": {} }` and reads `message.installedVersion` from the response.

package/docs/EXAMPLES.md

@@ -261,6 +261,8 @@ npm run dev -- play "https://example.com/video.mp4"
 npm run dev -- play playlist.json --skip-verify
 ```
 
+> **No feed server is required to cast.** A device can play any static, signed DP-1 playlist hosted at a public URL — sign it (`sign`), upload the JSON anywhere that serves it over HTTPS (S3, Supabase Storage, a static host, etc.), then `ff-cli play "<url>"`. The DP-1 Feed server ([Publish to Feed Server](#publish-to-feed-server) below) adds discovery and curation, but is optional for simply playing your own playlists.
+
 ## Publish to Feed Server
 
 Publish validated playlists to a DP-1 feed server for sharing and discovery.

package/package.json

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