docs: clarify Docker test setup requirements (#1383)

Dockerfile

@@ -1,8 +1,10 @@
 # See tests/README.md for instructions on how to run the tests.
 
 # tl;dr:
-# Run the following command in the adaptive-lighting repo folder to run the tests:
-# docker run -v $(pwd):/app basnijholt/adaptive-lighting:latest
+# 1. Clone HA core into ./core: git clone --depth 1 https://github.com/home-assistant/core.git core
+# 2. Setup symlinks: ./scripts/setup-symlinks
+# 3. Run tests (mount entire repo, not individual dirs, or symlinks break):
+#    docker run -v $(pwd):/app basnijholt/adaptive-lighting:latest
 
 # Optionally build the image yourself with:
 # docker build -t basnijholt/adaptive-lighting:latest .

tests/README.md

@@ -3,7 +3,23 @@
 To run the tests, check out the [CI configuration](../.github/workflows/pytest.yml) to see how they are executed in the CI pipeline.
 Alternatively, you can use the provided Docker image to run the tests locally or run them with VS Code directly in the dev container.
 
-To run the tests using the Docker image, navigate to the `adaptive-lighting` repo folder and execute the following command:
+## Prerequisites
+
+Before running tests with Docker, you need a local Home Assistant core checkout with symlinks:
+
+```bash
+# Clone HA core (one-time setup)
+git clone --depth 1 https://github.com/home-assistant/core.git core
+
+# Setup symlinks (one-time setup)
+./scripts/setup-symlinks
+```
+
+## Running tests with Docker
+
+Navigate to the `adaptive-lighting` repo folder and execute the following command.
+
+**Important:** Mount the entire repo (`-v $(pwd):/app`), not individual directories, or the symlinks will break.
 
 Linux / MacOS / Windows PowerShell:
 ```bash