diff --git a/README.md b/README.md
index f3933eb..7d6195d 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,8 @@ cp .env.example .env
 uv run main.py
 ```
 
+命令行支持 `-h` / `--help`（查看用法）与 `--smoke-test`（非交互自检）；提示符与选择菜单指针的颜色自动适配终端亮色 / 暗色主题（面板、表格等其他元素沿用 rich 语义色），可用 `PYRAG_LIGHT=1` / `PYRAG_DARK=1` 强制指定。
+
 3. 在主菜单中按需执行：
    - `1`：重建知识快照
    - `2`：执行召回测试
diff --git a/docs/user_guide/getting-started.md b/docs/user_guide/getting-started.md
index 67a118d..892ce54 100644
--- a/docs/user_guide/getting-started.md
+++ b/docs/user_guide/getting-started.md
@@ -75,6 +75,14 @@ uv sync
 uv run main.py
 ```
 
+命令行参数：
+
+*   `-h` / `--help`：打印用法说明并退出（不初始化依赖，瞬时返回，也无任何副作用）。
+*   `--smoke-test`：非交互式启动自检，主要用于构建验证。
+*   无参数：进入交互式主菜单。
+
+提示符与选择菜单指针的颜色会自动适配终端的亮色 / 暗色主题（面板、表格等其他元素沿用 rich 语义色）。主题通过 `COLORFGBG` 环境变量检测，无信号时按暗色处理；如检测不符，可用环境变量强制指定：`PYRAG_LIGHT=1`（亮色）或 `PYRAG_DARK=1`（暗色）。
+
 程序启动后会进入主菜单，您可以按需执行：
 
 *   **1. 知识库文档向量化处理**: 处理 `knowledge_base/` 目录中的 Markdown 文件，并生成新的本地知识快照。
diff --git a/docs/user_guide/user-guide.md b/docs/user_guide/user-guide.md
index c08294f..d142c8b 100644
--- a/docs/user_guide/user-guide.md
+++ b/docs/user_guide/user-guide.md
@@ -6,6 +6,8 @@
 
 当您按照 [快速上手](./getting-started.md) 指南成功运行 `uv run main.py` 后，程序会进入主菜单。
 
+命令行支持 `-h` / `--help`（查看用法）与 `--smoke-test`（非交互自检）；提示符与选择菜单指针的颜色自动适配终端亮色 / 暗色主题（面板、表格等其他元素沿用 rich 语义色），检测不符时可用 `PYRAG_LIGHT=1` 或 `PYRAG_DARK=1` 强制指定。
+
 您会看到类似以下的选项：
 
 ```
@@ -59,7 +61,7 @@ uv run python -m scripts.embed_knowledge_base --mode standard
     *   **Rerank重排**: 启用或禁用 Rerank 模型进行二次精排。
     *   **混合搜索权重**: 当使用“混合检索”时，调整向量和关键词搜索结果的权重。
 *   **切换模型**:
-    *   **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（例如，从 `google` 切换到 `openai`）。切换后，程序会自动重载模型。
+    *   **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（在 `config.toml` 中 `llm_configurations` 里定义的配置项之间切换，例如从 `openai` 切到 `google-pro`）。切换后，程序会自动重载模型；重载失败时自动回滚到原模型并提示。
     *   **重排模型 (Rerank)**: 切换用于精排的 Rerank 模型。
 *   **查看当前完整配置**: 显示所有当前生效的聊天和模型参数。