@feralfile/cli 2.10.1 → 4.0.0

package/docs/EXAMPLES.md

@@ -18,7 +18,7 @@ npm run dev -- config validate
 
 ## Use with a coding agent
 
-ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) / Codex skill at `skills/ff-control/SKILL.md`. Once installed, ask your agent in plain language ("Get 3 works from reas.eth and play on Living Room", "Build a playlist from this Objkt URL and publish to my feed") and it translates the request into `ff-cli find` or `ff-cli build` and runs the validate → play/publish flow for you.
+ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) / Codex skill at `skills/ff-control/SKILL.md`. Once installed, ask your agent in plain language ("Get 3 works from reas.eth and display on Living Room", "Build a playlist from this Objkt URL and publish to my feed") and it translates the request into `ff-cli find` or `ff-cli build` and runs the validate → display/publish flow for you.
 
 Recommended local install path:
 
@@ -32,19 +32,19 @@ The rest of this doc shows the deterministic commands the skill (or you) drives
 
 ## Find an artwork
 
-`ff-cli find` resolves a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist. Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses.
+`ff-cli find` resolves a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a DP-1 playlist ready to display. Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses.
 
 ```bash
-# Paste a URL and play it on your FF1
-npm run dev -- find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+# Paste a URL and display it on your FF1
+npm run dev -- find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
 
 # Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display
 
 # Feral File artwork (public id may be hex or numeric)
-npm run dev -- find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --play
+npm run dev -- find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --display
 
-# Save without playing
+# Save without displaying
 npm run dev -- find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 -o send-receive.json
 
 # Single on-chain token by coordinates
@@ -62,11 +62,11 @@ npm run dev -- find https://www.artblocks.io/collection/ringers-by-dmitri-cherni
 # Build and publish to a configured feed server
 npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --publish
 
-# Build, play on a named device, and skip interactive prompts
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play -d "Living Room Display" -y
+# Build, display on a named device, and skip interactive prompts
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display -d "Living Room Display" -y
 
-# -y alone also plays (the scripted default); add --no-play to build and save without casting
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 -y --no-play
+# -y alone also displays (the scripted default); add --no-display to build and save without casting
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 -y --no-display
 ```
 
 OpenSea and Verse accept both item and collection/series URLs:
@@ -261,14 +261,14 @@ the flag; without it those items are skipped rather than guessed at, because
 the wrong network returns a different artwork's metadata. A Tezos playlist
 needs no flag.
 
-Items the indexer cannot resolve are listed rather than guessed at:
+Items the token source cannot resolve are listed rather than guessed at:
 
 ```text
 Nothing to enrich
 
   Skipped 3:
     Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
-    Untitled — the indexer returned nothing for it
+    Untitled — the token source returned nothing for it
     Pre-Process — chain "evm" names a family; pass --assume-ethereum to assert the network
 ```
 
