@feralfile/cli 1.1.1

package/docs/PROJECT_SPEC.md

@@ -0,0 +1,228 @@
+# ff-cli Project Spec
+
+This document defines the current product role, boundaries, and constraints for `ff-cli`.
+
+It is derived from the behavior and interfaces implemented in this repository as of March 2026. It serves as the planning entry point for substantial changes and should be updated as the CLI evolves.
+
+## Why this doc exists
+
+- Give future contributors and coding agents a stable current-state spec before implementation starts.
+- Make the CLI's role in the broader FF1 and DP-1 system explicit.
+- Record the constraints that should shape changes even when the codebase is refactored.
+
+## Product summary
+
+- Project: `ff-cli`
+- Type: Node.js CLI
+- System role: a control and integration surface for FF1 and DP-1 workflows
+- Primary purpose: turn user intent or structured parameters into valid DP-1 playlists, then validate them and optionally sign, publish, and send them through FF1 and feed paths
+
+In the Feral File architecture bands, `ff-cli` sits primarily in the presentation and control layer. It is not the canonical source of truth for exhibitions, ownership, device runtime, or protocol evolution. It is a practical operator and developer surface that bridges those systems.
+
+## Strategic role
+
+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:
+
+- assemble playlists quickly
+- keep outputs DP-1 conformant
+- make FF1 playback and feed publishing easier to exercise
+- provide deterministic tooling around model-assisted workflows
+
+The CLI should strengthen the Gold Path, not invent a parallel product model.
+
+## Users and primary use cases
+
+Current likely users:
+
+- internal engineers working on FF1, DP-1, feed, and device flows
+- operators and launch teammates validating publish-to-play behavior
+- advanced users or partners building and testing playlists
+- developers using the CLI as a reference implementation for DP-1 and FF1 command flows
+
+Primary use cases:
+
+- build a playlist from structured JSON inputs
+- build a playlist from natural-language prompts using model orchestration plus deterministic tools
+- 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
+- send a playlist or direct media URL to a configured FF1 device
+- manage local config and FF1 SSH access
+- exercise compatibility checks against FF1 OS versions before risky commands
+
+## Domain language
+
+Use these terms consistently:
+
+- `FF1`
+- `FF1 device`
+- `DP-1`
+- `DP-1 envelope`
+- `DP-1 conformance`
+- `computational art playlist`
+- `channel endorsement`
+- `feed server`
+- `playlist`
+- `work`
+
+## Product goals
+
+The current code and internal context imply these practical goals:
+
+- Make playlist creation and playback 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.
+
+### 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.
+
+### Design direction
+
+Long-term interoperability should continue to reduce hard infrastructure coupling where practical, especially when a dependency blocks portability without adding protocol value.
+
+## Non-goals
+
+`ff-cli` should not become:
+
+- the source of truth for exhibitions, channels, or artwork metadata
+- the source of truth for ownership, passkeys, rights, or trust registry state
+- a replacement for the mobile app as the primary user-facing controller
+- a place to define new DP-1 protocol semantics by convenience
+- a long-running backend service with hidden state
+
+## Current system responsibilities
+
+Based on the code today, the CLI is responsible for:
+
+- loading configuration from `config.json`, `.env`, and defaults, with `config.json` taking precedence
+- parsing natural-language requests into structured playlist requirements and settings
+- orchestrating tool calls for feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and sending
+- supporting a deterministic non-AI build path from structured JSON
+- building DP-1 playlist envelopes from NFT metadata or direct media URLs
+- 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
+- performing FF1 OS compatibility preflight checks before display and SSH flows
+
+## Architecture boundaries
+
+### What the CLI owns
+
+- command-line UX and command routing
+- local config loading and validation
+- intent parsing and orchestration glue
+- deterministic playlist assembly, verification, and signing helpers
+- device and feed integration calls from the client side
+
+### What the CLI depends on but does not own
+
+- DP-1 protocol shape and evolution
+- feed server behavior and data persistence
+- FF1 runtime and OS behavior
+- ownership and identity systems
+- trust-path policy, licensing policy, and key registry policy
+
+### Boundary rules
+
+- The CLI may assemble, validate, and transmit DP-1 objects, but it should not silently fork the protocol.
+- The CLI may call feed and device endpoints, but it should not become their compatibility abstraction layer of last resort.
+- The CLI may use models for orchestration, but deterministic utilities remain the source of truth for output correctness.
+- Trust-sensitive correctness must stay vendor-neutral and portable. The CLI can use cloud APIs for model orchestration, but the trust path cannot depend on cloud-specific guarantees.
+- Current implementation note: some retrieval paths still use Feral File-operated services directly, so portability here is an intended direction rather than a fully achieved property.
+
+## Functional shape
+
+Today the CLI groups into these workflow areas:
+
+### Setup and configuration
+
+- `setup`
+- `status`
+- `config init|show|validate`
+
+### Build and orchestration
+
+- `chat`
+- `build`
+
+### DP-1 output integrity
+
+- `verify`
+- `validate`
+- `sign`
+
+### Delivery
+
+- `play` (handles playlist files, playlist URLs, and media URLs)
+- `publish`
+
+### Device operations
+
+- `ssh enable|disable`
+
+## Deterministic-first behavior
+
+The CLI supports model-assisted workflows, but the implementation posture should remain deterministic-first:
+
+- models interpret intent
+- utilities perform the real data fetching, playlist building, validation, signing, and delivery work
+- invalid or malformed outputs should fail validation rather than being accepted because they were model-produced
+
+## Trust, protocol, and rights assumptions
+
+Important constraints from the broader FF system:
+
+- DP-1 should evolve additively and remain forward-compatible where practical.
+- Trust-path correctness must remain portable and key-controlled.
+- Ownership and stewardship should not be confused with access gating in the CLI.
+- The CLI may surface signatures, verification, and publishing, but it should not absorb licensing or identity policy that belongs elsewhere in the system.
+
+## Reliability expectations
+
+### 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
+- 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
+- compatibility messaging should remain explicit enough that operators can distinguish confirmed incompatibility from uncertain device state
+
+## Code and design constraints
+
+- behavior changes should follow a spec-driven, test-first workflow when practical
+- TypeScript is preferred for new or updated source
+- comments should preserve durable maintenance context when the code encodes non-obvious design choices, trade-offs, invariants, or external constraints
+- docs should be updated when user-facing behavior changes
+- legacy compatibility paths should not be preserved unless explicitly required
+
+## Verification expectations
+
+The current repo verification path is:
+
+```bash
+npm run lint:fix
+npm test
+npm run build
+ANTHROPIC_API_KEY=dummy node dist/index.js validate examples/sample-playlist.json
+ANTHROPIC_API_KEY=dummy node dist/index.js config validate
+```
+
+## Open questions
+
+- Which CLI commands are considered stable public interface versus internal reference tooling?
+- How much of the feed and trust workflow should remain directly exposed in the CLI?
+- Which FF1 operations deserve stronger compatibility policies or broader smoke coverage?
+- How much of the mobile app's long-term control model should also be mirrored in CLI form?

