Updated docs

compose.yml

@@ -3,14 +3,11 @@ services:
     build: .
     ports:
       - "8085:8085"
-      - "6080:6080"  # noVNC for YouTube login
+      # - "6080:6080"  # Optional: expose if YouTube login iframe doesn't load
     volumes:
       - ./config:/config
-      - shanty-data:/data
+      - ./data:/data  # Database, downloads, MB data. Put on SSD if possible.
       - /path/to/music:/music  # Change this to your music library path
     environment:
       - SHANTY_WEB_BIND=0.0.0.0
     restart: unless-stopped
-
-volumes:
-  shanty-data:

docs/features/monitoring.md

@@ -1,32 +1,38 @@
 # Artist Monitoring
 
-Monitoring lets Shanty automatically detect when your favorite artists release new music. When a new album or single is found, it is added to your watchlist and queued for download.
+Monitoring lets Shanty automatically detect when your favorite artists release new music. When a new album or single is found, its tracks are added to your watchlist and queued for download.
 
-## How monitoring differs from watching
+## Watching tracks vs. monitoring artists
 
-- **Watching** an artist means you have added some or all of their existing discography to your watchlist. Watched tracks go through the download pipeline.
+In Shanty, **tracks** are what you watch. When you click "Watch All" on an artist page, every track in their current discography becomes a watched track. Those watched tracks get synced, downloaded, tagged, and organized by the pipeline.
-- **Monitoring** an artist means Shanty periodically checks MusicBrainz for new releases that were not in the artist's discography when you first added them. When something new appears, it is automatically added to your watchlist.
 
-You can watch an artist without monitoring them (just download their existing catalog), and you can monitor a watched artist to stay up to date with new releases.
+**Monitoring** is different. Monitoring an artist means Shanty periodically checks MusicBrainz for new release groups (albums, singles, EPs) that did not exist when you last looked. When new releases are found, their tracks are automatically added to your watchlist.
+
+In short:
+
+- **Watching** is about tracks: "I want these specific tracks in my library."
+- **Monitoring** is about artists: "Tell me when this artist puts out something new, and watch those tracks for me automatically."
+
+You can watch tracks from an artist without monitoring them (just grab their existing catalog and move on). You can also monitor an artist to stay current with future releases.
 
 ## How to set up
 
 1. Open the Shanty web UI and navigate to an artist's page (search for them or open them from your library).
 2. Click the **Monitor** button on the artist page.
-3. The artist is now monitored. A badge indicates their monitoring status.
+3. The artist is now monitored. A "Monitored" badge appears next to their name, and a checkmark shows in the Library view.
 
-To stop monitoring an artist, click the **Monitor** button again to toggle it off.
+To stop monitoring an artist, click the **Unmonitor** button on their page.
 
 ## How it works
 
 When monitoring is enabled, Shanty runs a background check on a schedule:
 
 1. For each monitored artist, it fetches the current list of release groups from MusicBrainz.
-2. It compares this against the release groups already in the watchlist.
+2. It compares this against the tracks already in your watchlist.
-3. Any new release groups (albums, singles, EPs) are expanded into individual track wanted_items and added to the watchlist.
+3. Any new release groups are expanded into individual tracks and added to the watchlist.
 4. The artist's `last_checked_at` timestamp is updated.
 
-If you have the pipeline scheduler enabled (the default), new releases are automatically downloaded on the next pipeline run.
+If you have the pipeline scheduler enabled (the default), new tracks are automatically downloaded on the next pipeline run.
 
 ## Automatic scheduling
 
@@ -40,7 +46,7 @@ Both the monitor check and the download pipeline run on configurable schedules:
 This means that in the default configuration:
 
 1. The monitor checks for new releases every 12 hours.
-2. If new releases are found, they are added to the watchlist.
+2. If new releases are found, their tracks are added to the watchlist.
 3. Within 3 hours, the pipeline runs automatically, downloading and processing the new tracks.
 
 ## Configuring schedules
@@ -69,14 +75,10 @@ When disabled, you can still trigger checks manually from the Dashboard.
 
 ## Manual checks
 
