Initial Arcana FX soundboard

BUILD_BRIEF.md

@@ -0,0 +1,41 @@
+Build a deployable Docker Compose webapp named Arcana FX.
+
+Purpose:
+- D&D effects soundboard now; future control surface for lights/effects later.
+- Frontend dashboard with tiles for audio effects. Pressing a tile tells backend to play that audio through Home Assistant.
+
+Source audio:
+- Filestash public share URL: https://files.fisoft.eu/s/FHBaJ8Z
+- Put that URL and share id in config/config.json.
+- The Filestash API flow discovered externally:
+  1. POST https://files.fisoft.eu/api/share/FHBaJ8Z/proof with header X-Requested-With: XmlHttpRequest. It returns JSON with path /DnD/Audio/ and sets proof cookie.
+  2. List directories with GET https://files.fisoft.eu/api/files/ls?path=<path>&share=FHBaJ8Z with same header and proof cookie. Root path is '/'. Results contain files/directories.
+  3. Stream/download file with GET https://files.fisoft.eu/api/files/cat?path=<path>&share=FHBaJ8Z with proof cookie.
+- Backend should cache/list recursive audio effects. Accept .mp3 .ogg .flac .wav .m4a. Ignore desktop.ini. Prefer not to preload/download all audio.
+- Backend must expose an intranet media proxy endpoint for a selected path, e.g. /media?path=..., because Home Assistant needs a URL it can fetch. The backend should fetch from Filestash with its proof cookie and stream it.
+
+Home Assistant:
+- URL from env: HA_URL=http://192.168.33.33:8123
+- Token from env only, never frontend and do not commit it.
+- Allowed media player entity must be hardcoded/config-limited to media_player.audio_test_media_player.
+- Backend service should expose only narrow endpoints: list effects, play a selected known effect path, stop optional. It must not accept arbitrary HA service/entity calls.
+- Play implementation should call POST /api/services/media_player/play_media with entity_id media_player.audio_test_media_player, media_content_id as PUBLIC_BASE_URL + /media?path=..., media_content_type audio/mpeg or audio/ogg etc.
+
+Deployment:
+- Use docker-compose.yml, not raw docker run.
+- Expose app on host port 8091.
+- Frontend can be served by backend or nginx; keep simple. Backend service must be separate logical component/code from frontend speaker controls.
+- Include Dockerfile, package files, README.
+- Add health endpoint.
+- Include .env.example but not .env.
+
+Frontend:
+- Creative dark fantasy control-room style.
+- Search, category filters, status messages.
+- Tiles should show name/category/path/type.
+- Add future-light-control placeholders visibly but disabled/coming soon.
+
+Tech preference:
+- Use Node.js/Express backend and static frontend unless you have a better simple choice.
+- Keep dependencies minimal.
+- Include basic validation and error handling.