@feralfile/cli 3.0.0 → 4.0.0

package/docs/CONFIGURATION.md

@@ -31,6 +31,8 @@ npm run dev -- config show
   - Which service `find`, `build`, and `enrich` read token data from. Defaults to `indexer`. See [tokenSource](#tokensource).
 - **ipfsGateways** (object)
   - Gateways used to turn bare `ipfs://` sources into HTTPS URLs. See [ipfsGateways](#ipfsgateways).
+- **supportLogs** (object)
+  - Where `ff-cli report` sends a problem report. See [supportLogs](#supportlogs).
 
 ## browser
 
@@ -43,10 +45,9 @@ 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, and as the default signing key for the owner-bound feed mutations (`publish --replace`, `unpublish`), which sign an authorization intent at request time. Those commands and `sign` all take `-k, --key` or `--key-file <path>` to override it for a single run — see [Where the signing key can come from](#where-the-signing-key-can-come-from). 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.
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures, and as the default signing key for the owner-bound feed mutations (`publish --replace`, `unpublish`), which sign an authorization intent at request time. Those commands and `sign` all take `-k, --key` or `--key-file <path>` to override it for a single run — see [Where the signing key can come from](#where-the-signing-key-can-come-from). 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`. `display` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `display` 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) 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-----`).
@@ -90,7 +91,7 @@ delivery mechanism rather than a fourth key format.
 
 **Prefer `--key-file` to `--key`.** `--key` writes your private key into your shell history file and
 exposes it in the process list, where any local user can read it for as long as the command runs.
-Neither disclosure can be undone: an Ed25519 signing key *is* the identity it asserts, and a playlist's
+Neither disclosure can be undone: an Ed25519 signing key _is_ the identity it asserts, and a playlist's
 `curators[]` owner set is immutable, so a leaked key cannot be rotated out of a document that already
 names it. `--key-file` keeps the material in a file you control:
 
@@ -116,7 +117,7 @@ The rules on both flags:
   something a publish or a delete can be taken back from.
 - **A `--key-file` argument is always opened, whatever it looks like.** A directory really can be
   called `BEGIN`, and a key file really can be named after a content hash. What is gated is not the
-  open but the *message*: a failure names the path only when it is short and no part of it is a
+  open but the _message_: a failure names the path only when it is short and no part of it is a
   complete key encoding, and otherwise says it could not be read without repeating it. Typing the key
   where the path goes — one keystroke from `--key` — is reported as that mistake, by name, with the
   value withheld.
@@ -149,8 +150,8 @@ If you need a different role, set `playlist.role` to one of the DP-1 signing rol
 ### Signing role and ownership
 
 A feed decides who owns a playlist from the document itself: the keys in `curators[]` are the owner set.
-Under **role-aware ownership**, a key counts as an owner only when that same key *also signed in the
-`curator` role* — being named is a claim, signing as `curator` is the proof.
+Under **role-aware ownership**, a key counts as an owner only when that same key _also signed in the
+`curator` role_ — being named is a claim, signing as `curator` is the proof.
 
 `ff-cli publish` requires that role. **This is ff-cli's check, not every feed's answer today**: a feed that
 does not yet enforce roles accepts an `agent`-signed document, so a manual upload of the same file can
@@ -185,7 +186,8 @@ DP‑1 Feed API configuration.
 
 - `feed.baseURLs` (string[]): Array of DP‑1 Feed Operator API v1 base URLs. The CLI queries all feeds in parallel.
 - Legacy support: `feed.baseURL` (string) is still accepted and normalized to an array.
-- Default: `https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1` if not set.
+- Default: `https://feed.feralfile.com/api/v1` if not set.
+- A configured URL on `dp1-feed-operator-api-prod.autonomy-system.workers.dev` (the deleted server ff-cli 3.0.0's `setup` wrote into `config.json`) is read as `https://feed.feralfile.com` with the same path, with a one-line note on stderr until you update it.
 - Compatibility: API v1 of the DP‑1 Feed Operator server. See the repository for endpoints and behavior: [dp1-feed](https://github.com/display-protocol/dp1-feed).
 
 Endpoints used by the CLI:
@@ -216,15 +218,15 @@ defaulting to index 0 would silently write to whichever feed happens to be first
 Environment variable alternative:
 
 ```env
-FEED_BASE_URLS=https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
+FEED_BASE_URLS=https://feed.feralfile.com/api/v1,https://feed.example.com/api/v1
 ```
 
 ## tokenSource
 
-Token data for `find`, `build`, and `enrich` (title, artist, description, playable source, on-chain provenance, and a still image where the service supplies one) comes from one service per run:
+Token data for `find`, `build`, and `enrich` (title, artist, description, the source to display, on-chain provenance, and a still image where the service supplies one) comes from one service per run:
 
 - `indexer` (default): the Feral File indexer (ff-indexer-v2). A token it has not seen yet triggers an indexing job, so a first build of unseen tokens can take minutes.
-- `raster` (opt-in, under evaluation): Raster's public GraphQL API. Tokens are looked up 40 per request, so a build does not wait for indexing jobs. Raster's data still has known bugs, tracked on [feral-file#3546](https://github.com/feral-file/feral-file/issues/3546): some Feral File works point at a retired image host and play black, and evolving works play an older snapshot. No still image is supplied: Raster's preview renditions refuse non-browser clients, so items and `enrich` get no thumbnail from Raster.
+- `raster` (opt-in, under evaluation): Raster's public GraphQL API. Tokens are looked up 40 per request, so a build does not wait for indexing jobs. Raster's data still has known bugs, tracked on [feral-file#3546](https://github.com/feral-file/feral-file/issues/3546): some Feral File works point at a retired image host and display black, and evolving works display an older snapshot. No still image is supplied: Raster's preview renditions refuse non-browser clients, so items and `enrich` get no thumbnail from Raster.
 
 ```json
 { "tokenSource": "raster" }
@@ -269,6 +271,24 @@ IPFS_GATEWAY_FERAL_FILE=https://ipfs.feralfile.com/ipfs/
 IPFS_GATEWAY_DEFAULT=https://ipfs.filebase.io/ipfs/
 ```
 
+## supportLogs
+
+`ff-cli report` posts to Feral File's support-logs service, `https://support-logs.feralfile.com` by default. No configuration or key is needed; set `supportLogs.baseUrl` only to point at a staging or test service. It does not move an Art Computer's log upload, which goes to the support-logs its FF OS names.
+
+```json
+{
+  "supportLogs": {
+    "baseUrl": "https://support-logs.feralfile.com"
+  }
+}
+```
+
+Environment variable alternative:
+
+```env
+FF_SUPPORT_LOGS_URL=https://support-logs.feralfile.com
+```
+
 ## Raster API
 
 `find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)), and with the default `tokenSource` so do `build` and `enrich`. No configuration is required; two environment variables adjust the integration:
@@ -284,13 +304,13 @@ RASTER_API_URL=https://api.raster.art/graphql
 
 ## ff1Devices
 
-Configure devices you want to play content on.
+Configure devices you want to display art on.
 
 - `ff1Devices.devices` (array of objects):
   - `name` (string): Friendly device label. Free‑form; pick anything memorable.
   - `id` (string): Stable physical ID discovered from FF1 (for example
-    `FF1-SKYZ2E3A`). Relayer pairing stores the topic under this ID in the OS
-    credential vault.
+    `FF1-ABCD1234`). Relayer pairing stores the topic under this ID in the OS
+    credential vault, and controller pairing names the controller key file after it.
   - `host` (string): Device base URL. For LAN devices, use `http://<ip>:1111`. The device typically listens on port `1111`.
 
 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.
@@ -310,9 +330,39 @@ You can also manage devices independently with:
 - `ff-cli device rename <name> <new-name>` – Rename a device without touching its host, API key, or default status. Works offline; also accepts the host URL as the identifier, so unnamed legacy entries can be given a name.
 - `ff-cli device remove <name>` – Remove a device by name.
 - `ff-cli device default <name>` – Promote a device to the top of the list so it is used when `-d` is omitted.
-- `ff-cli device pair [name]` – Display a one-time handoff code and key-bound
-  security check, then securely receive that device's relayer topic from Feral
-  File mobile. Confirm both values match before approving in mobile.
+- `ff-cli device pair [name]` – Pair ff-cli with an FF1. ff-cli reads the
+  FF1's status on the LAN to pick the path:
+  - FF OS with secure control and an owner: show a QR code (and the same text
+    to paste) that an owner scans with **Add controller** in the Feral File
+    app; ff-cli pins the FF1's control profile from the owner's sealed answer
+    and enrolls as a **controller**. Needs an internet connection; see
+    [Secure control pairing](#secure-control-pairing).
+  - FF OS without secure control (or with it switched on but no owner yet):
+    display a one-time code and key-bound security check; in Feral File
+    mobile choose **Pair with ff-cli**, enter the code, and confirm both values
+    match before sharing. The app sends the relayer topic, which ff-cli stores
+    in the operating system credential vault.
+  - Status unreadable (FF1 off the LAN): the QR path, with a hint. Pass
+    `--topic-handoff` to force the one-time-code path.
+
+  The status is not authenticated, so ff-cli says which path it chose from
+  it, and never chooses the one-time code when it already holds controller
+  keys for the FF1 (a controller file, a pending replacement or the keys of
+  an unfinished pairing); only `--topic-handoff` does then.
+
+- `ff-cli device controllers [name]` – List the controllers paired with an FF1
+  and any pending requests (owner only). On FF OS with display grants the list
+  also shows Play sites that an owner approved through mint pairing, with role
+  `display`, platform `web` and the site's origin in the LABEL column
+  (`(unverified)` when the relay did not attest it). A display row may only
+  cast to the FF1; `ff-cli device revoke` removes it like any controller.
+- `ff-cli device revoke <controller-id> [name]` – Revoke a controller, or deny
+  its pending request (owner only).
+- `ff-cli device unpair [name]` – Revoke ff-cli's own access on the FF1 (best
+  effort) and delete its controller keys. It always asks first (owner keys get
+  a stronger warning); `-y, --yes` skips the question.
+  Owner keys need confirmation (or `--yes`): if no other owner can reach the
+  FF1, deleting them leaves it without a reachable owner until a factory reset.
 
 Setup and `device add` both preserve existing devices. Adding a device with the same host as an existing one updates it in place.
 
@@ -330,7 +380,7 @@ Selection rules when sending:
 
 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:
+The device exposes a single HTTP endpoint, `POST http://<device>:1111/api/cast`. `ff-cli display` casts a DP-1 playlist with:
 
 ```jsonc
 POST http://<device>:1111/api/cast
@@ -348,18 +398,23 @@ Content-Type: application/json
 
 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.
 
-When LAN delivery is unreachable, `play` prints an explicit notice and retries
+When LAN delivery is unreachable, `display` prints an explicit notice and retries
 the same command through `ff1Relayer.baseUrl`. The per-device topic is read from
 the operating system credential vault, never `config.json`. Pair it from the
 mobile app first:
 
 ```bash
-ff-cli device pair office
+ff-cli device pair office                  # FF OS without secure control: one-time code
+ff-cli device pair office --topic-handoff  # force the one-time code (FF1 not on this LAN)
 ```
 
-The CLI and mobile confirmation both show the same 12-hex-digit security check.
-Comparing it authenticates the CLI public key out of band, so an active broker
-cannot silently substitute its own encryption key.
+On FF OS without secure control, the CLI and mobile confirmation both show the
+same 12-hex-digit security check. Comparing it authenticates the CLI public key
+out of band, so an active broker cannot silently substitute its own encryption
+key. On FF OS with secure control, the topic arrives inside the owner's sealed
+answer when the FF1 still uses the topic relayer; ff-cli stores it only after
+the FF1's enroll reply verified, and the enroll itself uses the relayer only
+with a topic stored earlier. The topic is never printed.
 
 The default relayer is
 `https://tv-cast-coordination.autonomy-system.workers.dev`. Override it with
@@ -368,18 +423,205 @@ need no additional key. Deployments that retain the cloud-edge compatibility
 gate may receive `ff1Relayer.apiKey` or `FF1_RELAYER_API_KEY`; ff-cli never
 bundles that shared key.
 
+#### Relay v2
+
+Relay v2 routes by FF1 device ID instead of a topic, on a public channel that
+carries only sealed envelopes: a reply counts only when it verifies under the
+FF1 profile pinned at pairing. `device pair` uses it for its pairing channel.
+
+With the default relayer, the v2 endpoint is the production relay v2 Worker,
+`wss://relayer.feralfile.io`, which keeps working after the legacy relayer is
+retired. A custom `ff1Relayer.baseUrl` that is a bare HTTPS origin is used as
+its own v2 endpoint. Either way pairing needs no setting. Override it with
+`ff1Relayer.v2Endpoint` or `FF1_RELAY_V2_ENDPOINT`: an HTTPS or WSS origin
+(plain HTTP only on loopback), with no credentials, path or query. An empty
+value turns v2 off; `device pair` then reports that pairing is unavailable.
+
+When ff-cli is paired as a controller, a command that cannot reach the FF1 on
+the LAN goes over relay v2 first when the v2 endpoint is set explicitly, or
+when the FF1's last verified status listed `relayV2` in its control
+transports (ff-cli remembers this in the controller file). Otherwise it uses
+the topic relayer.
+
+```json
+{
+  "ff1Relayer": {
+    "v2Endpoint": "https://relay.example"
+  }
+}
+```
+
+- The stored topic is used only when relay v2 proves the command was not
+  delivered: it could not connect, or the relay refused it for every peer and
+  no part of it was acknowledged. The topic route then carries a newly sealed
+  request.
+- When the command may have reached the FF1 (it was acknowledged, or the
+  connection dropped after sending, or no verified reply came in time), ff-cli
+  reports "Outcome unknown" and does not send it again. Check the FF1 before
+  running the command again.
+- Relay refusals while connecting, and relay backpressure, are retried with
+  backoff.
+- `device pair` finishes its enroll over a relayer topic this machine held
+  from before the pairing, when it has one: that topic reaches the real FF1,
+  which cannot answer an enroll sealed to a forged profile. Only when the
+  relayer answers that the topic has no device (1003) or is retired (410),
+  or the legacy host answers 404 (it was shut down), or no topic is held,
+  does it go to the LAN and then relay v2; any other relayer failure
+  (offline, a timeout, a 5xx, a DNS failure) stops there. When the
+  credential vault cannot be read, whether a topic is held is unknown, so the
+  enroll uses the LAN only, never relay v2. Relay v2 lets a
+  controller be added remotely: the FF1 profile comes from the owner's sealed
+  pairing result, so a reply on the public device channel has to verify under
+  it. A first-owner enroll with a screen invitation never uses relay v2.
+- A command that reaches the relayer topic only to hear that the topic leads
+  nowhere (the same 1003, 410 or 404) also tries relay v2, even before a
+  verified status has said the FF1 is on v2, and a verified reply there
+  records that it is. So does a command when ff-cli holds no topic for the
+  FF1, or cannot read its credential vault: with no topic route there is
+  nothing a relay v2 attempt could cost. If the legacy host's name stops resolving instead,
+  ff-cli cannot tell that from an offline network; update ff-cli to a
+  release without the legacy relayer.
+- The owner's sealed pairing result must fit one relay frame (32 KiB; results
+  are about 1 KiB). If the relay connection drops while `device pair` waits,
+  pairing stops; run it again to show a new code.
+- On relay v2 a `replay` answer is reported as an unknown outcome, never
+  retried: the FF1 may have received two copies of the same request.
+
 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.
+- `display` 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.
 
 - Minimum supported FF1 OS versions:
-  - `play` (`displayPlaylist`): `1.0.0` or newer
+  - `display` (`displayPlaylist`): `1.0.0` or newer
   - `ssh` (`sshAccess`): `1.0.9` or newer
 
 - If the CLI cannot get a version from the device (e.g. network or malformed response), it continues and sends the command.
 - If the detected version is below the minimum, the command fails early with an error that includes the detected version.
+- `ssh` sends the relayer topic stored by `ff-cli device pair` (OS keyring) in the `X-FF1-Topic` header. A claimed FF1 on newer FF OS rejects plaintext `sshAccess` without it (HTTP 401 `topic_required`). With no stored topic the request is sent without the header, which unclaimed devices and older FF OS accept.
+
+- When ff-cli is paired as a controller (a controller file exists for the
+  device), the preflight, `display` and `ssh` are all sent as secure envelopes
+  instead; see below.
+
+### Secure control pairing
+
+Current FF OS authorizes every command per controller (FF1 control protocol
+v1). The FF1 itself decides who may do what; the LAN and the relayer only carry
+encrypted, signed requests. ff-cli takes part as a controller:
+
+```bash
+ff-cli device pair office                 # show the QR, wait for an owner, enroll
+ff-cli device pair office --label studio  # name the owner sees (default: hostname); 1-64 characters,
+                                          # no control or invisible formatting (bidi, zero-width) characters
+ff-cli device pair office --timeout 600   # wait longer for an owner (seconds, 10-600; default 300)
+ff-cli device pair office --resume        # finish a pairing an owner already approved
+ff-cli device pair office --yes           # move a corrupt controller file aside without asking
+```
+
+Pairing is owner-initiated, like adding an SSH key: nothing is requested from
+the FF1 and no code is compared.
+
+1. ff-cli shows a QR code and the same text to paste (`ff1-ctl:1|…`). It
+   carries this computer's public controller keys, a one-time pairing secret
+   and a relay channel ID. The QR uses this computer's existing keys for the
+   FF1 when it has them, so a re-pair (after a revoke, a role change or a
+   factory reset) keeps one controller ID on the FF1. Otherwise the keys are
+   saved to `controllers/pairing/<device ID>.keys.json` once the relay
+   channel is open, before the QR is shown, so a retry after a timeout or Ctrl-C shows the same keys (with a
+   new secret and channel) and completes a registration an owner already
+   made.
+2. On an owner's phone, open the FF1 in the Feral File app, choose **Add
+   controller**, scan the code (or paste the text), and pick the role.
+3. The app registers ff-cli on the FF1, then sends ff-cli a sealed answer over
+   the relay channel. ff-cli accepts only an answer it can open with this
+   run's keys that carries its pairing secret, its own controller ID, and the
+   configured FF1's device ID; anything else on the channel is ignored. It pins
+   the FF1's control profile from that answer: every reply must then be signed
+   by its key.
+4. ff-cli enrolls with the FF1 (LAN first, relayer if the LAN is unreachable)
+   and prints the role it was granted.
+
+Pairing needs an internet connection: the relay carries the owner's answer and
+keeps nothing. It also needs an FF1 that already has an owner (choose **Secure
+this FF1** in the app first); ff-cli cannot become an FF1's first owner. If no
+owner answers within the timeout, the pairing is "not completed", not
+rejected: running `device pair` again shows a new code for the same keys.
+If an owner declines, the command fails. If the owner's
+answer arrived but enrolling did not finish (the FF1 was unreachable, Ctrl-C),
+`ff-cli device pair <name> --resume` finishes it without a new code.
+
+If ff-cli is already paired with the FF1 under a different identity (the FF1
+was factory reset), it says that the new pairing will replace it, and keeps
+the current keys in place until the new pairing is enrolled: a failed or
+abandoned pairing never loses an existing grant. The pending replacement is
+kept in `controllers/pairing/` until then.
+
+`ff-cli device unpair <name>` first asks the FF1 to revoke ff-cli's own access
+(a sealed self-revoke, best effort with a short timeout), then deletes the keys
+whatever the answer. Older FF OS refuses a controller's self-revoke, and an FF1
+never lets its last owner revoke itself; in those cases the FF1 keeps listing
+the controller until an owner revokes it. Unpair also deletes the keys of an
+unfinished pairing; if an owner already added them, it prints their
+controller ID for an owner to revoke.
+
+Roles:
+
+- **owner** – every command, including `ssh` and controller management.
+- **controller** – displaying art (`display`) and device status. `ssh`,
+  `device controllers` and `device revoke` need an owner grant.
+
+Controller keys live in one file per FF1:
+
+```
+$XDG_CONFIG_HOME/ff-cli/controllers/<device ID>.json   # default ~/.config/ff-cli/controllers/
+```
+
+The file holds this computer's private controller keys, the pinned FF1 profile
+(generation and key pins), facts from the owner's answer (channel, FF1 name,
+role, expiry), the granted role, expiry and notification key, and the request
+counter. ff-cli creates it with mode `0600` inside a `0700` directory
+and replaces it atomically on every write. It is never printed or logged.
+**Windows:** mode bits do not apply; the file relies on the ACL of your user
+profile directory, so keep `%USERPROFILE%\.config` private to your account.
+
+Treat the file like an SSH private key: anyone who copies it can act as this
+controller until an owner revokes it. Do not restore it from an old backup —
+the counter inside must only grow, and an FF1 rejects reused counters
+(`replay`). When an FF1 answers `replay` in a reply signed by its key, ff-cli
+moves the counter ahead and sends the command once more as a new request. If
+it keeps happening, check that no other computer uses a copy of the file, then
+run `ff-cli device pair <name>` again: the current keys stay in place until the
+new pairing is finished. A controller file that
+cannot be read (permissions, a program holding it) is never overwritten; a
+corrupt one is moved aside to `<device ID>.json.corrupt-<time>` (after a
+question, or `--yes`) before a new pairing.
+`device remove` keeps the file, so re-adding the same FF1 keeps its pairing.
+
+Requests go to `POST /api/cast` as
+`{"command":"ff1Envelope","request":{"v":1,"jwe":"…"}}` on the LAN. When the
+LAN is unreachable, `display`, enrolling (`device pair`), `device controllers`,
+`device revoke` and unpair's self-revoke go through the relayer instead (they are encrypted and signed
+either way); the version preflight and `ssh` stay LAN-only. Each attempt,
+including every retry, is a new request with a new counter. FF1s on older FF OS
+(no controller file for them) keep the plaintext path described above.
+
+Errors and what to do:
+
+| Message                                                                                                                         | Cause                                                                                                                                                                                     | Fix                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "This FF1 is secured and only accepts requests from paired controllers."                                                        | The FF1 refuses plaintext and ff-cli is not paired                                                                                                                                        | `ff-cli device pair <name>`; an owner scans the code with **Add controller**                                                                                                                                                               |
+| "…does not know this ff-cli controller", "…was revoked or has expired", "…has not been approved", "…still waiting for approval" | No active grant for these keys                                                                                                                                                            | `ff-cli device pair <name>` (or `--resume`); an owner scans the code with **Add controller**. If the owner gave the FF1 up (it shows a setup code, or no one has set it up since), `ff-cli device unpair <name>` to use it without pairing |
+| "Pairing was not completed: no owner answered…"                                                                                 | No verified answer reached ff-cli before `--timeout`                                                                                                                                      | Run `ff-cli device pair <name>` again (needs internet)                                                                                                                                                                                     |
+| "Pairing is not available: … relay v2 is turned off"                                                                            | Relay v2 is off: `ff1Relayer.v2Endpoint`/`FF1_RELAY_V2_ENDPOINT` is empty, the relayer settings are invalid, or `ff1Relayer.baseUrl` is not a bare HTTPS origin and no v2 endpoint is set | Remove the empty override, or set an HTTPS/WSS origin (see [Relay v2](#relay-v2))                                                                                                                                                          |
+| "This command needs owner access…"                                                                                              | `ssh` or controller management with a controller grant                                                                                                                                    | An owner grants the owner role in the app                                                                                                                                                                                                  |
+| "The FF1 could not open the request." / "…rejected the request signature."                                                      | The FF1's control identity changed (for example a factory reset), or the device address now reaches another FF1. These answers are not authenticated: anyone on the path can send one     | Check the device address first. If the FF1 was factory reset: `ff-cli device pair <name>` (the current keys stay until the new pairing is finished). Do not unpair                                                                         |
+| "The reply did not verify against the paired FF1 identity…"                                                                     | A reply not signed by the pinned FF1 (wrong device, or a forged relayer reply)                                                                                                            | Check the device host; if the FF1 was reset, `ff-cli device pair <name>`. Do not unpair                                                                                                                                                    |
+| "The FF1 is busy; try again."                                                                                                   | The FF1 was checking too many requests at once and did not run this one (`display` retries it automatically with a new request)                                                           | Run the command again                                                                                                                                                                                                                      |
+| "The FF1 has no grant for ff-cli, although an owner's Feral File app reported adding it."                                       | An owner removed ff-cli again before it enrolled                                                                                                                                          | `ff-cli device pair <name>`                                                                                                                                                                                                                |
+| "The FF1 rejected the request counter as already used."                                                                         | The counter is still behind after ff-cli moved it ahead once (another computer uses a copy of the file)                                                                                   | Stop the other copy; run the command again. Do not unpair                                                                                                                                                                                  |
+| "The FF1 rejected the request as malformed."                                                                                    | Usually a clock more than 5 minutes ahead of the FF1's                                                                                                                                    | Fix the clock on this computer (or let the FF1 finish setting its time), then retry                                                                                                                                                        |
 
 Troubleshooting note:
 
@@ -389,10 +631,10 @@ Examples:
 
 ```bash
 # Send to first device
-npm run dev -- play playlist.json
+npm run dev -- display playlist.json
 
-# Play on a specific device by exact name
-npm run dev -- play playlist.json -d "Living Room Display"
+# Display on a specific device by exact name
+npm run dev -- display playlist.json -d "Living Room Display"
 ```
 
 Minimal `config.json` example (selected fields):
@@ -405,7 +647,7 @@ Minimal `config.json` example (selected fields):
     "role": "curator"
   },
   "feed": {
-    "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"]
+    "baseURLs": ["https://feed.feralfile.com/api/v1"]
   },
   "ff1Devices": {
     "devices": [

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:
@@ -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