-You can trigger a monitor check at any time from the Dashboard by clicking **Check Monitored** (under the system actions). The results show how many artists were checked, how many new releases were found, and how many tracks were added.
+You can trigger a monitor check at any time from the Dashboard by clicking **Check Monitored Artists** (under the individual actions). The results show how many artists were checked, how many new releases were found, and how many tracks were added.
 
 Similarly, you can trigger the pipeline manually by clicking **Set Sail** at any time.
 
-## Viewing monitored artists
-
-The monitoring status is visible on each artist's page. You can also check the current monitor status via the API at `GET /api/monitor/status`, which returns a list of all monitored artists with their last check timestamps.
-
 ## Skipping scheduled runs
 
-If you want to skip the next scheduled pipeline or monitor run without disabling them permanently, you can do so from the Dashboard. The skip is a one-time action -- the schedule resumes after the skipped run.
+If you want to skip the next scheduled pipeline or monitor run without disabling them permanently, you can do so from the Dashboard. The skip is a one-time action -- the schedule resumes normally after the skipped run.

docs/features/musicbrainz-db.md

@@ -20,7 +20,7 @@ If you are casually using Shanty for a few artists, the caching system works wel
 
 - **Download size:** approximately 24 GB (compressed JSON dumps from MusicBrainz)
 - **Database size:** approximately 16 GB (the resulting SQLite database)
-- **Disk type:** SSD strongly recommended. The import writes millions of rows, which is very slow on spinning disks.
+- **Disk type:** SSD strongly recommended for best performance. On an SSD, artist pages load in under a second. On a spinning hard drive, the database still works and is a big improvement over the API (a few seconds per page load instead of 30-60 seconds), but you will notice the difference compared to SSD.
 - **Time:** 12-24 hours for the initial import, depending on your hardware and disk speed.
 - **Disk space total:** You need roughly 40 GB free during import (dumps + database). After import, you can delete the dump files to reclaim the 24 GB.
 

docs/features/playlists.md

@@ -4,7 +4,7 @@ Shanty can generate playlists from your library using similar-artist data from L
 
 ## Requirements
 
-Playlist generation using the **similar-artist** strategy requires a Last.fm API key. Set it via the `SHANTY_LASTFM_API_KEY` environment variable:
+Playlist generation requires a Last.fm API key. Set it via the `SHANTY_LASTFM_API_KEY` environment variable:
 
 ```yaml
 # In docker-compose.yml
@@ -14,29 +14,40 @@ environment:
 
 Get a free API key at: https://www.last.fm/api/account/create
 
-Other playlist strategies (genre, random, smart rules) do not require an API key.
+When creating your API account, use any application name and leave the callback URL blank or enter `http://localhost`.
 
 ## Generating a playlist
 
 1. Open the Shanty web UI and go to **Playlists**.
 2. Click the **Generate** tab.
-3. Choose a generation strategy:
+3. Search for and select one or more **seed artists** from your library. The dropdown shows all artists you have tracks for.
-   - **Similar Artists** -- Start with one or more seed artists and build a playlist from their music and music by similar artists. This is the most useful strategy for discovering connections in your library.
+4. Adjust **popularity bias** (higher values favor well-known tracks, lower values dig deeper).
-   - **Genre** -- Filter tracks by genre tags.
+5. Set the **track count** (how many tracks in the playlist).
-   - **Random** -- A random selection from your library.
+6. Choose **ordering**:
-   - **Smart Rules** -- Define rules based on track attributes (artist, album, year, genre, etc.).
+   - **Interleave** -- spreads artists evenly throughout the playlist, avoiding back-to-back tracks from the same artist.
-4. For the Similar Artists strategy:
+   - **By Score** -- highest-scored tracks first (most similar to your seeds, weighted by popularity).
-   - Search for and select one or more **seed artists**.
+   - **Random** -- fully shuffled.
-   - Adjust **popularity bias** (higher values favor well-known tracks, lower values dig deeper).
+7. Click **Generate**.
-   - Set the **track count** (how many tracks in the playlist).
-   - Choose **ordering**: interleave (mix artists evenly), score (highest match first), or random.
-5. Click **Generate**.
 
 The generated playlist is shown as a preview. You can then save it or adjust the parameters and regenerate.
 
-## Saving a playlist
+### How generation works
 
