Badges

CLAUDE.md

@@ -1,11 +1,57 @@
-# CLAUDE.md -- Shanty Architecture Reference
+# CLAUDE.md
 
-This document is the authoritative reference for any LLM working on the Shanty codebase. Read this before making changes.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## What Is Shanty?
 
 Shanty is a self-hosted music management application ("better Lidarr"). It searches MusicBrainz for music metadata, downloads from YouTube via yt-dlp, tags and organizes files, and serves the library over the Subsonic protocol. It is a Cargo workspace where each component is both a standalone CLI tool and a library consumed by the web app.
 
+## Development Commands
+
+A `justfile` provides common workflows. Run `just` to see all targets.
+
+```sh
+just check          # fmt + lint + test (full pre-commit check)
+just dev            # build frontend + run server
+just build          # cargo build --workspace
+just test           # cargo test --workspace
+just lint           # cargo clippy --workspace -- -D warnings
+just fmt            # cargo fmt
+just frontend       # cd shanty-web/frontend && trunk build
+just run            # cargo run --bin shanty
+```
+
+**Running single crate tests:**
+```sh
+cargo test --package shanty-db
+cargo test --package shanty-tag
+```
+
+**Running a single test by name:**
+```sh
+cargo test --package shanty-tag test_tag_with_match
+```
+
+**Frontend build (Yew/Trunk → WASM):**
+```sh
+cd shanty-web/frontend && trunk build              # dev
+cd shanty-web/frontend && trunk build --release    # optimized
+```
+
+**Running the server with verbose logging:**
+```sh
+cargo run --bin shanty -- -v      # info
+cargo run --bin shanty -- -vv     # debug
+cargo run --bin shanty -- -vvv    # trace
+```
+
+**MusicBrainz dump import subcommand:**
+```sh
+cargo run --bin shanty -- mb-import --download --data-dir /path/to/dumps
+```
+
+**Prerequisites:** Rust (stable, edition 2024), yt-dlp, ffmpeg, Python 3, ytmusicapi, Trunk. The `rust-toolchain.toml` pins stable and adds the `wasm32-unknown-unknown` target.
+
 ## Design Philosophy
 
 1. **Modular crates.** Each crate is a library and a CLI binary. The web app imports the library side; the CLI binary is for standalone use. Crates are git submodules hosted at `ssh://connor@git.rcjohnstone.com:2222/Shanty/{name}.git`. The exceptions are `shanty-config` and `shanty-data`, which are local workspace crates (not submodules).
@@ -20,7 +66,7 @@ Shanty is a self-hosted music management application ("better Lidarr"). It searc
 
 ## Workspace Structure
 
-All crates live in the workspace root `/home/connor/docs/projects/shanty/`.
+All crates live in the workspace root.
 
 | Crate | Purpose |
 |-------|---------|
@@ -137,10 +183,18 @@ The config is loaded once at startup and held in `Arc<RwLock<AppConfig>>`. It ca
 ## Testing
 
 ```sh
-cargo test --workspace
+cargo test --workspace           # all tests
+cargo test --package shanty-db   # single crate
 ```
 
-Integration tests per crate. Mock providers exist for MusicBrainz in tests. The frontend is excluded from workspace tests (it has its own build process via Trunk).
+The frontend is excluded from workspace tests (it has its own build process via Trunk).
+
+**Test patterns used across crates:**
+- **In-memory SQLite:** Integration tests create `Database::new("sqlite::memory:")` for fast, isolated DB testing. No fixtures directory -- data is inserted programmatically.
+- **Mock providers:** Each crate that depends on external APIs defines its own mock trait implementations (e.g., `MockProvider` for `MetadataProvider`, `MockBackend` for `DownloadBackend`). Mocks are self-contained per crate.
+- **Temp files:** `tempfile::TempDir` + `lofty` to create real MP3 files with valid ID3 tags for index/org/tag tests.
+- **Integration tests:** `{crate}/tests/integration.rs` (async via `#[tokio::test]`)
+- **Unit tests:** `#[cfg(test)]` modules inline in source files for pure functions (sanitization, parsing, normalization, template rendering).
 
 ## Important Constraints
 

readme.md

@@ -1,5 +1,10 @@
 # Shanty
 
+[![Docs](https://img.shields.io/badge/docs-getting%20started-blue)](docs/getting-started.md)
+[![API](https://img.shields.io/badge/docs-API%20reference-blue)](docs/api.md)
+[![Config](https://img.shields.io/badge/docs-configuration-blue)](docs/configuration.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Shanty is a self-hosted music management application. It searches MusicBrainz for artists and albums, downloads music from YouTube, tags and organizes files, and serves your library over the Subsonic protocol for streaming on any device.
 
 ## Features