package/docs/README.md

@@ -0,0 +1,348 @@
+# ff-cli Documentation
+
+Build DP-1 (Display Protocol 1) playlists from NFT data with either natural language (AI‑driven) or deterministic parameters. This doc covers install, config, and day‑to‑day usage.
+
+For project-level planning and future agentic work, see `./PROJECT_SPEC.md`.
+
+## Install
+
+```bash
+npm i -g @feralfile/cli
+```
+
+`npm` and `npx` require **Node.js 22 or newer** (see `package.json` `engines`). When a release raises the Node floor, that is a **breaking** change for Node 18/20 users; the GitHub Release for that version should say so explicitly (see `./RELEASING.md` for maintainer guidance).
+
+## Install (curl)
+
+```bash
+curl -fsSL https://feralfile.com/ff-cli-install | bash
+```
+
+Installs a prebuilt binary for macOS/Linux (no Node.js required).
+
+## Configure
+
+```bash
+# Guided setup (recommended)
+ff-cli setup
+```
+
+See the full configuration reference here: `./CONFIGURATION.md`.
+
+During setup, you can pick FF1 devices to add. Use `ff-cli device add` to add more devices later, and `ff-cli device list` to see what's configured. The first device is the default for `play` commands (override with `-d`).
+
+Manual config path:
+
+```bash
+ff-cli config init
+ff-cli config validate
+```
+
+### config.json structure (minimal)
+
+```json
+{
+  "defaultModel": "claude",
+  "models": {
+    "claude": {
+      "apiKey": "sk-ant-your-api-key-here",
+      "baseURL": "https://api.anthropic.com/v1/",
+      "model": "claude-sonnet-4-6",
+      "supportsFunctionCalling": true
+    },
+    "grok": {
+      "apiKey": "xai-your-api-key-here",
+      "baseURL": "https://api.x.ai/v1",
+      "model": "grok-beta",
+      "supportsFunctionCalling": true
+    },
+    "gpt": {
+      "apiKey": "sk-your-openai-key-here",
+      "baseURL": "https://api.openai.com/v1",
+      "model": "gpt-4o",
+      "supportsFunctionCalling": true
+    },
+    "gemini": {
+      "apiKey": "your-gemini-key-here",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
+      "model": "gemini-2.5-flash",
+      "supportsFunctionCalling": true
+    }
+  },
+  "defaultDuration": 10,
+  "playlist": {
+    "privateKey": "your_ed25519_private_key_hex_or_base64_here"
+  },
+  "feed": { "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"] },
+  "ff1Devices": {
+    "devices": [
+      {
+        "name": "Living Room Display",
+        "host": "http://192.168.1.100:1111"
+      }
+    ]
+  }
+}
+```
+
+### Environment variables (optional)
+
+See `./CONFIGURATION.md` for environment variable mappings.
+
+## Quick Start
+
+```bash
+# Chat
+ff-cli chat
+
+# Or natural language in one shot
+ff-cli chat "Get 3 works from reas.eth" -o playlist.json
+
+# Deterministic (no AI)
+ff-cli build examples/params-example.json -o playlist.json
+```
+
+For development in this repo:
+
+```bash
+npm run build
+node dist/index.js chat
+```
+
+If you're running from source without a build, use:
+
+```bash
+npm run dev -- chat
+```
+
+## Recommended Deterministic Flow (LLM + Tools)
+
+The model orchestrates; deterministic tools keep us honest and DP1‑conformant.
+
+1. Input: Share the essentials (contract + token IDs, or feed/URL names).
+2. Orchestration: The LLM parses your prompt and calls tools that:
+   - Fetch NFT metadata via OSS libs (`viem` for Ethereum, `@taquito/taquito` for Tezos)
+   - Validate DP1 schema with `dp1-js`
+   - Build a DP1 playlist envelope deterministically
+   - Optionally sign with Ed25519 (canonical JSON via `dp1-js`)
+3. Preview/send: Send to an FF1 on your LAN over HTTP (recommended). Point `ff1Devices.devices[].host` at a local relay if needed.
+4. Publish: Optional feed/registry publishing via the `publish` command.
+
+Notes:
+
+- **Deterministic by design**: Validation rejects bad or hallucinated data; we loop until it's valid or stop.
+- **OSS‑first**: `viem` and `@taquito/taquito`, with room for local caching.
+- **Relay**: Swap the example host for a local Node/Hono relay; avoid vendor lock‑in.
+
+## Commands (cheat sheet)
+
+- `chat [content]` – AI-driven natural language playlists
+  - Options: `-o, --output <file>`, `-m, --model <name>`, `-d, --device <name>`, `-v, --verbose`
+- `build [params.json]` – Deterministic build from JSON or stdin
+  - Options: `-o, --output <file>`, `-v, --verbose`
+- `validate <file-or-url>` – Validate playlist structure only
+- `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
+- `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
+  - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`
+- `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `validate`-style structure checks before sending; use `verify` for signatures)
+  - Options: `-d, --device <name>`, `--skip-verify` (skip structure validation; not recommended)
+- `publish <file>` – Publish a playlist to a feed server (`validate`-style structure checks before upload; use `verify` for signatures)
+  - Options: `-s, --server <index>` (server index if multiple configured)
+- `ssh <enable|disable>` – Manage SSH access on an FF1 device
+  - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
+- `device list` – List all configured FF1 devices
+- `device add` – Add a new FF1 device (with mDNS discovery)
+  - Options: `--host <host>`, `--name <name>`
+- `device remove <name>` – Remove a configured FF1 device
+- `device default <name>` – Set the default FF1 device (used when `-d` is omitted)
+- `config <init|show|validate>` – Manage configuration
+
+## Usage Highlights
+
+### Natural language (AI)
+
+```bash
+npm run dev -- chat "Get 3 works from reas.eth"
+npm run dev -- chat "Get 3 works from einstein-rosen.tez"
+npm run dev -- chat "Get tokens 52932,52457 from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0" -o playlist.json
+```
+
+Feed playlists (for example `Unsupervised`, `Social Codes`) depend on your configured feed servers and network reachability.
+Use exact or near-exact playlist titles for best results.
+
+If you prompt with a bare EVM address (for example `from 0x...`), the CLI now tries owner-address lookup first, then automatically falls back to contract lookup when no owned tokens are found.
+
+### One-shot complex prompt
+
+The model reads your request via the intent parser and turns it into structured `requirements` and `playlistSettings` (including shuffle, durations, and device). You can do everything in one line:
+
+```bash
+# Mix sources, shuffle order, set per-item duration, and send to a named device
+npm run dev -- chat "From Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 get tokens 52932,52457 and from reas.eth get 2 works; shuffle the order; 7 seconds per item; send to device 'Living Room Display'." -o playlist.json -v
+```
+
+How it works (at a glance):
+
+- The intent parser maps your text to `requirements` (what to fetch) and `playlistSettings` (e.g., `durationPerItem`, `preserveOrder=false` for shuffle, `deviceName`, `feedServer`).
+- Deterministic tools fetch NFT metadata, build a DP‑1 playlist, and validate it.
+- If `deviceName` is present, the CLI will send the validated playlist to that FF1 device.
+- If `feedServer` is present (via "publish to my feed"), the CLI will publish the playlist to the selected feed server.
+
+Use `--model claude|grok|gpt|gemini` to switch models, or set `defaultModel` in `config.json`.
+
+### Natural language publishing
+
+The intent parser recognizes publishing keywords and can both display and publish in one command:
+
+```bash
+# Build and publish
+npm run dev -- chat "Build playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; publish to my feed" -o playlist.json -v
+
+# Display on Art Computer AND publish to feed
+npm run dev -- chat "Get 3 from Unsupervised; shuffle; send to my Art Computer and publish to feed" -o playlist.json -v
+```
+
+For Feral File built playlists, you can reference titles listed in the repository:
+`https://github.com/feral-file/dp1-feed/tree/main/playlists`
+
+Example:
+
+```bash
+npm run dev -- chat "Get 3 from Unsupervised"
+```
+
+Publishing keywords: "publish", "publish to my feed", "push to feed", "send to feed". The CLI will:
+
+1. Detect the keyword and call `get_feed_servers`
+2. If multiple servers → ask which one to use
+3. Build → validate (structure) → publish automatically
+4. Display playlist ID and server URL on success
+
+If all configured feed servers are unreachable, the CLI now reports a feed availability error instead of "playlist not found".
+
+### Deterministic (no AI)
+
+```bash
+npm run dev -- build params.json -o playlist.json
+cat params.json | npm run dev -- build -o playlist.json
+```
+
+`params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`.
+
+### Validate, sign, and play
+
+```bash
+# Optional explicit validation (build flows already validate)
+npm run dev -- validate playlist.json
+
+# Sign (uses key and role from config, or overrides via --key / --role)
+npm run dev -- sign playlist.json -o signed.json
+
+# Play on configured default device (validates DP-1 structure by default)
+npm run dev -- play playlist.json
+
+# Play on a specific named device
+npm run dev -- play playlist.json -d "Living Room Display"
+
+# The play path performs a compatibility preflight check against the target FF1.
+# If the device reports an unsupported FF1 OS version, the command fails with
+# a clear version message before any cast request is sent.
+# It also retries transient local-network errors (for example intermittent
+# mDNS/Wi-Fi resolver failures) with a short backoff before returning a final error.
+
+# Play a hosted DP-1 playlist
+npm run dev -- play "https://cdn.example.com/playlist.json"
+
+# Play a media URL directly
+npm run dev -- play "https://example.com/video.mp4"
+
+# Skip structure validation only if you must send a non-conformant payload (not recommended)
+npm run dev -- play playlist.json --skip-verify
+```
+
+### SSH access
+
+```bash
+# Enable SSH access for 30 minutes
+ff-cli ssh enable --pubkey ~/.ssh/id_ed25519.pub --ttl 30m -d "Living Room Display"
+
+# Disable SSH access
+ff-cli ssh disable -d "Living Room Display"
+
+# `ff-cli ssh` also performs the same FF1 OS compatibility preflight used by `play`.
+```
+
+### Publish to feed server
+
+```bash
+# Publish to first configured feed server
+npm run dev -- publish playlist.json
+
+# Publish to specific server (if multiple configured)
+npm run dev -- publish playlist.json -s 0
+npm run dev -- publish playlist.json -s 1
+```
+
+The `publish` command:
+
+- Validates playlist structure (same as `validate`; does not verify signatures)
+- Shows interactive server selection if multiple are configured
+- Sends the validated playlist to the chosen feed server
+- Returns the playlist ID on success
+
+Configure feed servers in `config.json`:
+
+```json
+{
+  "feedServers": [
+    {
+      "baseUrl": "http://localhost:8787/api/v1",
+      "apiKey": "your-api-key-optional"
+    },
+    {
+      "baseUrl": "https://feed.example.com/api/v1",
+      "apiKey": "your-api-key-optional"
+    }
+  ]
+}
+```
+
+### FF1 device management
+
+```bash
+# List configured devices
+ff-cli device list
+
+# Add a device (interactive with mDNS discovery)
+ff-cli device add
+
+# Add a device non-interactively
+ff-cli device add --host 192.168.1.100 --name kitchen
+
+# Remove a device by name
+ff-cli device remove kitchen
+
+# Set the default device (used when -d is omitted)
+ff-cli device default office
+```
+
+Setup preserves existing devices when adding new ones. See selection rules and examples in `./CONFIGURATION.md`.
+
+### Playlist signing (optional)
+
+- Add `playlist.privateKey` (Ed25519 PKCS#8 DER as **hex** or **base64**, per `./CONFIGURATION.md`) and, optionally, `playlist.role` to `config.json`, or set `PLAYLIST_PRIVATE_KEY` and `PLAYLIST_ROLE`.
+- The CLI passes that string to **`dp1-js`** for signing; the dependency decodes hex (`0x` optional) or base64 before loading the key.
+- Signed playlists include a `signatures[]` envelope compliant with DP-1 v1.1.0 (via **`dp1-js`**).
+
+## Constraints
+
+- Max 20 items total across all requirements
+- Per-source caps enforced in utilities
+- Duration per item defaults to 10s (configurable)
+
+## Links
+
+- Function calling details: `./FUNCTION_CALLING.md`
+- Examples: `./EXAMPLES.md`
+- Release assets: `./RELEASING.md`
+- DP1 spec: `https://github.com/display-protocol/dp1`

package/docs/RELEASING.md

@@ -0,0 +1,73 @@
+# Releasing Binary Assets
+
+The curl installer downloads prebuilt binaries from GitHub Releases. Build one asset per OS/arch and upload both the archive and its `.sha256` checksum.
+
+## Build a Release Asset (local)
+
+**macOS / Linux:**
+
+```bash
+./scripts/release/build-asset.sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+.\scripts\release\build-asset-windows.ps1
+```
+
+This produces (names vary by OS/arch):
+
+- `release/ff-cli-darwin-arm64.tar.gz` (and `.sha256`) on macOS
+- `release/ff-cli-linux-x64.tar.gz` (and `.sha256`) on Linux
+- `release/ff-cli-windows-x64.zip` (and `.sha256`) on Windows
+
+Run the appropriate script on each target platform and upload each pair to the GitHub release.
+
+## GitHub Actions
+
+- **Build** (`build.yml`): Trigger manually (Actions → Build → Run workflow) or on pull requests. Builds binaries on macOS, Linux, and Windows and uploads them as workflow artifacts for download.
+- **Release** (`release.yml`): On **published** GitHub Releases, validates that `package.json` matches the tag, publishes to npm, then builds binaries and uploads assets. A GitHub Release marked as a pre-release publishes to the **`beta`** dist-tag; the version must also contain `beta`. A manual workflow dispatch can also publish a beta version when you need to bypass the normal release flow, but run it from `main`.
+
+## npm Publish Requirements
+
+- Set `NPM_TOKEN` in GitHub Actions secrets with an npm automation token.
+- Ensure `package.json` version matches the release tag (e.g. tag `1.0.2` → `"version": "1.0.2"`). The release job fails fast when they differ.
+- A **regular** (non-prerelease) GitHub Release publishes with the default dist-tag **`latest`**.
+- A GitHub Release marked **Set as a pre-release** publishes to the **`beta`** dist-tag, and its version must contain `beta` so the package version stays aligned with the beta channel.
+- Manual workflow dispatch runs publish to the **`beta`** dist-tag too, and the `version` input must contain `beta`, match `package.json`, and be dispatched from `main`.
+- Example beta version: `1.0.18-beta.0`.
+
+## Release notes and breaking changes
+
+GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm and installers surface it inconsistently, and operators skim release notes first.
+
+### Node.js engine floor (breaking)
+
+`package.json` declares `"engines": { "node": ">=22" }`. Raising the floor from Node 18 (or 20) is a **breaking change** for:
+
+- global installs and `npx @feralfile/cli` on older runtimes
+- CI jobs and images pinned to Node 18 or 20
+- anyone developing from source without upgrading Node
+
+**For the release that first ships this requirement**, copy or adapt the following into the GitHub Release description (and repeat in the upgrade section of internal comms if needed):
+
+> **Breaking — Node.js:** ff-cli now requires **Node.js 22 or newer** (`package.json` `engines`). Node 18 and Node 20 are no longer supported. Upgrade Node on your machines and in CI, or stay on an older ff-cli version until you can migrate.
+
+Later releases only need to repeat this block if the engine floor changes again.
+
+## Installer Redirect
+
+`https://feralfile.com/ff-cli-install` should redirect to:
+
+```
+https://raw.githubusercontent.com/feral-file/ff-cli/main/scripts/install.sh
+```
+
+The installer script then fetches the release assets from GitHub Releases.
+
+## Environment Overrides
+
+- `FF_CLI_VERSION`: overrides the version label in logs
+- `FF_CLI_NODE_VERSION`: Reserved in script headers for future use; current CI, npm `engines`, and release wrappers assume **Node.js 22+** (required by `dp1-js`).
+- `FF_CLI_OUTPUT_DIR`: output directory (default: `./release`)