fix(daemon): robust auto-advance; ensure next track starts even if playback fails

1 files changed, 55 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..31f1205
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# 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` or `rsplayer 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 (added in v0.9)
+
+## Task-Specific Guidelines
+- **CLI changes**: Update clap subcommands (including `rsp scan` and `rsp settings`) and regenerate shell completion scripts
+- **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
+
+## Completed Features (Phase 2)
+- [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 (`rsplayer queue`)
+- [x] Auto-play next track when current track ends
+
+## Remaining Work
+- Album shuffle mode (`ShuffleMode::Album`)
+- Database integration for queue persistence
+- `rsplayer queue` command for queue management
+- Scrobbling (Last.fm/ListenBrainz)
+- Database scanning and schema
+- Shell completion scripts
+- Systemd service unit