diff --git a/docs/a2a.md b/docs/a2a.md
index 690a0fcc..7b7ff338 100644
--- a/docs/a2a.md
+++ b/docs/a2a.md
@@ -144,12 +144,13 @@ All operations create artifacts for traceability:
 
 To prevent memory growth, the server uses LRU (Least Recently Used) eviction:
 
-- Maximum 1000 contexts kept in memory (configurable via `A2A_MAX_CONTEXTS`)
+- Maximum 1000 contexts kept in memory (configurable via `a2a.max_contexts`)
 - When limit exceeded, least recently used contexts are automatically evicted
 
-Configure via environment variable:
-```bash
-export A2A_MAX_CONTEXTS=1000
+Configure in `haiku.rag.yaml`:
+```yaml
+a2a:
+  max_contexts: 1000
 ```
 
 ## Security
diff --git a/docs/installation.md b/docs/installation.md
index bdaa43db..acd43c7b 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -47,26 +47,31 @@ vllm serve Qwen/Qwen3-4B --port 8002 --enable-auto-tool-choice --tool-call-parse
 vllm serve mixedbread-ai/mxbai-rerank-base-v2 --hf_overrides '{"architectures": ["Qwen2ForSequenceClassification"],"classifier_from_token": ["0", "1"], "method": "from_2_way_softmax"}' --port 8001
 ```
 
-Then configure haiku.rag to use the vLLM servers:
+Then configure haiku.rag to use the vLLM servers. Create a `haiku.rag.yaml` file:
 
-```bash
-# Embeddings
-EMBEDDINGS_PROVIDER="vllm"
-EMBEDDINGS_MODEL="mixedbread-ai/mxbai-embed-large-v1"
-EMBEDDINGS_VECTOR_DIM=512
-VLLM_EMBEDDINGS_BASE_URL="http://localhost:8000"
+```yaml
+embeddings:
+  provider: vllm
+  model: mixedbread-ai/mxbai-embed-large-v1
+  vector_dim: 512
 
-# QA (optional)
-QA_PROVIDER="vllm"
-QA_MODEL="Qwen/Qwen3-4B"
-VLLM_QA_BASE_URL="http://localhost:8002"
+qa:
+  provider: vllm
+  model: Qwen/Qwen3-4B
 
-# Reranking (optional)
-RERANK_PROVIDER="vllm"
-RERANK_MODEL="mixedbread-ai/mxbai-rerank-base-v2"
-VLLM_RERANK_BASE_URL="http://localhost:8001"
+reranking:
+  provider: vllm
+  model: mixedbread-ai/mxbai-rerank-base-v2
+
+providers:
+  vllm:
+    embeddings_base_url: http://localhost:8000
+    qa_base_url: http://localhost:8002
+    rerank_base_url: http://localhost:8001
 ```
 
+See [Configuration](configuration.md) for all available options.
+
 ## Requirements
 
 - Python 3.12+
diff --git a/docs/python.md b/docs/python.md
index 517599d0..bd01c260 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -189,7 +189,7 @@ for chunk, score in expanded_results:
 
 **Smart Merging**: When expanded chunks overlap or are adjacent within the same document, they are automatically merged into single chunks with continuous content. This eliminates duplication and provides coherent text blocks. The merged chunk uses the highest relevance score from the original chunks.
 
-This is automatically used by the QA system when `CONTEXT_CHUNK_RADIUS > 0` to provide better answers with more complete context.
+This is automatically used by the QA system when `processing.context_chunk_radius > 0` (configured in `haiku.rag.yaml`) to provide better answers with more complete context.
 
 ## Question Answering
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
index a9892aca..2dba754c 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -31,34 +31,28 @@ Install `haiku.rag` Python package using [uv](https://docs.astral.sh/uv/getting-
 uv pip install haiku.rag
 ```
 
-Configure your OpenAI API key and embeddings model.
+Configure haiku.rag to use OpenAI. Create a `haiku.rag.yaml` file:
 
-- Haiku RAG supports [dotenv](https://pypi.org/project/python-dotenv/) environment files and environment varibles for configuration
-- [See OpenAPI vector embeddings documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models)
+```yaml
+embeddings:
+  provider: openai
+  model: text-embedding-3-small  # or text-embedding-3-large
+  vector_dim: 1536
 
-Create a file called `.env` and add:
-
-```shell
-#
-# These settings are relevant for converting documents to embeddings
-#
-
-EMBEDDINGS_PROVIDER="openai"
-# or text-embedding-3-large
-EMBEDDINGS_MODEL="text-embedding-3-small"
-EMBEDDINGS_VECTOR_DIM=1536
-OPENAI_API_KEY="<your OpenAPI API key goes here>"
-
-#
-# These settings are relevant for question answering chats
-#
-
-# We tell Haiku.rag to use OpenAI remote AI for chats, instead of local ollama.
-QA_PROVIDER="openai"
-QA_MODEL="gpt-4o-mini"  # or gpt-4, gpt-3.5-turbo, etc.
+qa:
+  provider: openai
+  model: gpt-4o-mini  # or gpt-4o, gpt-4, etc.
 ```
 
-For the list of available OpenAI embedding models and `EMBEDDINGS_VECTOR_DIM` options, ask ChatGPT for instructions.
+Set your OpenAI API key as an environment variable (API keys should not be stored in the YAML file):
+
+```bash
+export OPENAI_API_KEY="<your OpenAI API key>"
+```
+
+For the list of available OpenAI models and their vector dimensions, see the [OpenAI documentation](https://platform.openai.com/docs/guides/embeddings).
+
+See [Configuration](configuration.md) for all available options.
 
 ## Adding the first documents