From 7deca612bb744accdc1c76fa4e6091fa0f766b55 Mon Sep 17 00:00:00 2001 From: Ajay Krishnan Date: Thu, 1 Oct 2026 13:08:22 -0700 Subject: [PATCH] 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 | 7 +++++-- docs/configuration.md | 17 ++++++++++++++--- docs/troubleshooting.md | 16 ++++++++++++++++ 3 files changed, 35 insertions(+), 5 deletions(-) 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