initial state: muzick music player + recommendation engine

AGENTS.md

@@ -0,0 +1,28 @@
+# Muzick — Agent Context
+
+music player + recommendation engine. `muzick.kvmx.ru:5174`.
+
+## ports
+- `5174:80` — frontend (docker)
+- `3000:3000` — backend api (docker, internal)
+
+## docker-compose services
+- `db` — postgres 16, schema at `backend/src/db/schema.sql`
+- `redis` — redis 7, job queue
+- `search` — typesense 0.25.1 (pinned), full-text search
+- `backend` — fastify/typescript, music dir mount at `/music`
+- `frontend` — vite SPA, served by nginx inside container
+- `worker` — metadata enrichment (lastfm, discogs, musicbrainz), `network_mode: host`
+
+## env (.env)
+- `LASTFM_API_KEY`, `LASTFM_SHARED_SECRET`
+- `MUSICBRAINZ_CONTACT`
+- `DISCOGS_TOKEN`
+- `SOCKS_PROXY_URL=socks5://192.168.1.104:10808` — for external api calls
+
+## gotchas
+- worker uses `network_mode: host` + SOCKS5 proxy for metadata lookups.
+- typesense is pinned to 0.25.1 — not latest. don't bump casually, the api changes between major versions.
+- db schema is in `backend/src/db/schema.sql` — dropped in via docker-entrypoint-initdb.d.
+- music dir is read-only bind from `/mnt/hdd1/media/Music`.
+- there's also an older `muzick.service` systemd unit that runs the backend solo on port 5213 — that's the pre-docker version and may conflict. the docker compose is the active deployment.