docs: code map, regression findings, and HTTP API reference

CLAUDE.md gains a function-level code map of web.py/webui.html, a
"verifying changes" section (test scope, no-node UI checks, endpoint
smoke pattern, Windows commit-message gotcha), and findings recorded as
guard rails: why detection must stay adaptive (fixed threshold produced
~600 useless sections/day), why section playback must stay clip-based
(libsndfile FLACs have no SEEKTABLE so browser seeks bisect the file),
and the five places analysis params are coupled.

README gains the adaptive-detection and clip-review features up top, an
HTTP API table for scripting, and a corrected Docker analyses-cache
paragraph (the rw mount is ./recordings/analyses layered over the ro
recordings mount, not a separate ./analyses dir).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -13,7 +13,9 @@ Records from multiple simultaneous sources — Icecast/HTTP streams and ALSA sou
 - OGG / Opus / FLAC header injection so every split file is independently playable
 - Auto-reconnect on stream drops or device errors
 - WAV and FLAC output for soundcard sources
-- Web UI to browse, download, and analyse recordings
+- Web UI to browse, play, cut, and download recordings — including files still being written
+- **Loud-event detection** — adaptive: events are flagged by how far they rise above the rolling background noise, not by absolute level, and ranked by score
+- **Clip review** — detected sections play as instant server-rendered clips with auto-advance, so a whole day can be reviewed like a highlights reel
 
 ---
 
@@ -21,7 +23,7 @@ Records from multiple simultaneous sources — Icecast/HTTP streams and ALSA sou
 
 ```bash
 pip install requests              # stream recording
-pip install numpy soundfile       # FLAC output + web waveform analysis (optional)
+pip install numpy soundfile       # FLAC output + web analysis/clips for FLAC (optional)
 
 cp config.example.ini config.ini
 # edit config.ini to add your sources
@@ -173,6 +175,25 @@ Shows recordings grouped by day with collapsible sections. Features:
 - **Fast loading** — analysis results are cached server-side on disk and client-side per session; cached waveforms load only for expanded day groups, and collapsed days fetch nothing until opened.
 - **WCAG-compliant** — skip link, `aria-expanded`/`aria-controls` on the player toggle, `aria-live` status, focus management, `role=img` on SVG waveforms.
 
+### HTTP API
+
+Everything the UI does goes through these endpoints, so they can also be scripted:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/files` | File listing with size, mtime, duration, recording state, cached-analysis params |
+| `GET /api/analyze?file=&margin=&min_gap=` | Loud-section analysis: `rms_display` (~800-point waveform), scored `sections`, `duration` |
+| `GET /api/clip?file=&start=&end=` | Section of a WAV/FLAC decoded server-side, returned as a standalone WAV (max 600 s) |
+| `GET /api/cut?file=&start=&end=` | ffmpeg-trimmed copy of the file as a download |
+| `GET /stream/<name>` | Inline playback with HTTP Range support; live files get an on-the-fly patched header |
+| `GET /download/<name>` | Raw file download |
+| `GET /api/status` | Currently recording files (`status.json` passthrough) |
+| `GET /api/storage` | Disk free/total |
+| `GET /api/config` | Server-side defaults for margin and min-gap (seeds the UI controls) |
+| `DELETE /api/files/<name>` | Delete a recording and its analysis cache |
+
+Analysis, clips, cut, and delete return `409` for files that are still being recorded.
+
 ---
 
 ## How it works
@@ -216,7 +237,7 @@ docker compose down && docker compose up -d --build
 
 **Log file in Docker:** The recorder always logs to stdout, so `docker compose logs -f` shows live output. To persist logs on the host, set `log_file = /app/recordings/recorder.log` in `config.ini` (the `recordings` directory is the bind mount).
 
-**Analysis cache in Docker:** The web container mounts `./recordings` read-only, so analysis cache files are written to a separate `./analyses` bind mount (mapped to `/analyses` inside the container). This directory is created automatically by Docker Compose on first run. Cache files are stored as `analyses/<filename>.analysis.json` on the host.
+**Analysis cache in Docker:** The web container mounts `./recordings` read-only; a separate read-write bind mount of `./recordings/analyses` is layered on top so analysis cache files can still be written. The directory is created automatically by Docker Compose on first run. Cache files are stored as `recordings/analyses/<filename>.analysis.json` on the host.
 
 **File retention:** Individual recordings can be deleted from the web UI. For bulk / automated cleanup, add a cron job on the host:
 ```bash