docs: add .env.example and service configuration guide

.env.example

@@ -0,0 +1,34 @@
+# Copy to .env for `docker compose` (docker compose auto-loads .env from the
+# repo root). Everything here is optional — the core service works with no
+# configuration at all.
+
+# ---------------------------------------------------------------------------
+# Core HTTP service (used by wr-core)
+# ---------------------------------------------------------------------------
+# Optional bearer token for the HTTP API. When set, every request must send
+# `Authorization: Bearer <key>`.
+WATERMARKS_SERVER_API_KEY=
+
+# ---------------------------------------------------------------------------
+# Harness / heavy backends (only used by the harness/heavy profiles)
+# ---------------------------------------------------------------------------
+# Optional Hugging Face token for gated models (CtrlRegen, MarkLLM,
+# MarkDiffusion score models). Env only — never on argv.
+HF_TOKEN=
+
+# ---------------------------------------------------------------------------
+# Client-side (used by the skill or curl, NOT by compose)
+# ---------------------------------------------------------------------------
+# Where to reach the service. Defaults to http://127.0.0.1:8765.
+# WATERMARKS_SERVICE_URL=http://127.0.0.1:8765
+
+# ---------------------------------------------------------------------------
+# Layer B statistical-watermark rewrite (only for the rewrite_text.py hook,
+# which runs inside the core image or a local checkout; the agent skill does
+# Layer B itself with its own model and does not need these)
+# ---------------------------------------------------------------------------
+# WATERMARKS_REWRITE_BACKEND=ollama        # or: openai
+# WATERMARKS_REWRITE_MODEL=llama3.2
+# WATERMARKS_REWRITE_BASE_URL=http://127.0.0.1:11434
+# WATERMARKS_REWRITE_API_KEY=              # env only, never on argv
+# WATERMARKS_REWRITE_ALLOW_REMOTE=1        # only for non-loopback endpoints

README.md

@@ -176,6 +176,25 @@ make compose-check        # or: ./compose-check.sh
 
 Checks `wr-core` via `GET /health` and runs each harness/heavy service with `--help`, requiring exit `0`.
 
+### Configuration
+
+**Nothing is required to clean arbitrary text** — the core service works out of the box:
+
+```bash
+echo "Hello\u200bWorld\u00ad!" > /tmp/sample.txt
+curl -s -X POST http://127.0.0.1:8765/clean -H 'Content-Type: application/json' \
+  -d "{\"file\": \"$(base64 -w0 /tmp/sample.txt)\", \"name\": \"sample.txt\"}"
+```
+
+Optional configuration goes in `.env` (auto-loaded by compose; template: [`.env.example`](.env.example)):
+
+| Var | Applies to | Purpose |
+| --- | --- | --- |
+| `WATERMARKS_SERVER_API_KEY` | `wr-core` | Require `Authorization: Bearer <key>` on the HTTP API |
+| `HF_TOKEN` | harness/heavy | Hugging Face token for gated models |
+| `WATERMARKS_SERVICE_URL` | client (skill/curl) | Default `http://127.0.0.1:8765` |
+| `WATERMARKS_REWRITE_BACKEND` / `_MODEL` / `_BASE_URL` / `_API_KEY` | `rewrite_text.py` hook | Layer B rewrite via a local Ollama/OpenAI endpoint (the skill does Layer B itself and doesn't need these) |
+
 Images publish automatically on `v*` tags via [`.github/workflows/release-images.yml`](.github/workflows/release-images.yml).
 
 ## Optional SynthID pixel scoring