@feralfile/cli 2.10.1 → 4.0.0

package/docs/CONFIGURATION.md

@@ -27,6 +27,12 @@ npm run dev -- config show
 - **generativeDuration** (number, seconds)
   - Display duration stamped on generative/interactive (HTML) works, which have no intrinsic runtime and no end-of-stream event. Defaults to **60s** (override via `DEFAULT_GENERATIVE_DURATION`).
   - Set to **0** to omit the duration entirely, so a conformant player parks on the work open-ended instead of rotating. Note: some players (including FF1) require every item to carry a `duration` and will reject a playlist whose items omit it — keep this non-zero unless you know your player tolerates an absent duration.
+- **tokenSource** (`"raster"` | `"indexer"`)
+  - 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
 
@@ -39,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-----`).
@@ -86,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:
 
@@ -112,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.
@@ -145,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
@@ -181,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:
@@ -212,12 +218,80 @@ 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
 ```
 
-## find (Raster API)
+## tokenSource
+
+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 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" }
+```
+
+Omit the key, or set `"indexer"`, to use the default.
+
+Environment variable alternative:
+
+```env
+FF_TOKEN_SOURCE=raster
+```
+
+There is no fallback between the two. A token Raster does not cover, or one that was burned, is reported as unresolved rather than looked up elsewhere.
+
+Raster has no way to list a contract's tokens. With `tokenSource: "raster"`, a `build_playlist` requirement without `tokenIds` fails with a message saying so, and a `query_address` requirement for an address that holds nothing is not retried as a contract. Give token ids, an owner address, or run `find` on the series URL instead.
+
+Only Ethereum mainnet and Tezos mainnet tokens are built. Tokens on other chains in a wallet or series are skipped and counted.
+
+## ipfsGateways
+
+With `tokenSource: "raster"`, many sources come back as bare `ipfs://` CIDs, which the FF1 cannot load. ff-cli rewrites them through a gateway:
 
-`ff-cli find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)). No configuration is required; two environment variables adjust the integration:
+- `ipfsGateways.feralFile`: used for Feral File works. Default `https://ipfs.feralfile.com/ipfs/`.
+- `ipfsGateways.default`: used for everything else. Default `https://ipfs.filebase.io/ipfs/`.
+
+A bare origin such as `https://gateway.example` is accepted and normalized to `https://gateway.example/ipfs/`. Sources on the retired `cdn.feralfileassets.com` host are rewritten to `cdn.artworks.feralfile.io`. Sources on the legacy `ipfs.bitmark.com` gateway go through `ipfsGateways.feralFile` instead.
+
+```json
+{
+  "ipfsGateways": {
+    "feralFile": "https://ipfs.feralfile.com/ipfs/",
+    "default": "https://ipfs.filebase.io/ipfs/"
+  }
+}
+```
+
+Environment variable alternative:
+
+```env
+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:
 
 ```env
 # API key sent as the x-api-key header. The API currently answers without
@@ -230,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.
@@ -256,12 +330,49 @@ 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.
 
+For an explicitly enrolled owner Tailscale connection, use the FF1's Tailscale IPv4
+address with the **same physical `--id` and existing `--name`**. Save its old
+host first. This updates that device in place, preserving its list position,
+API key and ID; relayer credentials remain in the vault under the same ID.
+The configured host is replaced, with no automatic LAN/Tailscale failover.
+See the [owner-access procedure](https://github.com/feral-file/ffos/blob/36e25cec84505271a7232d6936bb46a19fab5cfd/docs/OWNER_TAILSCALE.md).
+
 Selection rules when sending:
 
 - If you omit `-d`, the first configured device is used.
@@ -269,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
@@ -287,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
@@ -307,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:
 
@@ -328,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):
@@ -344,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": [