diff --git a/.gitignore b/.gitignore
index 6b8a55b..3a79811 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,3 +58,4 @@ __screenshots__/
 
 .deploy
 *.xcf
+sync-secrets.sh
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c371254
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# web_server
+
+Dockerized multi-service personal website.
+
+## Untracked Files Requiring Manual Setup
+
+These files are git-ignored and must be created or obtained manually before running the stack.
+
+### `.env`
+
+Environment variables used by all services. No example file is provided — see `docker-compose.yml` for the full list of referenced variables (database credentials, hostnames, secrets, Spotify OAuth, Gitea tokens, etc.).
+
+### `gitea/config/app.ini`
+
+Gitea application config. Copy from the template and fill in secrets:
+
+```sh
+cp gitea/config/app.ini.template gitea/config/app.ini
+```
+
+Populate `LFS_JWT_SECRET`, `SECRET_KEY`, `INTERNAL_TOKEN`, `JWT_SECRET`, and the database `PASSWD`.
+
+### `searxng/settings.yml`
+
+SearXNG settings. Copy from the template:
+
+```sh
+cp searxng/settings.yml.template searxng/settings.yml
+```
+
+The template uses environment variable substitution (`${BASE_URL}`, `${SEARXNG_SECRET_KEY}`) at container build time, so this file is generated by the Dockerfile's `entrypoint.sh`. If running outside Docker, fill in values manually.
+
+### `certbot/conf/` and `certbot/www/`
+
+Let's Encrypt certificate storage. In production, certbot populates these automatically on first run. For local/dev use, either:
+
+- Use dev mode (`docker-compose.dev.yml`) which skips SSL, or
+- Place self-signed certs in `certbot/conf/live/localhost/` (`fullchain.pem`, `privkey.pem`).
+
+### `backend/token/`
+
+Directory where the backend persists Spotify OAuth tokens (`spotify_token.json`). Created automatically at runtime — no manual setup needed, but the directory is git-ignored so it won't exist on a fresh clone. Docker mounts `./backend/token/:/backend/token` so the directory is created by Docker.
+
+### `icecast2/fallback_music/`
+
+MP3 files used as fallback music for the Icecast2/Liquidsoap radio stream. Place at least one `.mp3` file here. A `.gitkeep` is tracked to preserve the directory.
+
+### `gitea-runner/act_runner`
+
+The Gitea Actions runner binary. Download from [Gitea's releases](https://gitea.com/gitea/act_runner/releases) for your platform and place in `gitea-runner/`.
+
+### `gitea-runner/.runner`
+
+Runner registration state file. Generated automatically when `gitea-runner/run.sh` runs for the first time (requires `GITEA_RUNNER_REGISTRATION_TOKEN` in `.env`).