-After generating a playlist, click **Save** to give it a name and store it. Saved playlists appear in the **Saved** tab.
+Shanty uses Last.fm's similar-artist data to find tracks from artists related to your seeds. For example, if you seed with "Radiohead," the playlist might include tracks by Radiohead, Thom Yorke, Portishead, Massive Attack, and other similar artists -- but only tracks that actually exist in your library.
+
+The **popularity bias** slider (0-10) controls the balance:
+- Higher values favor popular, well-known tracks from each artist.
+- Lower values give more equal weight to deep cuts and lesser-known tracks.
+
+Multiple seed artists are blended together -- artists similar to more of your seeds get higher scores.
+
+## Creating a blank playlist
+
+From the **Saved** tab, click **New** to create an empty playlist and open it in the editor. You can then add tracks manually.
+
+## Saving a generated playlist
+
+After generating a playlist, enter a name and click **Save Playlist**. Saved playlists appear in the **Saved** tab.
 
 ## Editing a playlist
 
@@ -46,47 +57,15 @@ After generating a playlist, click **Save** to give it a name and store it. Save
    - **Drag and drop** tracks to reorder them.
    - **Remove** tracks by clicking the remove button next to each track.
    - **Add** tracks by searching in the track picker at the bottom.
-   - **Rename** the playlist or update its description.
+   - **Rename** the playlist.
+4. Click **Save** when done.
 
 ## Exporting as M3U
 
-To export a playlist as an M3U file (compatible with most music players):
+From the **Saved** tab, click **M3U** on any playlist to download it as an M3U file. M3U files are compatible with most music players and contain file paths relative to your library.
-
-1. Open a saved playlist.
-2. Click **Export M3U**.
-3. The file downloads to your computer.
-
-M3U files contain file paths relative to your library, so they work with any music player that has access to the same library directory.
 
 ## Playlists via Subsonic
 
 Saved playlists are available through the Subsonic API. Any Subsonic client that supports playlists (most do) can see and play your Shanty playlists.
 
 To use this, make sure you have [Subsonic set up](subsonic.md) with a Subsonic password configured.
-
-## Generation strategies explained
-
-### Similar Artists
-
-This uses Last.fm's similar-artist data to find tracks from artists related to your seeds. For example, if you seed with "Radiohead," the playlist might include tracks by Radiohead, Thom Yorke, Portishead, Massive Attack, and other similar artists -- but only tracks that exist in your library.
-
-The **popularity bias** slider controls the balance:
-- High bias (closer to 1.0): favors popular/well-known tracks
-- Low bias (closer to 0.0): gives equal weight to all tracks
-
-### Genre
-
-Filters your library by genre tags and selects tracks that match. You can specify one or more genres.
-
-### Random
-
-A random sample from your entire library. If ordering is not set to "random," tracks are ordered by artist/album for easier listening.
-
-### Smart Rules
-
-Define custom rules like:
-- Artist contains "Pink Floyd"
-- Year is between 1970 and 1980
-- Genre is "Progressive Rock"
-
-Tracks matching all rules are included, up to the count limit.

docs/features/subsonic.md

@@ -20,7 +20,9 @@ The Subsonic protocol uses its own authentication system, separate from your Sha
 2. Find the **Subsonic API** section.
 3. Enter a password and click **Save**.
 
-**Security note:** The Subsonic protocol transmits passwords as MD5 hashes (not encrypted). This is a limitation of the protocol itself. Do not reuse a password you use for other services. The Subsonic password is stored in plain text in the database, per the protocol specification.
+**Important -- please read:** The Subsonic password is stored as **plain text** in the database. This is not a bug or an oversight. The Subsonic protocol requires the server to verify authentication by computing `md5(password + client_salt)`, which means the server must have access to the original password. There is no way to store it securely (like a one-way hash) and still be compatible with the protocol. This is a well-known limitation of the Subsonic standard and is how all Subsonic-compatible servers handle it, including Navidrome.
+
+Because of this, **do not reuse a password from any other account**. Choose a simple, unique password that you use only for Subsonic access. Your Shanty web login password is stored securely (Argon2id hash) and is completely separate.
 
 ### 2. Configure your client
 

docs/features/youtube-auth.md

@@ -25,20 +25,6 @@ There is a small but real risk that Google may flag your account for unusual act
 
 Shanty extracts the YouTube cookies from Firefox and saves them. From this point forward, all downloads use your authenticated session.
 
