Document local runtime state

.env.example

@@ -41,10 +41,12 @@ CONTEXT_KIT_DOCS_EMBED_MODEL=BAAI/bge-small-en-v1.5
 # fast; call the docs_refresh MCP tool when you want to populate the index.
 # CONTEXT_KIT_DOCS_PREINDEX=1
 
-# One or more source files, separated by spaces.
+# One or more source files, separated by spaces. Keep committed profiles generic.
+# Add private absolute-path profiles only in your ignored local .env.
 CONTEXT_KIT_DOCS_SOURCES=config/sources.default.txt
 
 # Optional machine-local llms.txt tree. Files are served only inside docs-mcp at
 # http://127.0.0.1:8769/ so absolute local paths do not leak into source files.
+# Keep private menus here or in another local path, not under config/.
 # CONTEXT_KIT_DOCS_LOCAL_SOURCES_DIR=/path/to/context-kit-local-sources
 # CONTEXT_KIT_DOCS_LOCAL_SOURCES_PORT=8769

README.md

@@ -66,6 +66,28 @@ config that will not be committed.
 - Repomix mounts only the current project read-only.
 - No code-editing MCP server is enabled by default.
 
+## Public Repo vs Local Runtime State
+
+This repository is the public, portable Context Kit distribution. It should only
+contain generic defaults, Docker/service code, install snippets, and optional
+public docs source profiles.
+
+Machine-specific configuration stays out of git:
+
+- `.env` is ignored. Use it for local ports, data paths, and private source
+  profile paths.
+- `CONTEXT_KIT_DATA_DIR` stores runtime state: docs indexes, model caches, the
+  generated `docs-sources.txt`, and any local source tree you choose to keep
+  there.
+- Private docs source profiles can live anywhere outside the repo and can be
+  referenced from `.env` with an absolute path.
+- Private `llms.txt` menus belong under `CONTEXT_KIT_DOCS_LOCAL_SOURCES_DIR`, not
+  under `config/`.
+
+The public default is intentionally small: `config/sources.default.txt`. If a
+machine adds extra local menus, they affect only that machine's running
+`context-docs` service.
+
 ## Docs Sources
 
 The default docs index is intentionally small:

docs/configuration.md

@@ -7,6 +7,47 @@ 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.
 
+## Public Files vs Local State
+
+Context Kit is meant to be a public repo plus private local runtime state.
+
+Tracked public files:
+
+- `config/sources.default.txt`: small default docs index.
+- `config/sources.*.txt`: optional public source profiles.
+- `snippets/`: portable assistant config snippets that use `context-kit` on
+  `PATH`.
+- `compose.yml`, `docker/`, `bin/`, and `scripts/`: generic runtime and release
+  logic.
+
+Ignored or external local files:
+
+- `.env`: local overrides; never commit it.
+- `CONTEXT_KIT_DATA_DIR`: docs indexes, model caches, generated
+  `docs-sources.txt`, and local source trees.
+- Private source profile files referenced by absolute path from `.env`.
+- Private `llms.txt` menus under `CONTEXT_KIT_DOCS_LOCAL_SOURCES_DIR`.
+
+Do not put personal project menus, private repo names, or local filesystem paths
+in `config/`. Put them in a private source profile outside the repo, then add
+that profile to `.env`:
+
+```sh
+CONTEXT_KIT_DOCS_SOURCES="config/sources.default.txt /path/to/private-sources.txt"
+CONTEXT_KIT_DOCS_LOCAL_SOURCES_DIR=/path/to/local-sources
+```
+
+Entries in the private profile should still be URLs, not filesystem paths. For a
+local menu stored at `/path/to/local-sources/my-project/llms.txt`, reference it
+as:
+
+```text
+http://127.0.0.1:8769/my-project/llms.txt
+```
+
+That loopback URL is inside the `docs-mcp` container. It is not exposed on the
+host.
+
 ## User-Facing Variables
 
 Only the variables below are part of the public configuration surface. Other