Document how a new docs source is loaded and indexed

The configuration guide covered a changed CONTEXT_KIT_DOCS_SOURCES but not
an edited profile, said nothing of start's warning or of restart taking
every shared service down, and left new sources to be embedded inside the
first query. Troubleshooting had no entry for a source that never appears.

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
+service on the old one, and says so. Then index any new source with
-bridge to the already-running docs service.
+`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

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
+The docs service reads its source list once, when its container starts. Run
-restart` after changing `CONTEXT_KIT_DOCS_SOURCES`; `bin/context-kit docs` only
+`bin/context-kit restart` after changing `CONTEXT_KIT_DOCS_SOURCES` or editing
-bridges stdio clients to the already-running service.
+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

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