-## Docker port requirement
-
-The noVNC interface runs on port **6080** by default. Your `docker-compose.yml` must expose this port:
-
-```yaml
-ports:
-  - "8085:8085"
-  - "6080:6080"  # Required for YouTube login
-```
-
-If you are running Shanty on a remote server, you need to access noVNC from your browser at `http://your-server-ip:6080`. Make sure firewalls allow this port during the login process. You can close the port afterward if you want -- it is only needed during initial login and manual re-authentication.
-
-The noVNC port is configurable via `download.vnc_port` in the config file.
-
 ## How auto-refresh works
 
 YouTube cookies expire roughly every 2 weeks. Shanty automatically refreshes them using headless Firefox (no visible browser window needed):

docs/getting-started.md

@@ -24,20 +24,17 @@ Create `docker-compose.yml` with these contents:
 ```yaml
 services:
   shanty:
-    image: git.squid-inc.dev/connor/shanty:latest
+    image: git.rcjohnstone.com/connor/shanty:latest
     ports:
       - "8085:8085"
-      - "6080:6080"
+      # - "6080:6080"  # Optional: expose if YouTube login iframe doesn't load
     volumes:
       - ./config:/config
-      - shanty-data:/data
+      - ./data:/data
       - /path/to/your/music:/music
     environment:
       - SHANTY_WEB_BIND=0.0.0.0
     restart: unless-stopped
-
-volumes:
-  shanty-data:
 ```
 
 Replace `/path/to/your/music` with the actual path to where you want your music stored. For example, `/home/yourname/Music` on Linux or `/Users/yourname/Music` on Mac.
@@ -47,7 +44,7 @@ Replace `/path/to/your/music` with the actual path to where you want your music
 | Mount point | Purpose |
 |-------------|---------|
 | `./config` | Stores your configuration file (`config.yaml`). Lives next to your docker-compose.yml. |
-| `shanty-data` | Stores the database and downloaded files before they are organized. Managed by Docker. |
+| `./data` | Stores the database, downloaded files, and MusicBrainz data. Put this on an SSD if possible. |
 | `/music` | Your music library. This is where organized, tagged music ends up. |
 
 ## Step 2: Start the container
@@ -87,6 +84,8 @@ On first launch, you will see a setup screen. Choose a username and password (at
 
 You will see the artist appear on the **Library** page with track counts showing how many tracks are wanted versus owned.
 
+**Note:** Browsing artist discographies may be slow on the first visit (30-60 seconds per artist) because Shanty queries MusicBrainz one request at a time. This gets much faster after the first visit (results are cached). For instant lookups, you can [import the MusicBrainz database locally](features/musicbrainz-db.md) -- but this is optional and can be done later.
+
 ## Step 5: Download your music
 
 Click the **Set Sail** button on the Dashboard. This runs the full pipeline:

readme.md

@@ -23,23 +23,20 @@ This is the recommended way to run Shanty.
 ```yaml
 services:
   shanty:
-    image: git.squid-inc.dev/connor/shanty:latest
+    image: git.rcjohnstone.com/connor/shanty:latest
     ports:
       - "8085:8085"
-      - "6080:6080"
+      # - "6080:6080"  # Optional: expose if YouTube login iframe doesn't load
     volumes:
       - ./config:/config
-      - shanty-data:/data
+      - ./data:/data
       - /path/to/your/music:/music
     environment:
       - SHANTY_WEB_BIND=0.0.0.0
     restart: unless-stopped
-
-volumes:
-  shanty-data:
 ```
 
-**2.** Replace `/path/to/your/music` with the directory where you want your music library stored.
+**2.** Replace `/path/to/your/music` with the directory where you want your music library stored. The `./data` directory will be created automatically and stores the database, downloads, and any imported MusicBrainz data. If you plan to use the [local MusicBrainz database](docs/features/musicbrainz-db.md), put this on an SSD.
 
 **3.** Start the container:
 
@@ -57,7 +54,7 @@ For developers who want to build and run locally:
 
 ```sh
 # Prerequisites: Rust (edition 2024), yt-dlp, ffmpeg, Python 3, ytmusicapi, Trunk
-git clone https://git.squid-inc.dev/connor/shanty.git
+git clone https://git.rcjohnstone.com/connor/shanty.git
 cd shanty
 
 # Build frontend