Simplify runtime checks and MCP smokes

docs/assistants.md

@@ -1,7 +1,14 @@
 # Assistant Setup
 
-Context Kit supports any assistant that can run local stdio MCP servers. The
-included snippets cover Claude Code and OpenCode.
+Context Kit supports assistants that can run local stdio MCP servers, HTTP MCP
+servers, or both. The default transport split is simple:
+
+- `context-web-search`: local stdio command.
+- `context-docs`: local HTTP MCP service.
+- `context-repomix`: local stdio command.
+
+`bin/context-kit docs` is a stdio fallback for clients that cannot use HTTP MCP.
+The included snippets cover Claude Code and OpenCode.
 
 ## Claude Code
 

docs/configuration.md

@@ -7,7 +7,10 @@ Explicit environment variables win over `.env` values. The `.env` parser accepts
 simple `KEY=VALUE` lines for `CONTEXT_KIT_*` variables only; it does not execute
 shell code.
 
-## Core Variables
+## User-Facing Variables
+
+Only the variables below are part of the public configuration surface. Other
+`CONTEXT_KIT_*` variables used by scripts are release/test hooks and may change.
 
 | Variable | Default | Purpose |
 |---|---|---|
@@ -68,14 +71,21 @@ Avoid `*`; the docs MCP is a local unauthenticated endpoint.
 
 ## Source Profiles
 
-The docs MCP accepts one or more source files:
+The docs MCP accepts one or more source profile files:
 
 ```sh
 CONTEXT_KIT_DOCS_SOURCES="config/sources.default.txt config/sources.js.txt"
 ```
 
-Each source file is plain text. Blank lines and `#` comments are ignored.
-Entries may be absolute source-profile paths for private machine-local config.
+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.
+
+`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
+ignored. Entries inside profile files must be URLs ending in `/llms.txt` or
+`/llms-full.txt`.
+
 For local llms.txt files, place content under
 `CONTEXT_KIT_DOCS_LOCAL_SOURCES_DIR` and reference it as
 `http://127.0.0.1:8769/path/inside/local-sources/llms.txt` or another URL that

docs/security.md

@@ -6,6 +6,7 @@ Context Kit is designed to be safe by default for local development.
 
 - SearXNG is bound to `127.0.0.1` only.
 - No hosted API keys are required.
+- The web-search MCP image runs as the non-root `node` user.
 - Repomix mounts only the current project read-only.
 - Docs indexing stores data under `$HOME/.local/share/context-kit` unless you
   override it.

docs/troubleshooting.md

@@ -6,8 +6,21 @@
 bin/context-kit doctor
 ```
 
-This checks Docker, Compose, images, the Docker network, SearXNG health, and
-docs source configuration.
+This checks Docker, Compose, images, the Docker network, SearXNG health, docs
+HTTP readiness, and docs source configuration.
+
+For release-grade MCP protocol checks, run:
+
+```sh
+scripts/release-check
+```
+
+Live provider checks are opt-in because search engines, remote docs, and model
+downloads can fail independently of this repo:
+
+```sh
+CONTEXT_KIT_LIVE_CHECKS=1 scripts/release-check
+```
 
 ## SearXNG Is Not Responding
 
@@ -66,11 +79,13 @@ URL fetching uses the HTTP extractor path.
 
 ## Docs Indexing Is Slow
 
-The first run downloads an embedding model and embeds every configured docs
-section. Keep default sources small, and add profiles only when you need them.
+The first `docs_query` or `docs_refresh` downloads an embedding model and
+embeds the requested docs sections lazily. Keep default sources small, and add
+profiles only when you need them.
 
 Cloudflare and other large docs sets can take significantly longer than the
-default source profile.
+default source profile. Set `CONTEXT_KIT_DOCS_PREINDEX=1` only if you want
+startup to eagerly embed every configured source.
 
 ## Docs Tools Say Index Manager Not Initialized
 
@@ -79,7 +94,7 @@ If `docs_query` or `docs_refresh` returns `Index manager not initialized` while
 initialize its embedding model or Chroma database. Check the container logs:
 
 ```sh
-docker logs context-kit-docs-mcp
+docker compose -p "${CONTEXT_KIT_COMPOSE_PROJECT:-context-kit}" -f compose.yml logs docs-mcp
 ```
 
 A common cause is Docker creating the bind-mounted cache directories as `root`
@@ -93,7 +108,7 @@ unable to open database file
 Fix ownership and restart:
 
 ```sh
-DATA_DIR="${CONTEXT_KIT_DATA_DIR:-$HOME/.local/share/context-kit}"
+DATA_DIR="${CONTEXT_KIT_DATA_DIR:-${HOME:?Set HOME or CONTEXT_KIT_DATA_DIR}/.local/share/context-kit}"
 sudo chown -R "$(id -u):$(id -g)" "$DATA_DIR/docs" "$DATA_DIR/models"
 bin/context-kit restart
 ```