# Agent Instructions for rsplayer

## Overview
Rust CLI music player daemon for GNU/Linux with shell autocompletion, SQLite library database, Unix socket IPC, and Last.fm/ListenBrainz scrobbling.

## Required Verification Commands
Run these before completing any task:
- Lint: `cargo clippy -- -D warnings`
- Format check: `cargo fmt --check`
- Test: `cargo test`
- Build: `cargo build`

## Development Workflow
- Use `rsp restart` to kill any running daemon and start a new one (useful during development)
- Daemon runs in background; restart command handles cleanup automatically
- After making changes to audio/playback/daemon code, always restart the daemon to test changes

## Code Conventions
- Use `directories` crate to resolve XDG paths (respect `XDG_CONFIG_HOME` and `XDG_RUNTIME_DIR` environment variables)
- Follow standard Rust style (enforced by `cargo fmt`)
- Never commit changes unless explicitly requested by the user
- Update shell completions when adding/modifying CLI subcommands
- Use `rand` crate for shuffle/randomization features

## Task-Specific Guidelines
- **CLI changes**: Update clap subcommands (including `rsp scan` and `rsp settings`) and regenerate shell completion scripts
- **Completion changes**: `rsp db-complete` has a two-tier strategy — if the query looks like a path (`./`, `../`, `~/`, or `/`), it lists filesystem entries directly; otherwise it queries the DB in a thread with a 100ms timeout and falls back to filesystem completion on timeout or no match. The zsh script (`completions/_rsp`) is manually edited (not clap-generated) and concatenated after the clap output during install
- **Database changes**: Update SQLite schema and `rsp scan` logic
- **Playback changes**: Modify daemon audio engine or queue management code
  - Audio engine uses cpal for output and symphonia for decoding
  - Queue system implemented in daemon.rs with `Queue` struct
  - Sample buffering implemented to prevent buffer underruns - uses device default sample rate, not file's sample rate
  - Pause/resume uses cpal stream `pause()`/`play()` methods
- **Scrobbling changes**: Update Last.fm/ListenBrainz client implementation
- **Config/Settings changes**: Update config schema, `rsp settings` subcommands, and scan interval/auto-scan logic
- **Notification changes**: Update `notify-rust` dependency in Cargo.toml if needed; notification functions are in `src/notification.rs`; notification call sites are in `src/daemon.rs` (track events) and `src/audio.rs` (error events)

## Completed Features
- [x] Unix socket daemon IPC
- [x] Audio engine with play/pause/stop/volume
- [x] Queue system with in-memory tracking and auto-advance
- [x] Shuffle mode: `none`, `all`, and `album` (structure ready) implemented
- [x] Next/previous track commands with queue navigation
- [x] Resume CLI subcommand
- [x] Directory playback - queues all audio files in folder recursively
- [x] Fixed audio buffer underrun issues by using device default sample rate
- [x] Queue display with pager support (`rsp queue`)
- [x] Auto-play next track when current track ends
- [x] Metadata extraction and display (INDEX. ARTIST - TITLE format, falls back to filename)
- [x] `rsp scan` with `--force` and `--paths` options
- [x] `rsp settings` subcommands (get/set/list/unset)
- [x] Shell completions (`rsp completions bash|zsh|fish|powershell|elvish`)
- [x] Unit tests for Player, Track, and ShuffleMode
- [x] Smart autocompletion: DB completion with 100ms timeout, filesystem path fallback, path-prefix detection (`./`, `../`, `~/`, `/`)
- [x] Desktop notifications for track changes, queue end, and errors

## Remaining Work
Check @TODO.md