@ciphore/radiocli 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -2,8 +2,75 @@
 
 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
 
@@ -478,3 +545,4 @@ Initial public release.
 [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

@@ -51,6 +51,16 @@ 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
 pre-release pass that includes live data, playback, packaging, and fresh-install

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
 
-On macOS configurations supported by 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,260 +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 checks that executables are
-available. Play a station to verify the actual audio path. Intel or older macOS
-installations should consult the platform matrix for alternative package routes.
-
-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.
 
-## Platform coverage
-
-RadioCLI separates core playback, storage, terminal rendering, desktop helpers,
-and native alarm services. A missing scheduler or clipboard helper leaves the
-other features available. `radiocli doctor --json` reports each capability,
-terminal and network policy, and runtime eligibility separately.
-
-The [platform matrix](apps/docs/content/docs/platforms.mdx) distinguishes required
-CI targets from verified installations, experimental community paths, and known
-runtime blockers. Node 22 and 24 are the reference test lines. BSD package plans,
-Termux, Haiku and illumos guidance do not imply that every OS/CPU combination has
-been exercised. AIX playback and Haiku's packaged Node 20 remain explicit gaps.
-Linux without a usable systemd user session can still run the player and TUI;
-reliable background alarms require a verified native adapter.
-
-Invocation preferences do not change saved settings:
-
-```bash
-RADIOCLI_ASCII=1 radiocli             # ASCII decoration; station names preserved
-NO_COLOR=1 radiocli                  # no color or background fills
-RADIOCLI_SCREEN_READER=1 radiocli     # readable controls; no visualizer animation
-RADIOCLI_OFFLINE=1 radiocli           # cached directories and saved stations
-RADIOCLI_LOW_BANDWIDTH=1 radiocli     # cached atlas; no automatic receiver scan
-```
+Launch `radiocli`, open Search or Explore, select a station, and press `Enter`
+to start playback.
 
-Offline mode disables directory, location, update, vote and receiver-discovery
-requests. An external player still needs a connection to listen to a live stream.
-For proxy, SSH, read-only storage and custom-player paths, see
-[troubleshooting](apps/docs/content/docs/troubleshooting.mdx).
-
-## Visual tour
+| 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 |
 
-These recordings come from the built TUI. Generate them locally with
-`npm run demo:assets`.
+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.
 
-### Library
+## Screenshots
 
-![Favorites and recent stations in the RadioCLI Library](apps/docs/public/demo/radiocli-library.gif)
+**Explore:** Move the map cursor with WASD or click a location to list stations
+by distance.
 
-### Explore
+![Interactive world map and station discovery in RadioCLI](apps/docs/public/demo/radiocli-explore-map.gif)
 
-![World map discovery in RadioCLI Explore](apps/docs/public/demo/radiocli-explore-map.gif)
+**Search:** Browse results with station names, countries, codecs, and bitrates.
 
-### Search
+![Searching internet radio stations in the terminal](apps/docs/public/demo/radiocli-search.gif)
 
-![Station search results in RadioCLI](apps/docs/public/demo/radiocli-search.gif)
+**Library:** Switch between favorites, recent stations, and imported streams.
 
-### Nearby
+![Favorites and recent stations in the RadioCLI library](apps/docs/public/demo/radiocli-library.gif)
 
-![Nearby stations in RadioCLI](apps/docs/public/demo/radiocli-nearby.gif)
+**Nearby:** Browse stations around your approximate location.
 
-### Stats
+![Nearby radio stations in RadioCLI](apps/docs/public/demo/radiocli-nearby.gif)
 
-![Local listening stats with selectable display colors](apps/docs/public/demo/radiocli-stats-colors.gif)
+**Stats:** Review listening activity and totals, with selectable display colors.
 
-## Essential controls
+![Listening stats and the 52-week activity graph with selectable colors](apps/docs/public/demo/radiocli-stats-colors.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; resume reconnects at the live edge with `mpv` |
-| `,` / `.` or `F7` / `F9` | Previous or next station |
-| `+` / `-` | Change volume |
-| `f` (`Ctrl+F` while typing in Search) | 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).
+## CLI and agent control
 
 ```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 https://example.com/live.mp3
-radiocli import stations.m3u
-radiocli export favorites.m3u
-radiocli alarm list
-radiocli alarm doctor
-radiocli update --install # Upgrade and repair enabled MCP registrations
+radiocli play jazz
+radiocli now
+radiocli favorite
+radiocli stop
 ```
 
-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 direct HTTP(S) station streams as well as `.m3u`, `.pls`, and
-`.xspf` playlists. Direct import is useful when a station cannot be found through
-an open radio directory—for example, an iHeartMedia station that is available
-only through its direct stream. Find the station's direct stream URL and run
-`radiocli import <stream-url> [station name]`, or enter
-`:import <stream-url> [station name]` in the TUI. RadioCLI reads available
-HTTP/ICY metadata to discover the name, codec, bitrate, and homepage; the name
-argument is optional and overrides the published name. Imported stations appear
-after favorites and before recently played stations. RadioCLI 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/platform` — host identity, independent capabilities, native command plans,
-  paths, terminal policy, networking and runtime eligibility
-- `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
+`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.
 
-```bash
-git clone https://github.com/Ciphore/RadioCLI.git
-cd RadioCLI
-npm ci
-npm run verify
-npm run dev
-```
-
-`npm run verify` checks types, lint, tests, the production build, and live provider
-data. `npm run fresh:check -- --require-mpv` tests packed installs with and without
-optional dependencies using a local WAV, real mpv IPC controls and MCP. See
-[contribution checks](CONTRIBUTING.md) for documentation and packaging validation.
-
-## Contributing
-
-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)
-- [Platform matrix](apps/docs/content/docs/platforms.mdx)
-- [Troubleshooting](apps/docs/content/docs/troubleshooting.mdx)
-- [Controls](apps/docs/content/docs/getting-started/tui-controls.mdx)
-- [Architecture](apps/docs/content/docs/architecture.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

package/dist/agent/alarm-service.js

@@ -1,4 +1,5 @@
-import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone, nextOccurrenceForAlarm } from '../alarms/schedule.js';
+import { AlarmOccurrenceCache } from '../alarms/occurrence-cache.js';
+import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone } from '../alarms/schedule.js';
 import { connectActiveAlarms } from '../alarms/active-session.js';
 import { createSchedulerService } from '../alarms/scheduler.js';
 export class AgentAlarmService {
@@ -6,6 +7,7 @@ export class AgentAlarmService {
     resolveStation;
     scheduler;
     handoffToInteractive;
+    occurrences = new AlarmOccurrenceCache();
     constructor(store, resolveStation, scheduler = createSchedulerService(), handoffToInteractive) {
         this.store = store;
         this.resolveStation = resolveStation;
@@ -45,7 +47,7 @@ export class AgentAlarmService {
                 keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? false
             }
         };
-        const alarm = this.store.addAlarm(alarmInput);
+        const alarm = await this.store.addAlarm(alarmInput);
         await this.syncSaved(alarm);
         return this.describe(alarm);
     }
@@ -55,7 +57,7 @@ export class AgentAlarmService {
         const fallbackStation = input.clearFallback
             ? undefined
             : input.fallbackStationId ? await this.requiredStation(input.fallbackStationId) : alarm.playback.fallbackStation;
-        const updated = this.store.updateAlarm(alarm.id, {
+        const updated = await this.store.updateAlarm(alarm.id, {
             label: input.label === undefined ? alarm.label : cleanLabel(input.label),
             enabled: input.enabled ?? alarm.enabled,
             station,
@@ -76,7 +78,7 @@ export class AgentAlarmService {
         return this.describe(updated);
     }
     async setEnabled(id, enabled) {
-        const alarm = this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
+        const alarm = await this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
         await this.syncSaved(alarm);
         return this.describe(alarm);
     }
@@ -84,8 +86,9 @@ export class AgentAlarmService {
         if (!confirm)
             throw new Error('Alarm removal requires confirm=true. List alarms first and confirm the exact alarm ID with the user.');
         const alarm = this.requiredAlarm(id);
-        await this.scheduler.remove(alarm.id);
-        if (!this.store.removeAlarm(alarm.id))
+        const disabled = await this.store.toggleAlarm(alarm.id, false);
+        await this.scheduler.remove(disabled.id);
+        if (!await this.store.removeAlarm(alarm.id))
             throw new Error(`Alarm not found: ${id}`);
         return { ok: true, removed: alarm.id };
     }
@@ -117,7 +120,7 @@ export class AgentAlarmService {
             enabled: alarm.enabled,
             station: { id: `${alarm.station.provider}:${alarm.station.id}`, name: alarm.station.name },
             schedule: alarm.schedule,
-            nextOccurrence: nextOccurrenceForAlarm(alarm, new Date())?.toISOString() ?? null,
+            nextOccurrence: this.occurrences.next(alarm, new Date())?.toISOString() ?? null,
             playback: {
                 volume: alarm.playback.volume,
                 fadeSeconds: alarm.playback.fadeSeconds,

package/dist/agent/cli.js

@@ -1,3 +1,6 @@
+import { airPlayPolicy } from '../player/airplay-policy.js';
+import { readSettingsWithoutMigration } from '../storage/read-settings.js';
+import { defaultLibraryPath } from '../storage/store.js';
 import { AgentRadioService, stationForAgent } from './service.js';
 import { configureMcpIntegrations, mcpIntegrationReport, portableMcpConfig } from './mcp-install.js';
 import { runMcpServer } from './mcp-server.js';
@@ -64,7 +67,7 @@ export async function runAgentCliCommand(args, runtime) {
     else if (command === 'done')
         value = await service.runCompletionPreset();
     else
-        throw new Error('Usage: radiocli agent <status|search|browse|play|pause|resume|stop|next|previous|volume|mute|unmute|favorite|unfavorite|stats|appearance|airplay|preset|done>');
+        throw new Error(agentCommandUsage());
     console.log(JSON.stringify(value, null, 2));
 }
 function parseBrowseKind(value) {
@@ -191,3 +194,15 @@ function assertMcpInstallSucceeded(results, action) {
         return;
     throw new Error(`RadioCLI was ${action} where possible, but ${failed.length} integration${failed.length === 1 ? '' : 's'} failed: ${failed.map(result => `${result.client} (${result.detail})`).join('; ')}`);
 }
+export function agentCommandUsage() {
+    let enabled = airPlayPolicy().enabled;
+    if (process.platform === 'linux') {
+        try {
+            enabled = airPlayPolicy({ linuxAirPlayEnabled: readSettingsWithoutMigration(defaultLibraryPath())?.linuxAirPlayEnabled === true }).enabled;
+        }
+        catch {
+            enabled = false;
+        }
+    }
+    return `Usage: radiocli agent <status|search|browse|play|pause|resume|stop|next|previous|volume|mute|unmute|favorite|unfavorite|stats|appearance${enabled ? '|airplay' : ''}|preset|done>`;
+}