diff --git a/README.md b/README.md
index 9067b01..f333eb2 100644
--- a/README.md
+++ b/README.md
@@ -127,8 +127,11 @@ CONTEXT_KIT_DOCS_SOURCES="config/sources.default.txt config/sources.js.txt" \
 
 The docs service reads its source list once, at startup. After changing
 sources, run `restart`; `start` writes the new list but leaves a running docs
-service on the old one, and says so. `bin/context-kit docs` is only a stdio
-bridge to the already-running docs service.
+service on the old one, and says so. Then index any new source with
+`bin/context-kit docs-rebuild SOURCE_URL`, so the first query does not have to.
+See [Source Profiles](docs/configuration.md#source-profiles).
+`bin/context-kit docs` is only a stdio bridge to the already-running docs
+service.
 
 `docs_query` searches with FTS5 plus embeddings, deduplicates exact content,
 and supports source/host filters. It returns snippets but does not retrieve full
diff --git a/docs/configuration.md b/docs/configuration.md
index 8da6617..1ca87b0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -165,9 +165,20 @@ The docs MCP accepts one or more source profile files:
 CONTEXT_KIT_DOCS_SOURCES="config/sources.default.txt config/sources.js.txt"
 ```
 
-Source changes are loaded when the docs service starts. Run `bin/context-kit
-restart` after changing `CONTEXT_KIT_DOCS_SOURCES`; `bin/context-kit docs` only
-bridges stdio clients to the already-running service.
+The docs service reads its source list once, when its container starts. Run
+`bin/context-kit restart` after changing `CONTEXT_KIT_DOCS_SOURCES` or editing
+any profile file it names. `start` regenerates the list too, but it never
+restarts a running container, so it leaves a running docs service on the old
+list and warns that a restart is needed. `bin/context-kit docs` only bridges
+stdio clients to the already-running service.
+
+`restart` restarts all three shared services, so every connected assistant
+loses web search and docs until they are ready again.
+
+A restart does not index a newly added source. Index it before anyone queries
+it, with `bin/context-kit docs-rebuild SOURCE_URL` or the `docs_refresh` tool;
+otherwise the first `docs_query` after the restart does that work inline, and a
+large feed can take several minutes on CPU, longer than many clients wait.
 
 `CONTEXT_KIT_DOCS_SOURCES` may include absolute paths to private machine-local
 profile files. Each profile file is plain text; blank lines and `#` comments are
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 9e76481..108a0f4 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -175,6 +175,22 @@ Cloudflare and other large docs sets can take significantly longer than the
 default source profile. Set `CONTEXT_KIT_DOCS_PREINDEX=1` only if you want
 startup to eagerly embed every configured source.
 
+## A New Docs Source Does Not Appear
+
+If `docs_sources` does not list a source you added, or `docs-rebuild` fails with
+`unconfigured sources`, the running docs service is still on its old source
+list. It reads the list only at startup, and `start` does not restart a running
+container; it warns instead. Restart, then index the new source:
+
+```sh
+bin/context-kit restart
+bin/context-kit docs-rebuild https://example.com/llms-full.txt
+```
+
+Edit the profile files named by `CONTEXT_KIT_DOCS_SOURCES`, not the generated
+`docs-sources.txt` under the data directory; every lifecycle command overwrites
+that file.
+
 ## Docs Sources Report Refresh Errors
 
 If `docs_sources` reports `last_error`, the service keeps the previous generation