@@ -278,14 +278,14 @@ has to be re-signed:
 ```bash
 ff-cli enrich playlist.json --assume-ethereum
 ff-cli sign playlist.json
-ff-cli play playlist.json -d "living room"
+ff-cli display playlist.json -d "living room"
 ```
 
 Casting does not care about the signing role. Add `-r curator` to that `sign` if the playlist is also
 going to a feed: `ff-cli publish` requires the owner role, for the reasons in
 [Publish to Feed Server](#publish-to-feed-server).
 
-## Validate / Sign / Play
+## Validate / Sign / Display
 
 ```bash
 # Validate playlist structure
@@ -298,27 +298,27 @@ npm run dev -- verify playlist.json
 # Sign playlist (uses key/role from config, or override via --key / --role)
 npm run dev -- sign playlist.json -o signed.json
 
-# Play on the configured default device
-npm run dev -- play playlist.json
+# Display on the configured default device
+npm run dev -- display playlist.json
 
-# Play on a specific named device
-npm run dev -- play signed.json -d "Living Room Display"
+# Display on a specific named device
+npm run dev -- display signed.json -d "Living Room Display"
 
-# Play a hosted DP-1 playlist
-npm run dev -- play "https://cdn.example.com/playlist.json"
+# Display a hosted DP-1 playlist
+npm run dev -- display "https://cdn.example.com/playlist.json"
 
-# Play a playlist straight from a DP-1 feed server (the URL the feed hands out)
+# Display 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
+npm run dev -- display "https://feed.feralfile.com/api/v1/playlists/<slug>" --skip-verify
 
-# Play a media URL directly
-npm run dev -- play "https://example.com/video.mp4"
+# Display a media URL directly
+npm run dev -- display "https://example.com/video.mp4"
 
 # Skip verification only if you must send a non-conformant payload (not recommended)
-npm run dev -- play playlist.json --skip-verify
+npm run dev -- display 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.
+> **No feed server is required to cast.** A device can display 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 display "<url>"`. The DP-1 Feed server ([Publish to Feed Server](#publish-to-feed-server) below) adds discovery and curation, but is optional for simply displaying your own playlists.
 
 ## Publish to Feed Server
 
@@ -921,7 +921,7 @@ says so rather than sending you after a key that does not exist. That is the sta
 published without an owner-role signature is frozen in, and it is what the `publish` owner-role gate
 above exists to prevent.
 
-## Complete Flow (build → validate → sign → play → publish)
+## Complete Flow (build → validate → sign → display → publish)
 
 ```bash
 # 1. Build a playlist (via find or build)
@@ -937,8 +937,8 @@ npm run dev -- validate playlist.json
 #    what feeds enforce today.
 npm run dev -- sign playlist.json -r curator -o signed.json
 
-# 4. Play it on a device
-npm run dev -- play signed.json -d "Living Room Display"
+# 4. Display it on a device
+npm run dev -- display signed.json -d "Living Room Display"
 
 # 5. Publish to a feed server
 npm run dev -- publish signed.json -s 0
@@ -949,17 +949,17 @@ key declared in `curators[]`. Skip step 3 and use `playlist.json` in steps 4 and
 `signed.json` on that path:
 
 ```bash
-npm run dev -- play playlist.json -d "Living Room Display"
+npm run dev -- display playlist.json -d "Living Room Display"
 npm run dev -- publish playlist.json -s 0
 ```
 
 Set `playlist.curatorName` in the config to control the name recorded in `curators[]`; it defaults
 to `ff-cli`.
 
-`ff-cli find` can collapse build + play + publish into one command:
+`ff-cli find` can collapse build + display + publish into one command:
 
 ```bash
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play -d "Living Room Display" --publish
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display -d "Living Room Display" --publish
 ```
 
 ## FF1 device management

package/docs/PROJECT_SPEC.md

@@ -15,7 +15,7 @@ It is derived from the behavior and interfaces implemented in this repository as
 - Project: `ff-cli`
 - Type: Node.js CLI
 - System role: a control and integration surface for FF1 and DP-1 workflows
-- Primary purpose: turn resolved sources or structured parameters into valid DP-1 playlists deterministically, then validate them and optionally sign, publish, and play them through FF1 and feed paths
+- Primary purpose: turn resolved sources or structured parameters into valid DP-1 playlists deterministically, then validate them and optionally sign, publish, and display them through FF1 and feed paths
 
 There is no built-in natural-language interface and no model orchestration. Natural language belongs in the user's coding agent (Claude Code, Codex), which drives ff-cli's deterministic commands via the `ff-control` skill. ff-cli requires no LLM API key.
 
@@ -25,11 +25,11 @@ In the Feral File architecture bands, `ff-cli` sits primarily in the presentatio
 
 The CLI supports the broader Feral File goal of making it effortless to live with digital art every day.
 
-Its value is reducing friction in the publish-to-play path:
+Its value is reducing friction in the publish-to-display path:
 
 - assemble playlists quickly
 - keep outputs DP-1 conformant
-- make FF1 playback and feed publishing easier to exercise
+- make displaying on FF1 and feed publishing easier to exercise
 - provide deterministic tooling that agents and scripts can drive reliably
 
 The CLI should strengthen the Gold Path, not invent a parallel product model.
@@ -39,7 +39,7 @@ The CLI should strengthen the Gold Path, not invent a parallel product model.
 Current likely users:
 
 - internal engineers working on FF1, DP-1, feed, and device flows
-- operators and launch teammates validating publish-to-play behavior
+- operators and launch teammates validating publish-to-display behavior
 - advanced users or partners building and testing playlists
 - developers using the CLI as a reference implementation for DP-1 and FF1 command flows
 
@@ -50,7 +50,7 @@ Primary use cases:
 - validate or verify a local or hosted DP-1 playlist
 - sign a playlist with an Ed25519 key
 - publish a validated playlist to a configured feed server
-- play a playlist or direct media URL on a configured FF1 device
+- display a playlist or direct media URL on a configured FF1 device
 - manage local config and FF1 SSH access
 - exercise compatibility checks against FF1 OS versions before risky commands
 
@@ -73,15 +73,15 @@ Use these terms consistently:
 
 The current code and internal context imply these practical goals:
 
-- Make playlist creation and playback testing fast enough for daily use.
+- Make playlist creation and display testing fast enough for daily use.
 - Keep the path from intent to valid DP-1 output deterministic and inspectable.
 - Preserve openness by relying on DP-1 as the compatibility layer instead of a CLI-specific format.
-- Support FF1 as the reference playback target without making correctness depend on proprietary-only infrastructure.
-- Serve as a reference surface for publish, verify, and play flows used elsewhere in the Feral File stack.
+- Support FF1 as the reference display target without making correctness depend on proprietary-only infrastructure.
+- Serve as a reference surface for publish, verify, and display flows used elsewhere in the Feral File stack.
 
 ### Current behavior
 
-The current implementation still depends on Feral File-operated infrastructure for some data retrieval paths, including the hardcoded production indexer endpoint used for NFT lookup.
+Token data for `find`, `build`, and `enrich` comes from the Feral File indexer (ff-indexer-v2) by default. Raster's public GraphQL API is selectable with `tokenSource: "raster"` and is under evaluation as the replacement (feral-file#3576); it stays opt-in until the data bugs reported on feral-file#3546 are fixed. One token source answers a whole run; there is no fallback between them.
 
 ### Design direction
 
@@ -103,16 +103,22 @@ Based on the code today, the CLI is responsible for:
 
 - loading configuration from `config.json`, `.env`, and defaults, with `config.json` taking precedence
 - 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
+- running feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and display
 - supporting a deterministic build path from structured JSON (`build`)
-- 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
+- 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 token-source metadata
 - validating and verifying playlist structure and signatures
 - signing playlists when a private key is configured
 - publishing validated playlists to configured feed servers
-- discovering configured FF1 devices and sending playlists or direct media playback requests
-- pairing a device's signed relayer topic through a short-lived end-to-end
-  encrypted mobile handoff, authenticating the CLI key with a user-compared
-  security check, and storing it in the operating system credential vault
+- discovering configured FF1 devices and sending playlists or direct media display requests
+- pairing as an FF1 controller through owner-initiated registration: the CLI
+  shows a QR of its public keys and a one-time secret, an owner adds it in the
+  Feral File app, and the CLI pins the FF1 profile only from the owner's sealed
+  answer over the relay pairing channel, then enrolls (any relayer topic the
+  answer carries goes to the operating system credential vault)
+- pairing an FF1 without secure control by its signed relayer topic through
+  a short-lived end-to-end encrypted mobile handoff, authenticating the CLI key
+  with a user-compared security check, and storing it in the operating system
+  credential vault
 - falling back from unreachable LAN delivery to the shared FF1 relayer with an
   explicit terminal notice, so sandboxed and cross-subnet control remains
   observable to the mobile app
@@ -159,13 +165,17 @@ Today the CLI groups into these workflow areas:
 - `find`
 - `build`
 
-An item's `provenance.contract` is read from the indexer row, not inferred. Each
-row carries the token's own `standard` (`erc721`, `erc1155`, `fa2`) and its
-CAIP-2 `chain` (`eip155:1`, `tezos:mainnet`), and both are written through. The
-client's own detection sees a chain name and an address and nothing else, so it
-answers `erc721` for every EVM contract; it applies only to rows that carry no
-standard, and to the CID a lookup by coordinate must build before the indexer
-has been asked anything. A row naming a chain DP-1 has no word for is recorded
+An item's `provenance.contract` is read from the token source's row, not
+inferred. Each row carries the token's own standard and its CAIP-2 `chain`
+(`eip155:1`, `tezos:NetXdQprcVkpaWU` on Raster, `tezos:mainnet` on the
+indexer), and both are written through. Raster standards DP-1 cannot name
+(`CRYPTOPUNKS`, `ORDINAL_INSCRIPTION`) are written as `other`. Raster
+lowercases EVM addresses; they are checksummed before use, so an item's `id`
+(derived from the address and token id) and its provenance are the same
+whichever source built it. The client's own detection sees a chain name and an
+address and nothing else, so it answers `erc721` for every EVM contract; it
+applies only to rows that carry no standard, and to the CID a lookup by
+coordinate must build before the indexer has been asked anything. A row naming a chain DP-1 has no word for is recorded
 as `other` — the item is still built, and the client's guess is never
 substituted for a chain the row already named.
 
@@ -177,7 +187,7 @@ substituted for a chain the row already named.
 
 ### Delivery
 
-- `play` (handles playlist files, playlist URLs, and media URLs)
+- `display` (handles playlist files, playlist URLs, and media URLs; `play` is a hidden alias kept for existing scripts and agents)
 - `fetch`
 - `publish` (`--replace` sends an owner-bound replacement instead of a create)
 - `unpublish`
@@ -248,6 +258,13 @@ replacement.
 
 - `ssh enable|disable`
 
+### Support
+
+- `report` (posts a problem report to Feral File's support-logs, which mints the `Support [<id>]`
+  reference and a token scoped to that one report; with `-d`, the Art Computer is then asked to upload
+  its logs under the same reference with its existing `uploadLogs` command. ff-cli holds no support
+  credential, since a key in a public package is public)
+
 ### Inline Ref Manifests
 
 Playlist items carry a full Ref Manifest inline (DP-1 Playlist Extension §3.6)
@@ -284,13 +301,13 @@ and nothing else. `enrich` is the repair path for those.
 - It writes `inlineManifest` and nothing else. `source`, `duration`, `title`,
   `id`, and `display` are curator decisions and survive untouched even when the
   indexer disagrees with them.
-- An item the indexer cannot resolve is reported, never synthesized. The same
+- An item the token source cannot resolve is reported, never synthesized. The same
   rule the manifest mapping follows applies here: the CLI does not invent fields
   it cannot substantiate, and an invented artist line inside a signed document
   is worse than an absent one.
-- DP-1 names the EVM family `evm`; the FF indexer names it `ethereum`. Enrich
-  translates between the two. Unlisted chain names pass through so the indexer
-  decides what it supports.
+- DP-1 names the EVM family `evm`; the token sources name it `ethereum`. Enrich
+  translates between the two. Unlisted chain names pass through so the token
+  source decides what it supports.
 - Enrichment changes the document, so both the `signatures[]` envelope and the
   legacy flat `signature` are removed and the playlist must be re-signed.
   Leaving a stale envelope in place would produce a file that fails
@@ -302,9 +319,10 @@ and nothing else. `enrich` is the repair path for those.
   discards the integrity hash the remote manifest is checked against. That
   conversion, if ever wanted, belongs behind its own flag.
 - Enrichment looks each distinct coordinate up once, however many items share
-  it. A token the indexer has not seen triggers an indexing job and a poll that
-  can take minutes, and a playlist that repeats a work would otherwise submit
-  that job once per appearance.
+  it. On Raster the lookups are batched; on the indexer a token it
+  has not seen triggers an indexing job and a poll that can take minutes, and a
+  playlist that repeats a work would otherwise submit that job once per
+  appearance.
 - Overriding an item's title changes the manifest's content, so it also changes
   the manifest's `id`. The indexer derives that id from the token coordinate,
   so two items of one artwork receive the same one; leaving it alone while
@@ -352,7 +370,8 @@ and nothing else. `enrich` is the repair path for those.
   nor the response can say which network is meant. Ethereum is chosen because
   it is the only EVM network this client can reach — `buildTokenCID` maps
   ethereum to `eip155:1` and tezos to `tezos:mainnet` and throws for anything
-  else. The residual risk is narrow: an L2 work whose address and token id also
+  else, and the Raster token source likewise builds Ethereum and Tezos mainnet
+  only. The residual risk is narrow: an L2 work whose address and token id also
   exist on Ethereum would take the Ethereum work's metadata. The command
   is the operator's to make: `--assume-ethereum` asserts it, and without that
   flag `evm` items are skipped with a reason that names the flag. The warning
@@ -411,7 +430,7 @@ and nothing else. `enrich` is the repair path for those.
 - The playlist is validated before lookup and the enriched candidate is
   validated before writing. On either failure the diagnostics are printed and
   the file is left untouched, rather than replaced with a document that sign,
-  publish, and play would each reject later.
+  publish, and display would each reject later.
 
 ## Deterministic-first behavior
 
@@ -488,16 +507,16 @@ Important constraints from the broader FF system:
 ### Current behavior
 
 - reliability matters more than novelty
-- the publish-to-play path should stay simple and testable
-- the CLI should help prove the path from canonical JSON to FF1 playback
+- the publish-to-display path should stay simple and testable
+- the CLI should help prove the path from canonical JSON to FF1 display
 - compatibility checks fail clearly when incompatibility is confirmed
 - if FF1 OS version cannot be determined during preflight, the CLI currently proceeds and logs a warning instead of hard-blocking the command
 
 ### Design direction
 
 - reliability matters more than novelty
-- the publish-to-play path should stay simple and testable
-- the CLI should help prove the path from canonical JSON to FF1 playback
+- the publish-to-display path should stay simple and testable
+- the CLI should help prove the path from canonical JSON to FF1 display
 - compatibility messaging should remain explicit enough that operators can distinguish confirmed incompatibility from uncertain device state
 
 ## Code and design constraints