diff --git a/.env.langfuse.example b/.env.langfuse.example
new file mode 100644
index 0000000..dfe59e8
--- /dev/null
+++ b/.env.langfuse.example
@@ -0,0 +1,77 @@
+# Langfuse local development environment.
+#
+# Usage:
+#   cp .env.langfuse.example .env.langfuse
+#   # replace all CHANGE_ME values before starting
+#   docker compose --env-file .env.langfuse -f docker-compose.langfuse.yml up -d
+#
+# Generate secrets with commands such as:
+#   openssl rand -base64 32
+#   openssl rand -hex 16
+#   openssl rand -hex 32
+#
+# Do not commit .env.langfuse.
+
+# Public URL used by Langfuse itself. For local browser access this should match
+# http://localhost:3000. For a VM, set this to your HTTPS domain.
+LANGFUSE_NEXTAUTH_URL=http://localhost:3000
+
+# Host ports. Internal container ports stay unchanged and are used for
+# container-to-container communication.
+LANGFUSE_WEB_PORT=3000
+LANGFUSE_WORKER_PORT=3030
+LANGFUSE_POSTGRES_HOST_PORT=15432
+LANGFUSE_REDIS_HOST_PORT=16379
+LANGFUSE_CLICKHOUSE_HTTP_PORT=18123
+LANGFUSE_CLICKHOUSE_NATIVE_PORT=19000
+LANGFUSE_MINIO_API_PORT=9090
+LANGFUSE_MINIO_CONSOLE_PORT=9091
+
+# Core Langfuse secrets. Replace these values.
+LANGFUSE_NEXTAUTH_SECRET=CHANGE_ME_generate_with_openssl_rand_base64_32
+LANGFUSE_SALT=CHANGE_ME_generate_with_openssl_rand_hex_16
+# Must be exactly 64 hex characters. Generate with: openssl rand -hex 32
+LANGFUSE_ENCRYPTION_KEY=CHANGE_ME_generate_with_openssl_rand_hex_32
+
+# Langfuse internal Postgres. This is not the chatbot application's Postgres.
+LANGFUSE_POSTGRES_VERSION=17
+LANGFUSE_POSTGRES_USER=postgres
+LANGFUSE_POSTGRES_PASSWORD=CHANGE_ME_langfuse_postgres_password
+LANGFUSE_POSTGRES_DB=postgres
+
+# Langfuse internal ClickHouse.
+LANGFUSE_CLICKHOUSE_USER=clickhouse
+LANGFUSE_CLICKHOUSE_PASSWORD=CHANGE_ME_langfuse_clickhouse_password
+LANGFUSE_CLICKHOUSE_CLUSTER_ENABLED=false
+
+# Langfuse internal Redis.
+LANGFUSE_REDIS_PORT=6379
+LANGFUSE_REDIS_AUTH=CHANGE_ME_langfuse_redis_password
+
+# Langfuse local MinIO/object storage.
+LANGFUSE_MINIO_ROOT_USER=minio
+LANGFUSE_MINIO_ROOT_PASSWORD=CHANGE_ME_langfuse_minio_password
+LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=minio
+LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=CHANGE_ME_langfuse_minio_password
+LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID=minio
+LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=CHANGE_ME_langfuse_minio_password
+LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT_PUBLIC=http://localhost:9090
+LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID=minio
+LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY=CHANGE_ME_langfuse_minio_password
+LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT=http://localhost:9090
+
+# Development defaults.
+LANGFUSE_TELEMETRY_ENABLED=false
+LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
+
+# Optional headless initialization. Leave blank to create the organization,
+# project, user, and API keys in the UI after startup.
+LANGFUSE_INIT_ORG_ID=
+LANGFUSE_INIT_ORG_NAME=
+LANGFUSE_INIT_PROJECT_ID=
+LANGFUSE_INIT_PROJECT_NAME=
+LANGFUSE_INIT_PROJECT_PUBLIC_KEY=
+LANGFUSE_INIT_PROJECT_SECRET_KEY=
+LANGFUSE_INIT_USER_EMAIL=
+LANGFUSE_INIT_USER_NAME=
+LANGFUSE_INIT_USER_PASSWORD=
diff --git a/README.md b/README.md
index e69de29..f1ee9d9 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,51 @@
+# Talie chatbot service
+
+Architecture decisions live in [`docs/adr`](docs/adr). The first implementation
+milestone is documented in the [ingestion vertical-slice plan](docs/plans/001-ingestion-vertical-slice.md).
+
+## Local Langfuse
+
+This repo includes a root-level development Compose file for Langfuse:
+
+- [`docker-compose.langfuse.yml`](docker-compose.langfuse.yml)
+- [`.env.langfuse.example`](.env.langfuse.example)
+
+Start Langfuse locally:
+
+```bash
+cp .env.langfuse.example .env.langfuse
+# edit .env.langfuse and replace CHANGE_ME values
+
+docker compose --env-file .env.langfuse -f docker-compose.langfuse.yml up -d
+```
+
+Open:
+
+```text
+http://localhost:3000
+```
+
+If the chatbot app runs on your host machine, configure it with:
+
+```env
+LANGFUSE_HOST=http://localhost:3000
+```
+
+If the chatbot app later runs inside the same Compose project/network as
+Langfuse, configure it with:
+
+```env
+LANGFUSE_HOST=http://langfuse-web:3000
+```
+
+A future app stack can be launched together with Langfuse using multiple Compose
+files:
+
+```bash
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.langfuse.yml \
+  --env-file .env \
+  --env-file .env.langfuse \
+  up -d
+```