diff --git a/docs/dev/creating-a-service.md b/docs/dev/creating-a-service.md
index 2d5181f6..f1e9196f 100644
--- a/docs/dev/creating-a-service.md
+++ b/docs/dev/creating-a-service.md
@@ -137,7 +137,7 @@ will use throughout the service:
 
 | Attribute | What it is |
 |---|---|
-| `self.config` | This service's `config.yaml` contents (a dict), or `None` if absent. |
+| `self.config` | A dict: this service's `config.yaml`, with the user's `services.<TAG>` block from `unshackle.yaml` merged over it. Without a `config.yaml`, it holds only the user's block. See [Services & authentication](../reference/configuration/services.md) for the override keys. |
 | `self.log` | A `logging.Logger` named after your class. |
 | `self.session` | A prepared `requests.Session` with config headers and a retry adapter (5 retries, backoff 0.2, retries on 429/500/502/503/504). Send every request through it: with a proxy active, a request from service code that does not go through the proxy logs a warning. A separate HTTP session that goes direct on purpose sets `proxy_exempt = True`. |
 | `self.cache` | A `Cacher` for arbitrary key/value data, for example authentication tokens. |
diff --git a/docs/dev/service-architecture.md b/docs/dev/service-architecture.md
index 7083a124..5eef937e 100644
--- a/docs/dev/service-architecture.md
+++ b/docs/dev/service-architecture.md
@@ -112,7 +112,7 @@ up the objects your methods rely on:
 
 | Attribute | What it is |
 |---|---|
-| `self.config` | The per-service config slice (see [Request and HTTP session objects](#request-and-http-session-objects)). |
+| `self.config` | The merged service config (see [Request and HTTP session objects](#request-and-http-session-objects)). |
 | `self.log` | A `logging.Logger` named after your class. |
 | `self.session` | A ready-to-use HTTP session (headers, retries, and proxy applied). Send every request through it: with a proxy active, a request from service code that does not go through the proxy logs a warning. A separate HTTP session that goes direct on purpose sets `proxy_exempt = True`. |
 | `self.cache` | A generic key/value `Cacher` namespaced to the service. |
@@ -471,10 +471,11 @@ the container file.
 Everything a service does over the network flows through objects the base constructor
 prepared, all derived from the Click context (`ctx`) that `dl` passes in.
 
-- **`self.config`**: your service's slice of `unshackle.yaml`, i.e.
-  `config.services[<ServiceName>]`. This is a plain dict. Use it for per-service settings
-  like base URLs, an API key, or a `title_map`. See
-  [Configuration](../getting-started/configuration-file.md).
+- **`self.config`**: a plain dict. unshackle loads the service's own `config.yaml`, then merges
+  the user's `services.<TAG>` block from `unshackle.yaml` over it. Nested keys merge one by one,
+  the user's value wins, and a list in the user's block replaces the whole list. Use it for
+  per-service settings like base URLs, an API key, or a `title_map`. See
+  [Services & authentication](../reference/configuration/services.md) for the override keys.
 - **`self.session`**: a `requests.Session` with `config.headers` applied, a retry policy
   (`total=5`, backoff, retry on 429/5xx), and any resolved proxy already mounted. Pass this
   HTTP session into the manifest parsers and DRM calls so headers, cookies, and proxies flow