@ciphore/radiocli 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -2,8 +2,151 @@
 
 All notable changes to RadioCLI are documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.2.5] - 2026-10-18
+
+### Added
+
+- Added direct shell playback, volume controls, station-name lookup, filtered
+  search, favorites, recents, named presets, and listening stats.
+- Added a compact now-playing view with live track metadata and `--watch`,
+  readable terminal tables, JSON/plain output, and shell completion for Bash,
+  Zsh, Fish, and PowerShell.
+- Added Linux desktop media controls for RadioCLI's station queue, metadata,
+  playback, and volume, with `radiocli media-controls auto|on|off` overrides.
+- Added experimental Omarchy Quattro integration with preferred-terminal
+  launching and desktop/session diagnostics.
+- Added experimental, opt-in Linux AirPlay with Avahi discovery, receiver
+  selection, passcode handling, and guided dependency setup.
+
+### Changed
+
+- Simplified shell help around eight everyday commands, with `help --all` for
+  the full reference, `play` to resume, and favorites, recent, and popular queues.
+- Expanded Doctor with separate terminal, desktop media, audio, Omarchy, and
+  AirPlay readiness checks.
+- Included station presets in library backup, restore, and concurrent saves.
+- Reduced Gallop's drawing scale by 10% while preserving its proportions,
+  centering, and animation timing.
+- Removed the twelve preview receiver scenes, retaining the original 63 styles
+  and Ultracode default. Retired selections migrate without resetting saved data.
+
+### Fixed
+
+- Kept TUI playback running after a terminal crash, recovering the active
+  station, queue, controls, and sleep timer when the terminal reopens.
+- Recovered interrupted or stalled live mpv streams without restarting paused
+  sessions, finite recordings, or playback canceled by Stop.
+- Prevented duplicate mpv desktop media players and kept desktop controls in
+  sync with the shared player, including live-edge resume and alarm transitions.
+- Restored alarm volume to the original Linux output after default-device
+  changes and overlapping alarms, and kept imported alarm IDs distinct across
+  case-insensitive and Unicode-normalizing filesystems.
+- Preserved AirPlay mute, volume, and station metadata during connection setup,
+  added legacy RAOP password authentication, and improved connection errors.
+- Protected concurrent library saves and preserved the latest data in the safety
+  backup before a restore. Retried temporary Windows file-replacement conflicts.
+- Preserved migrated custom-station IDs, corrected XSPF CDATA and Unicode URL
+  imports, and restored Windows drive-path playlist imports.
+- Corrected mixed Arabic/Latin terminal layout and emoji clipping, padding, and
+  scrolling without changing plain output or screen-reader behavior.
+- Expired future-dated provider cache entries after clock corrections and
+  preserved valid data when migrating older caches.
+- Preserved package-manager paths during Unix updates and allowed slower
+  PowerShell startup when opening native Windows terminals.
+- Fixed a documentation typecheck race and added a single required CI gate for
+  platform, playback, and documentation checks. Release checks now include
+  packed upgrades from 0.2.3 and 0.2.4 and native TUI crash recovery.
+
+### Security
+
+- Removed the optional AirPlay sender's vulnerable elliptic dependency, using
+  Node's native Ed25519 while preserving pairing formats and optional installs.
+- Enabled native stream certificate verification and restricted FFmpeg network
+  playlists that cannot safely carry TLS policy. Documented the remaining
+  native OpenSSL numeric-IP certificate identity limitation.
+- Kept Doctor's probes read-only, bounded local service checks, and excluded
+  receiver codes and stream credentials from AirPlay diagnostics.
+- Updated documentation and development dependencies to patched releases.
+
+Quattro integration and Linux AirPlay remain experimental. Software playback
+checks do not establish physical receiver, speaker, hardware-key, or suspend/wake
+support; existing platform support tiers are unchanged.
+
+## [0.2.4] - 2026-09-17
+
+### Added
+
+- Added a shared platform layer for runtime eligibility, capabilities, executable
+  discovery, package installation, storage paths, networking, IPC, desktop
+  helpers, and terminal launching.
+- Added first-class Node.js 22 and 24 CI coverage for macOS Apple Silicon and
+  Intel, Ubuntu x64 and arm64, Windows x64, and Windows 11 arm64, including
+  packed installation and native mpv IPC playback checks.
+- Added repeatable packed CLI and mpv playback checks in full FreeBSD, OpenBSD,
+  and NetBSD guest kernels, plus explicit installation and capability guidance
+  for additional Unix, WSL, Termux, Haiku, illumos, and AIX environments.
+- Added offline, low-bandwidth, screen-reader, reduced-motion, ASCII, limited-
+  color, and noninteractive terminal modes with deterministic full, compact,
+  and micro rendering coverage.
+- Added automatic HTTP/ICY metadata discovery when importing a direct station
+  URL from the CLI or the TUI command palette.
+
+### Changed
+
+- Centralized native package recipes and guided setup so dry runs and executed
+  commands use the same platform-specific definitions.
+- Expanded `radiocli doctor --json` with host, runtime, network, storage,
+  terminal, playback, desktop, scheduling, and optional-feature capabilities.
+- Reorganized installation, platform, architecture, reliability, privacy, and
+  contributor documentation as stable reference material with explicit support
+  boundaries and troubleshooting paths.
+- Changed TUI `:import` to add custom stream URLs, renamed full-library recovery
+  to `:restore`, and consolidated shell URL additions under `radiocli import`.
+- Placed newest imported stations after favorites and before recently played
+  stations in the Library.
+- Changed resume for live radio to reload the active stream at its current live
+  edge instead of replaying audio accumulated in mpv's paused buffer.
+
+### Fixed
+
+- Kept playback and the TUI usable when optional history, presence, cache, or
+  library writes fail, while preserving recoverable data after interrupted or
+  permission-denied writes.
+- Hardened alarm deletion, native scheduler cleanup, terminal reopening, Alarm
+  Guard ownership, system-volume restoration, and forced-process teardown.
+- Preserved exact arguments, data locations, and supported environment selectors
+  across macOS, Linux, BSD, and Windows child processes without forwarding
+  unrelated shell state.
+- Improved player discovery, mpv readiness and IPC handling, provider timeouts,
+  mirror fallback, offline cache behavior, and degraded terminal rendering.
+- Recovered ARM Linux playback from mpv audio-service initialization failures
+  by retrying once with ALSA first, retained bounded player diagnostics, and
+  stopped system-wide backend failures from skipping through every station.
+- Replaced stale Radio Browser hosts with live DNS service discovery and added
+  a TLS-verified resolver fallback for temporary hostname failures without
+  bypassing configured proxies.
+- Preserved full RGB theme colors when a terminal explicitly advertises
+  truecolor, even when its Node.js stream reports a conservative 256-color
+  depth; explicit 256-color, 16-color, and no-color modes remain unchanged.
+- Kept retained Search results playable after clearing the submitted query and
+  added `Ctrl+F` to favorite the selected result while query input is active,
+  without intercepting an ordinary `f` typed into the search text.
+- Dismissed added and removed favorite confirmations after 4.5 seconds on
+  Overview, Now Playing, Library, Explore, Search, Nearby, and country station
+  views.
+- Marked AirPlay controls as macOS-only, hid the unsupported Settings shortcut,
+  and kept non-macOS users on their current screen with a direct platform notice.
+- Corrected Windows terminal launches to create independent interactive console
+  handles and retain the intended user data location.
+
+### Security
+
+- Updated documentation-site dependencies to patched releases.
+- Limited child-process environments to the settings required for RadioCLI data
+  identity and native integrations, excluding unrelated credentials and proxy
+  secrets.
+- Made native cleanup and ownership checks fail closed when a job, helper,
+  process, or saved state cannot be identified safely.
 
 ## [0.2.3] - 2026-09-07
 
