add ambience music system: TUI crossfade, yt-dlp fetch, source tracking

- tools/run.py: pygame.mixer subsystem — polls session/ambience.md,
  crossfades tracks, shows ♫ in status bar
- tools/music-fetch.py: search/download from YouTube via yt-dlp,
  auto-increment filenames, --replace and --dry-run modes
- tools/ambience.py: companion CLI to set ambience state
- session/ambience.md: current ambience state file (DM writes here)
- session/ambience_options.md: ambience → file mapping table
- session/ambience_sources.md: file → YouTube URL tracking for re-download
- session/audio/ added to .gitignore (audio files not tracked in git)

session/ambience.md

@@ -0,0 +1 @@
+silence

session/ambience_options.md

@@ -0,0 +1,79 @@
+# Ambience Options
+
+Set the current ambience by writing its name into `session/ambience.md`.
+The TUI polls this file and crossfades to the matching track.
+
+Music files go in `session/audio/`. Supported formats: `.mp3`, `.ogg`, `.wav`.
+When multiple files are listed, one is chosen at random each time the ambience activates.
+
+## Requirements
+
+```bash
+pip install pygame yt-dlp
+```
+`ffmpeg` must also be installed on your system.
+
+## Fetching New Tracks
+
+Use the music-fetch tool to search YouTube and download tracks:
+
+```bash
+# Auto-search for a tavern track
+python3 tools/music-fetch.py tavern
+
+# Custom query
+python3 tools/music-fetch.py "deep fen" "swamp ambience D&D"
+
+# Specific video
+python3 tools/music-fetch.py tavern --url "https://youtu.be/..."
+
+# Replace all tracks for an ambience
+python3 tools/music-fetch.py tavern --replace
+
+# Preview without downloading
+python3 tools/music-fetch.py tavern --dry-run
+```
+
+Sources are recorded in `session/ambience_sources.md` so tracks can be
+re-downloaded without keeping audio files in git.
+
+## Available Ambiences
+
+| Ambience | Files |
+|----------|-------|
+| silence | (stops all music) |
+| calm | calm_01.ogg |
+| combat | combat_01.ogg |
+| dungeon | dungeon_01.ogg, dungeon_02.ogg |
+| forest | forest_01.ogg, forest_02.ogg |
+| tavern | tavern_01.ogg |
+| tension | tension_01.ogg |
+| town | town_01.ogg |
+| wilds | wilds_01.ogg |
+
+## Usage (DM)
+
+```bash
+# Switch to forest ambience
+echo "forest" > session/ambience.md
+
+# Stop music
+echo "silence" > session/ambience.md
+```
+
+Or use the companion CLI shortcut:
+
+```bash
+python3 tools/ambience.py forest
+python3 tools/ambience.py silence
+```
+
+## Status Display
+
+The TUI status bar shows the current ambience:
+
+```
+Dillion  ❤ 10  │  42 entries  │  3 todo  │  2026-06-24  │  ♫ tavern
+```
+
+If pygame is not installed, the music icon is absent and no audio plays.

session/ambience_sources.md

@@ -0,0 +1,7 @@
+# Ambience Sources
+
+Each entry maps a local audio file to its source URL so tracks can be
+re-downloaded without keeping the audio files in git.
+
+| File | Ambience | Source |
+|------|----------|--------|

session/tweaks.md

@@ -4,4 +4,6 @@ _Any house rules, custom tables, or modifications we've made._
 
 | Date | Change |
 |------|--------|
-|      |        |
+| 2026-06-23 | AGENTS.md rule #5 strengthened: "Log before narrating, not after." Log now gets written before the next scene description. |
+| 2026-06-23 | Created journal.md with TODO/DONE sections. Added TODO pane to run.py TUI (above the log window). |
+| 2026-06-24 | Added ambience music subsystem to run.py — polls `session/ambience.md`, crossfades via pygame.mixer. Created companion CLI `tools/ambience.py`, config file `session/ambience_options.md`, and `session/audio/` directory. |