@@ -397,7 +540,9 @@ Initial public release.
 [0.2.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.1
 [0.2.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.2
 [0.2.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.3
+[0.2.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.4
 [0.1.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.4
 [0.1.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.3
 [0.1.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.2
 [0.1.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.1
+[0.2.5]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.5

package/CONTRIBUTING.md

@@ -12,19 +12,22 @@ npm run build
 npm run test
 ```
 
-Install `mpv` for playback controls, metadata polling, and the best playback
-experience:
+Install `mpv` for playback controls and metadata polling. On a macOS
+configuration supported by Homebrew:
 
 ```bash
 brew install mpv
 ```
 
-On Linux, use your package manager's `mpv` package. On Windows, use:
+On Linux, use your package manager's `mpv` package. On Windows x64, use:
 
 ```powershell
 winget install --id shinchiro.mpv -e
 ```
 
+Use the [platform installation routes](apps/docs/content/docs/platforms.mdx#installation-and-playback-prerequisites)
+for Windows arm64 and other package managers.
+
 ## Verification
 
 Run these before opening a PR:
@@ -34,11 +37,29 @@ npm run check
 npm run lint
 npm run test
 npm run build
+npm run pack:check
+npm run fresh:check -- --require-mpv
+npm run check:package
+npm run smoke:mcp
+npm run docs:check
+npm run docs:build
 ```
 
-Run `npm run smoke:playback` when changing playback code. It opens a public
-stream briefly, so do not run it in environments where audio/network access is
-not acceptable.
+Install documentation dependencies with `npm --prefix apps/docs ci` first.
+Run `npm run smoke:playback` when changing playback code. Its default fixture is
+a local WAV file; mpv uses null audio in deterministic package
+checks. These checks exercise the player process and controls, and do not prove
+speaker output. `npm run smoke:data` intentionally contacts public providers.
+
+Also run `npm run smoke:network` for playback or transport changes. It uses
+loopback HTTP/TLS fixtures with null/dummy audio to verify certificate rejection,
+live EOF and stall recovery, finite-media EOF, Stop ownership, and installed
+fallback readiness. Set `RADIOCLI_REQUIRE_FALLBACKS=1` when the test host should
+have FFmpeg, ffplay and VLC; missing tools then fail instead of being skipped.
+
+Run `npm run build && npm run smoke:cli` when changing shell playback or session
+control. It uses an isolated library and silent local WAV with mpv's null audio
+output to check background startup, separate CLI controls, presets, and shutdown.
 
 Live provider checks are useful before releases, but ordinary pull requests
 should stay deterministic. Run `npm run verify:release` for a full maintainer
@@ -52,9 +73,28 @@ checks.
 - Never make location lookup implicit.
 - Prefer clear terminal text over decorative filler.
 - Keep command-line and TUI behavior aligned.
+- Put OS decisions in `src/platform`; keep capability availability separate from
+  runtime eligibility and recorded platform verification.
 - Add tests for parsing, storage, layout, or provider transformations when the
   behavior can be checked without live audio.
 
+## Platform verification
+
+The required Node 22/24 CI matrix tests x64 and arm64 installations and real mpv
+control. Weekly or manually triggered BSD checks execute the packed JavaScript
+in guest kernels. Changes to script harnesses
+also require `node --test scripts/packed-smoke.test-node.mjs scripts/install-smoke-mpv.test-node.mjs`.
+
+Record OS release, CPU, endianness, libc, Node/npm versions, artifact hash, and
+whether execution was native, virtualized, emulated, or mocked. An installation
+test, native command mock, or foreign binary inspection alone cannot promote a
+platform to supported. Follow the [support tiers](apps/docs/content/docs/platforms.mdx).
+
+The deterministic visual fixtures cover full, compact, and micro layouts, all
+major screens, and receiver styles. Preserve Unicode captures. When rendering
+changes intentionally, describe the visible effect in the pull request and do
+not update snapshots merely to hide failures.
+
 ## Issue Triage
 
 Playback issues should include station name, country, backend, and

package/README.md

@@ -1,39 +1,70 @@
-![RadioCLI Now Playing visualizer demo](apps/docs/public/demo/radiocli-now-playing.gif)
-
 # RadioCLI
 
-[![CI](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml)
+RadioCLI is an open-source internet radio player with a full-screen terminal
+interface and a scriptable CLI. Discover and stream stations from around the
+world without leaving your terminal. No account. No cloud library.
+
+[![CI](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
 
-RadioCLI brings live radio to your terminal. Browse stations around the world,
-save favorites, and listen through `mpv`—without an account or cloud library.
-
-Built with [Ink](https://github.com/vadimdemedes/ink),
-[React](https://react.dev/), and the
-[Radio Browser](https://api.radio-browser.info/) directory.
-
-## Highlights
-
-- Discover stations through Explore, Search, Countries, or approximate-location Nearby.
-- Listen with a receiver-style Now Playing screen, live metadata, sleep timer, diagnostics, and selectable visualizers.
-- Keep favorites, recents, imports, track history, and listening stats on your machine.
-- Create one-time or recurring radio alarms from the TUI, with native background
-  scheduling, station fallback, missed-run grace, snooze, and optional Alarm Guard.
-- Move through the exact station list you tuned from with previous and next controls.
-- Use `mpv` for complete playback control, with `ffplay` and VLC as limited fallbacks.
-- Resize freely: full, compact, and micro layouts preserve navigation and essential controls; Explore retains its interactive world map at every usable size.
+![RadioCLI playing SomaFM while cycling through terminal receiver styles](apps/docs/public/demo/radiocli-now-playing.gif)
+
+## Features
+
+- **Station discovery:** Search by name or genre, filter by country, language,
+  codec, and bitrate, or browse country lists. The interactive world map uses a
+  cached station atlas to find broadcasts around the map cursor and sort them by
+  distance. Cached directory results remain available during provider outages.
+- **63 receiver styles:** Switch between braille animation, ASCII geometry,
+  waves, fire, cityscapes, and the Gallop display without interrupting
+  playback. Color themes are selected independently. Receivers animate during
+  active playback and return to a zero-signal display when audio is inactive.
+- **Listening stats:** A 52-week activity graph, listening time, session counts,
+  active days, streaks, and your most-listened station. Stats are recorded locally
+  across TUI and CLI listening sessions.
+- **Alarms (beta):** One-time and recurring schedules with timezones, independent
+  volume, fade-in, fallback stations, snooze, and auto-stop. Native OS scheduling
+  allows alarms to run after the terminal closes. See the
+  [alarm guide](apps/docs/content/docs/alarms.mdx) for setup and power requirements.
+- **Agent control:** An optional Model Context Protocol (MCP) server exposes
+  typed tools for discovery, playback, favorites, stats, alarms, AirPlay, and
+  appearance. Coding assistants can operate RadioCLI directly; `radiocli agent`
+  provides the same controls for other local tools.
+- **Terminal support:** Full, compact, and micro layouts adapt to window resizing.
+  Keyboard, mouse, and trackpad controls work alongside Unicode and ASCII
+  rendering, reduced motion, screen-reader output, transparent backgrounds, and
+  limited-color or `NO_COLOR` environments. Offline browsing and low-bandwidth
+  modes are also supported.
+- **Playback:** Pause, volume, mute, and live track metadata through `mpv`, with
+  configurable media keys and a sleep timer. Previous and next follow the station
+  list you tuned from. Track history and stream diagnostics are available in
+  the TUI.
+- **Nearby stations:** Discover stations around an approximate location and
+  browse them by distance. Location lookup runs when you open Nearby and can be
+  disabled in Settings.
+- **Local library:** Save favorites, revisit recent stations, and manage imports
+  in one place. Settings, track history, and listening data stay on your machine,
+  with JSON backup and restore. No account is required.
+- **AirPlay (experimental):** Discover network receivers and switch audio output
+  from the TUI, including passcode entry when required. Availability depends on
+  the platform and receiver; see [supported setups](apps/docs/content/docs/platforms.mdx).
+- **Custom stations:** Add direct HTTP(S) stream URLs with automatic ICY metadata
+  lookup. Import M3U, PLS, or XSPF playlists and export an M3U library.
+- **Shell commands:** Start background playback by station name, save named
+  presets, and watch the current track from your prompt. Shell completion and
+  JSON or plain output support interactive use and scripting.
 
 ## Quick start
 
-macOS with Homebrew:
+**Homebrew**
 
 ```bash
 brew install ciphore/tap/radiocli
 radiocli
 ```
 
-macOS, Linux, or Windows with npm:
+**npm · Node.js 22 or newer**
 
 ```bash
 npm install -g @ciphore/radiocli
@@ -41,216 +72,84 @@ radiocli setup
 radiocli
 ```
 
-RadioCLI requires Node.js 22 or newer. The Homebrew formula installs `mpv` and
-FFmpeg. After an npm install, `radiocli setup` detects the operating system and
-package manager, lets you choose `mpv`, FFmpeg, and VLC, installs the selected
-native tools with branded progress feedback, and verifies playback readiness.
-
-See the [installation guide](apps/docs/content/docs/getting-started/install.mdx)
-for Windows, Linux distributions, AirPlay prerequisites, and fallback players.
+Setup helps install the playback tools for your system. See
+[installation](apps/docs/content/docs/getting-started/install.mdx) for other
+routes and [platform support](apps/docs/content/docs/platforms.mdx) for
+macOS, Linux, Windows, and BSD details.
 
-## Visual tour
+Launch `radiocli`, open Search or Explore, select a station, and press `Enter`
+to start playback.
 
-These recordings come from the built TUI. Generate them locally with
-`npm run demo:assets`.
-
-### Library
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Switch screens |
+| `↑` / `↓`, then `Enter` | Select and tune a station |
+| `space` | Pause or resume |
+| `f` | Toggle a favorite |
+| `v` / `t` | Change receiver style / color theme on Playing |
+| `?` / `q` | Show shortcuts / quit |
 
-![Favorites and recent stations in the RadioCLI Library](apps/docs/public/demo/radiocli-library.gif)
+The footer shows controls for the current screen. See the
+[controls guide](apps/docs/content/docs/getting-started/tui-controls.mdx) for
+filters, station skipping, media keys, and the command palette.
 
-### Explore
+## Screenshots
 
-![World map discovery in RadioCLI Explore](apps/docs/public/demo/radiocli-explore-map.gif)
+**Explore:** Move the map cursor with WASD or click a location to list stations
+by distance.
 
-### Search
+![Interactive world map and station discovery in RadioCLI](apps/docs/public/demo/radiocli-explore-map.gif)
 
-![Station search results in RadioCLI](apps/docs/public/demo/radiocli-search.gif)
+**Search:** Browse results with station names, countries, codecs, and bitrates.
 
-### Nearby
+![Searching internet radio stations in the terminal](apps/docs/public/demo/radiocli-search.gif)
 
-![Nearby stations in RadioCLI](apps/docs/public/demo/radiocli-nearby.gif)
+**Library:** Switch between favorites, recent stations, and imported streams.
 
-### Stats
+![Favorites and recent stations in the RadioCLI library](apps/docs/public/demo/radiocli-library.gif)
 
-![Local listening stats with selectable display colors](apps/docs/public/demo/radiocli-stats-colors.gif)
+**Nearby:** Browse stations around your approximate location.
 
-## Essential controls
+![Nearby radio stations in RadioCLI](apps/docs/public/demo/radiocli-nearby.gif)
 
-| Key | Action |
-| --- | --- |
-| `←` / `→` or `Tab` / `Shift+Tab` | Switch screens |
-| `↑` / `↓` or `n` / `p` | Move the selection |
-| `Enter` | Open or tune the selection |
-| `space` or `F8` | Pause or resume with `mpv` |
-| `,` / `.` or `F7` / `F9` | Previous or next station |
-| `+` / `-` | Change volume |
-| `f` | Save or remove a favorite |
-| `?` | Open all shortcuts and commands |
-| `q` or `Ctrl+C` twice | Quit cleanly |
-
-The footer always shows controls for the current screen. Press `:` to open the
-command palette. The [TUI controls guide](apps/docs/content/docs/getting-started/tui-controls.mdx)
-covers filters, playback, media-key learning, AirPlay, and every command.
-
-## CLI
-
-RadioCLI can also be controlled by local coding agents. Run `radiocli setup`
-and opt into MCP, or use `radiocli setup --mcp`, to configure detected Codex,
-Claude, OpenCode, Cursor, Gemini, VS Code/Copilot, and Orca-backed runtimes
-automatically. From the TUI, open **Settings → Agent control & MCP** and turn on
-**Allow local agent control** for the same one-step setup—no terminal command is
-required. The same actions are
-available to non-MCP harnesses through `radiocli agent` and `radiocli alarm`:
-search and play stations, browse recents/favorites/nearby stations, favorite the
-current station, inspect listening stats, create and control alarms, control
-macOS AirPlay, change the receiver look, or run a user-configured completion
-preset. Codex Voice can invoke those same typed MCP tools. Agent playback opens
-the normal RadioCLI TUI in a terminal window by default on macOS, Windows, and
-Linux. Interactive setup explains that macOS may require the agent host to approve
-a one-time Automation prompt; users can explicitly opt into headless playback.
-Scheduled alarms remain isolated and always use local output rather than
-unattended AirPlay. See the
-[CLI guide](apps/docs/content/docs/getting-started/cli.mdx#local-agent-and-mcp-control).
+**Stats:** Review listening activity and totals, with selectable display colors.
 
-```bash
-radiocli                 # Start the TUI
-radiocli check           # Check providers, playback tools, and the local store
-radiocli doctor --json   # Create a redacted support report
-radiocli search "japan hits"
-radiocli countries
-radiocli import stations.m3u
-radiocli export favorites.m3u
-radiocli add-url <stream-url> [station name]
-radiocli alarm list
-radiocli alarm doctor
-radiocli update --install # Upgrade and repair enabled MCP registrations
-```
+![Listening stats and the 52-week activity graph with selectable colors](apps/docs/public/demo/radiocli-stats-colors.gif)
 
-Existing installations keep their library and preferences when upgraded. Use
-`radiocli update` to inspect the detected Homebrew, npm, pnpm, or Bun command,
-or `radiocli update --install` to run it. MCP registrations use an
-upgrade-stable launcher so versioned package paths do not break them. On
-Windows this is a shell-free Node command; on Unix it uses the `radiocli` shim.
-Run `radiocli mcp status` to inspect registrations and `radiocli mcp repair`
-after moving an installation or when an agent client reports a stale server;
-fully quit and reopen agent clients after enabling, repairing, or upgrading.
-Until that restart, even a newly created task in an already-running client will
-not have RadioCLI's tools and may incorrectly fall back to browser playback.
-
-RadioCLI imports `.m3u`, `.pls`, and `.xspf` playlists. It exports favorites
-and imported streams as `.m3u`.
-
-Alarms are experimental beta functionality and live under **Overview**,
-immediately before Settings. Saving an enabled
-alarm registers it with launchd on macOS, a systemd user timer on Linux, or Task
-Scheduler on Windows, so the terminal does not need to remain open. When it
-fires, RadioCLI reopens the saved supported terminal and shows the ringing
-screen. Enter transfers the station into normal interactive playback; Space
-stops it and snoozes for 10 minutes. If a
-RadioCLI TUI is already open, that instance shows the controls instead. The
-computer must still be powered on with a logged-in interactive audio session; wake timing
-depends on hardware and OS power policy. See the [CLI guide](apps/docs/content/docs/getting-started/cli.mdx)
-and [reliability notes](apps/docs/content/docs/reliability.mdx) before relying on
-an alarm for something critical. Use a secondary device as the primary alarm
-for safety-critical, medical, travel, or emergency timing. See the dedicated
-[Alarms guide](apps/docs/content/docs/alarms.mdx) for the full workflow.
-
-The **Verify alarm setup** row performs a disposable native-scheduler
-registration, an authenticated terminal/control handshake, sleep-inhibitor and
-system-volume checks, and a short sample from the next configured alarm. It
-cleans up the temporary job and reports hard blockers separately from hardware-
-or policy-dependent wake limitations.
-
-See the [CLI guide](apps/docs/content/docs/getting-started/cli.mdx) for all
-arguments and examples.
-
-## Playback and reliability
-
-RadioCLI prefers `mpv` because it handles redirects, HLS, real-world codecs,
-ICY metadata, and interactive controls reliably. `ffplay` and VLC can keep a
-stream playing when `mpv` is unavailable, but the UI labels their controls as
-limited.
-
-Station providers use mirror fallback, bounded caches, and stale-cache recovery.
-Playback waits for backend readiness, applies tune timeouts, and can skip broken
-streams. Corrupt library and cache files are backed up instead of silently
-overwritten.
-
-Scheduled playback retries the primary station once, then tries an optional
-fallback. A missed-run grace window controls catch-up after sleep or logout.
-True fade-in requires `mpv`; `ffplay` and VLC start audibly at the configured
-target volume. Scheduled alarms always use local speakers, never unattended
-AirPlay.
-
-On macOS, an npm or source installation is executed by Node, so System Settings
-may identify its background item as `node`. Showing RadioCLI as the providing
-application requires a future signed macOS app bundle with a bundled helper;
-changing a launchd label cannot safely relabel the executable.
-
-Read the [reliability notes](apps/docs/content/docs/reliability.mdx) for failure
-handling and troubleshooting.
-
-## Privacy
-
-RadioCLI does not require an account, proxy audio, or upload your listening
-history. Favorites, recents, imports, settings, alarms, track history, and
-activity stay in a local JSON library. Full JSON library backups include alarm
-definitions, while native scheduler registrations, runtime health, Alarm Guard
-state, and authenticated loopback-control tokens remain machine-local.
-
-Nearby contacts `ipapi.co` only when you open that screen, then uses an
-approximate location to sort the local station atlas. Disable the lookup with
-`l`, Settings, or `:location off`.
-
-Favoriting a Radio Browser station sends a best-effort public directory vote by
-default. Turn off **Share favorite votes with Radio Browser** in Settings to
-keep favorites local-only.
-
-See [Privacy and security](apps/docs/content/docs/privacy-security.mdx) for the
-complete data-flow description.
-
-## Project structure
-
-- `src/ui` — screens, input, layout, and terminal rendering
-- `src/providers` — station directories, resolution, and caches
-- `src/player` — playback backends, metadata, and AirPlay
-- `src/alarms` — schedules, native registration, Alarm Guard, and active controls
-- `src/storage` — local library persistence and migration
-- `apps/docs` — documentation website and manual
-
-More detail lives in the [architecture guide](apps/docs/content/docs/architecture.mdx)
-and [design notes](apps/docs/content/docs/design.mdx).
-
-## Development
+## CLI and agent control
 
 ```bash
-git clone https://github.com/Ciphore/RadioCLI.git
-cd RadioCLI
-npm ci
-npm run verify
-npm run dev
+radiocli play jazz
+radiocli now
+radiocli favorite
+radiocli stop
 ```
 
-`npm run verify` checks types, lint, tests, the production build, and package
-contents. Playback and live-data smoke tests are available separately because
-they contact public services or start a local player.
-
-## Contributing
+`play` starts background playback and returns to your prompt. If the TUI is
+already open, commands control its player instead. Both interfaces use the same
+library, metadata, and listening history. Use `radiocli help` for common commands
+or `radiocli help --all` for the full reference.
 
-Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and
-include `radiocli check` output with playback reports.
+Run `radiocli setup --mcp` to configure the optional local MCP integration for
+coding assistants. Ordinary CLI playback does not require MCP setup. The
+[CLI and agent guide](apps/docs/content/docs/getting-started/cli.mdx) covers
+commands, presets, shell completion, and integration details.
 
 ## Documentation
 
-- [Getting started](apps/docs/content/docs/index.mdx)
-- [Installation](apps/docs/content/docs/getting-started/install.mdx)
-- [Controls](apps/docs/content/docs/getting-started/tui-controls.mdx)
-- [Architecture](apps/docs/content/docs/architecture.mdx)
-- [Roadmap](apps/docs/content/docs/roadmap.mdx)
-- [Release packaging](apps/docs/content/docs/release-packaging.mdx)
+[Getting started](apps/docs/content/docs/index.mdx) ·
+[Controls](apps/docs/content/docs/getting-started/tui-controls.mdx) ·
+[Alarms](apps/docs/content/docs/alarms.mdx) ·
+[Troubleshooting](apps/docs/content/docs/troubleshooting.mdx) ·
+[Architecture](apps/docs/content/docs/architecture.mdx)
+
+Your library and listening history stay on your machine. Read
+[Privacy and security](apps/docs/content/docs/privacy-security.mdx) for the
+network requests and data flow.
 
-Run the documentation site locally with `npm run docs:dev`.
+Want to contribute? [CONTRIBUTING.md](CONTRIBUTING.md) covers development and
+checks. RadioCLI is [MIT licensed](LICENSE).
 
-## License
+---
 
-[MIT](LICENSE)
+![Radio on internet, from Silicon Valley](apps/docs/public/demo/silicon-valley-radio-on-internet.gif)

package/SECURITY.md

@@ -24,10 +24,32 @@ information, or unexpected command execution.
 - The app stores recents, favorites, settings, imports, and provider cache data
   locally under the user data directory.
 - RadioCLI does not proxy audio. It resolves public stream URLs and hands
-  playback to `mpv` or `ffplay`.
+  playback to native players.
 - Favoriting a Radio Browser station sends a best-effort vote to that public
   directory by default; the Settings screen can disable vote sharing.
 
+## Stream Certificate Verification
+
+RadioCLI enables mpv TLS verification, including redirected and nested streams,
+and enables TLS verification for direct FFmpeg/ffplay network media. Native
+trust stores and player certificate configuration apply. It never retries an
+HTTPS input with certificate verification disabled.
+
+FFmpeg releases in circulation do not propagate TLS policy to every resource
+opened by network playlist demuxers. Those inputs are restricted in FFmpeg
+fallbacks: use mpv for HLS/DASH/IMF playback, or a direct audio stream for AirPlay.
+Local FFmpeg inputs cannot open network protocols. The plain HTTP compatibility
+retry explicitly blocks both HTTPS and TLS, including changed redirects.
+
+Known upstream limitation: tested FFmpeg/OpenSSL builds can accept a trusted
+certificate with a mismatched **numeric IP address**, even with verification
+enabled. This also affects mpv builds using that native TLS implementation.
+DNS hostname mismatch fixtures are rejected. Prefer DNS station URLs. A
+separate Node preflight would not secure the player's actual connection, so
+RadioCLI does not present one as a fix. See the
+[reliability reference](apps/docs/content/docs/reliability.mdx#playback-recovery-and-secure-streams)
+and native smoke results for the precise guarantees and remaining limits.
+
 ## Supported Versions
 
 Until a tagged release cadence is established, security fixes target the active