diff --git a/content/cn/docs/quickstart/hugegraph-ai/_index.md b/content/cn/docs/quickstart/hugegraph-ai/_index.md
index 5b9d07820..2b1226622 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/_index.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/_index.md
@@ -15,14 +15,31 @@ weight: 3
 - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client)：管理 Schema、图数据和 Gremlin 查询的 Python SDK。
 - [vermeer-python-client](https://github.com/apache/hugegraph-ai/tree/main/vermeer-python-client)：调用 Vermeer 图计算服务的 Python SDK。
 
-仓库使用 `uv` workspace 管理 LLM 和 Python 客户端。HugeGraph-ML 是路径依赖模块，不在 workspace members 中。
+仓库使用 `uv` workspace，其成员是 `hugegraph-llm` 和 `hugegraph-python-client`。`hugegraph-ml` 和 `vermeer-python-client` 是可编辑的路径依赖，不在 workspace members 中。当前仓库版本为 `1.7.0`。
 
 ## 环境要求
 
-- HugeGraph-LLM：Python 3.10 或 3.11
-- HugeGraph-ML、Python 客户端：Python 3.10 或更高版本
+- HugeGraph-LLM：Python 3.10 或 3.11（`>=3.10,<3.12`）
+- HugeGraph-ML：Python 3.10 或更高版本
+- HugeGraph Python 客户端、Vermeer Python 客户端：Python 3.9 或更高版本
 - `uv` 0.7 或更高版本
-- HugeGraph Server 1.5 或更高版本
+- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
+
+## 可选依赖组
+
+根项目为每个模块声明一个 extra，另有几个组合项：
+
+| Extra | 安装内容 |
+|---|---|
+| `llm` | `hugegraph-llm` |
+| `ml` | `hugegraph-ml` |
+| `python-client` | `hugegraph-python-client` |
+| `vermeer` | `vermeer-python-client` |
+| `dev` | pytest、pytest-cov、coverage、pylint、ruff、mypy、ty、pre-commit |
+| `nk-llm` | `hugegraph-llm`、`hugegraph-python-client`，以及编译镜像所需的 Nuitka |
+| `all` | 四个模块包 |
+
+`hugegraph-llm` 自身还声明了 `vectordb` extra，用于安装 `pymilvus` 和 `qdrant-client`。
 
 ## Docker Compose 部署
 
@@ -70,6 +87,7 @@ cd hugegraph-ml/src
 ## 后续阅读
 
 - [HugeGraph-LLM](./hugegraph-llm.md)
+- [HugeGraph-LLM 使用流程](./quick_start.md)
 - [配置参考](./config-reference.md)
 - [REST API](./rest-api.md)
 - [HugeGraph-ML](./hugegraph-ml.md)
diff --git a/content/cn/docs/quickstart/hugegraph-ai/config-reference.md b/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
index ffd67e64a..17a43d646 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
@@ -6,6 +6,12 @@ weight: 4
 
 HugeGraph-LLM 从 `hugegraph-llm/.env` 读取运行配置。提示词单独保存在 `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`，不会写入 `.env`。
 
+`.env` 路径按以下顺序解析：
+
+1. 若设置了环境变量 `HUGEGRAPH_LLM_ENV_PATH`，则使用该路径，开头的 `~` 会被展开。
+2. 从源码运行时，使用 `hugegraph-llm/.env`。
+3. 以已安装的包运行时，使用当前工作目录下的 `.env`。
+
 运行以下命令可按配置类的默认值创建或更新文件：
 
 ```bash
@@ -13,6 +19,8 @@ cd hugegraph-ai/hugegraph-llm
 python -m hugegraph_llm.config.generate --update
 ```
 
+`--update` 默认开启，因此不带参数运行效果相同。该命令会写入 HugeGraph、管理员、LLM 和索引配置，然后重新生成提示词 YAML。若 `.env` 已存在，会先询问是否覆盖。
+
 `.env` 包含密钥和密码，不要提交到版本库。
 
 ## 基础选项
@@ -91,27 +99,28 @@ API 地址默认是 `https://api.openai.com/v1`；三个语言模型默认是 `g
 | `TOPK_PER_KEYWORD` | `1` | 每个关键词的候选数 |
 | `TOPK_RETURN_RESULTS` | `20` | 重排序后返回的结果数 |
 
-## 外部向量数据库
-
-默认实现可以使用本地 FAISS。启用可选依赖后还可配置：
+## 向量索引后端
 
-| 配置项 | 默认值 |
-|---|---|
-| `QDRANT_HOST` | 空 |
-| `QDRANT_PORT` | `6333` |
-| `QDRANT_API_KEY` | 空 |
-| `MILVUS_HOST` | 空 |
-| `MILVUS_PORT` | `19530` |
-| `MILVUS_USER` | 空 |
-| `MILVUS_PASSWORD` | 空 |
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `CUR_VECTOR_INDEX` | `Faiss` | 当前使用的向量库：`Faiss`、`Milvus` 或 `Qdrant` |
+| `QDRANT_HOST` | 空 | |
+| `QDRANT_PORT` | `6333` | |
+| `QDRANT_API_KEY` | 空 | |
+| `MILVUS_HOST` | 空 | |
+| `MILVUS_PORT` | `19530` | |
+| `MILVUS_USER` | 空 | |
+| `MILVUS_PASSWORD` | 空 | |
 
-安装对应依赖：
+FAISS 在本地运行，无需额外依赖。未安装可选依赖就选择 `Milvus` 或 `Qdrant` 时，会报错并指出缺少的包，因此需要先安装：
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
+Web 页面的 `5. Set up the vector engine.` 面板提供同样的选择，并会保存所选引擎的连接配置。
+
 ## 登录与日志接口
 
 | 配置项 | 默认值 | 说明 |
@@ -148,9 +157,13 @@ GRAPH_PWD=your-password
 
 配置类先提供代码默认值，再从 `.env` 和进程环境读取覆盖值。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 `.env`。手工改动 `.env` 后应重启服务；提示词 YAML 可由页面加载逻辑刷新。
 
+`.env` 中的未知键会被忽略而不是报错，空值会回退到代码默认值，键名匹配不区分大小写。
+
 配置定义位于：
 
 - `hugegraph-llm/src/hugegraph_llm/config/llm_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/hugegraph_config.py`
+- `hugegraph-llm/src/hugegraph_llm/config/index_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/admin_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/prompt_config.py`
+- `hugegraph-llm/src/hugegraph_llm/config/models/base_config.py`：加载与文件同步逻辑
diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
index df071259a..748a8a7a0 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
@@ -10,9 +10,9 @@ HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演
 
 > AI 总结项目文档：[Ask DeepWiki](https://deepwiki.com/apache/hugegraph-ai)
 
-- Python 3.10 或 3.11
+- Python 3.10 或 3.11（`>=3.10,<3.12`）
 - `uv` 0.7 或更高版本
-- HugeGraph Server 1.5 或更高版本
+- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
 
 ## Docker Compose 部署
 
@@ -34,6 +34,32 @@ docker compose -f docker-compose-network.yml ps
 - HugeGraph Server：`http://localhost:8080`
 - RAG 服务和 Web 页面：`http://localhost:8001`
 
+Compose 文件会把 `${PROJECT_PATH}/hugegraph-llm/.env` 挂载到容器内的 `/home/work/hugegraph-llm/.env`，因此该文件必须在容器启动前存在。资源目录 `hugegraph-llm/src/hugegraph_llm/resources` 也可以用同样方式挂载，该挂载默认被注释掉。
+
+## 容器镜像
+
+| 镜像 | 构建文件 | 内容 |
+|---|---|---|
+| `hugegraph/rag` | `docker/Dockerfile.llm` | 包含源码的 Python 3.10 运行环境，入口是 `python -m hugegraph_llm.demo.rag_demo.app --host 0.0.0.0 --port 8001` |
+| `hugegraph/rag-bin` | `docker/Dockerfile.nk` | 基于 `nk-llm` extra 用 Nuitka 编译的二进制，入口是 `./app.dist/app.bin` |
+
+两个镜像都暴露 `8001` 端口，以非 root 用户 `work` 运行，为 `hugegraph-llm/src/hugegraph_llm/resources` 声明数据卷，并使用 `curl -f http://localhost:8001/` 作为健康检查。
+
+`scripts/build_llm_image.sh` 会用 `docker/Dockerfile.llm` 构建并打上 `hugegraph/graphrag:1.7.0` 标签。
+
+## Kubernetes 部署
+
+`docker/charts/hg-llm` 是 RAG 服务的 Helm chart，部署 `hugegraph/graphrag` 镜像。默认发布 `NodePort` 类型的 Service，把节点端口 `8039` 和服务端口 `8080` 映射到容器端口 `8001`，名称固定为 `hg-llm-service`。Ingress 和水平自动扩缩容已定义但默认关闭。
+
+chart 中 `image.tag` 仍默认为 `v0.0.1`，因此需要通过 `--set image.tag=1.7.0` 或修改 `values.yaml` 指向实际构建的标签。
+
+chart 的 `values.yaml` 中，`.env` 和提示词 YAML 的挂载默认被注释掉。要使用自定义配置，先创建两个 ConfigMap，再取消对应 `volumes` 和 `volumeMounts` 段落的注释：
+
+```bash
+kubectl create configmap hugegraph-llm-env --from-file=/path/to/.env
+kubectl create configmap hugegraph-llm-prompt-config --from-file=/path/to/config_prompt.yaml
+```
+
 ## 从源码启动
 
 依赖应从仓库根目录按 workspace 安装：
@@ -55,8 +81,12 @@ python -m hugegraph_llm.demo.rag_demo.app \
   --port 18001
 ```
 
+设置 `HG_DEV_RELOAD=1` 可让 uvicorn 以自动重载方式启动，便于开发调试。
+
 服务以 `hugegraph-llm/.env` 保存模型、HugeGraph 和登录配置。提示词放在 `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`。缺少文件时，配置代码会按默认值创建。
 
+`.env` 路径按以下顺序解析：先看是否设置了 `HUGEGRAPH_LLM_ENV_PATH`；未设置时，从源码运行则使用 `hugegraph-llm/.env`；否则使用当前工作目录下的 `.env`。
+
 ## 主要功能
 
 ### 构建 RAG 索引
@@ -67,34 +97,88 @@ Web 页面的第一个标签页可以处理文本或文件，并执行以下操
 2. 按给定 Schema 从文本抽取顶点和边。
 3. 将抽取结果写入 HugeGraph，并更新顶点向量索引。
 
+文本可以在 `text` 子页直接输入，也可以在 `file` 子页上传。上传支持 `.txt`、`.docx` 和 `.pdf`，并可一次选择多个文件。加密 PDF 以及没有可提取文本层的扫描件 PDF 会被拒绝。
+
 Schema 可以是内联 JSON，也可以是现有图名。通过 REST API 使用图名时，必须同时传入匹配的 `client_config.graph`；内联 JSON 不会连接 HugeGraph，也不能附带 `client_config`。
 
+该标签页还提供两个生成器。`Graph Schema Generator` 根据查询示例和少样本示例生成 Schema。`Graph Extraction Prompt Generator` 根据描述的场景和选定的参考示例生成抽取提示词。`Graph Extraction Split Type` 下拉框可在抽取前选择 `document`、`paragraph` 或 `sentence` 粒度。
+
 ### GraphRAG
 
 查询流程可以组合直接回答、chunk 向量召回和图召回。图召回先抽取关键词并匹配顶点，再尝试 Text2Gremlin；生成或执行失败时可回退到预定义的图遍历方式。请求参数可控制返回数量、向量距离阈值、模板数量和重排序方式。
 
+同一标签页还有批量回归测试面板，可从 `.xlsx` 或 `.csv` 文件读取问题、逐条作答，并返回可下载的结果文件。上传控件旁提供模板文件下载。
+
 ![知识图谱构建器](/images/docs/hugegraph-ai/gradio-kg.jpg)
 
 ### Text2Gremlin
 
 `POST /text2gremlin` 根据自然语言、图 Schema 和可选示例生成 Gremlin。自定义提示词必须保留 `{query}`、`{schema}`、`{example}` 和 `{vertices}` 四个占位符。
 
+对应的页面标签可以先用问题与 Gremlin 对照文件（`.json` 或 `.csv`）构建示例向量索引。未上传文件时使用内置的 `resources/demo/text2gremlin.csv`。
+
+### 图工具与管理工具
+
+`Graph Tools` 标签页可直接执行 Gremlin 查询、手动触发图备份，以及初始化 HugeGraph 演示数据。`Admin Tools` 标签页在校验 `ADMIN_TOKEN` 后展示 `logs/llm-server.log` 的末尾内容，并可刷新或清空该文件。
+
+进程运行期间还有两个后台任务：每天 01:00 执行图备份的定时任务，以及持续更新顶点 id 向量的任务。
+
 ## 模型与向量后端
 
-聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型也可以独立选择。默认向量索引使用 FAISS；安装 `vectordb` 可选依赖后，还可配置 Milvus 或 Qdrant：
+聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型可独立选择，同样支持这三种提供方。重排序支持 Cohere 和 SiliconFlow。
+
+默认向量索引使用 FAISS。`CUR_VECTOR_INDEX` 可选 `Faiss`、`Milvus` 或 `Qdrant`，Web 页面的 `5. Set up the vector engine.` 面板提供同样的选择。Milvus 和 Qdrant 需要安装可选依赖：
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
-完整环境变量见[配置参考](./config-reference.md)，HTTP 请求格式见[REST API](./rest-api.md)。
+页面操作流程见[使用流程](./quick_start.md)，完整环境变量见[配置参考](./config-reference.md)，HTTP 请求格式见[REST API](./rest-api.md)。
+
+## 程序化调用
+
+原有的 `RAGPipeline` 和 `KgBuilder` 类已被流水线调度器取代。通过 `SchedulerSingleton` 按名称调用流程：
+
+```python
+from hugegraph_llm.flows.scheduler import SchedulerSingleton
+
+scheduler = SchedulerSingleton.get_instance()
+res = scheduler.schedule_flow(
+    "rag_graph_only",
+    query="Tell me about Al Pacino.",
+    graph_only_answer=True,
+    vector_only_answer=False,
+    raw_answer=False,
+    gremlin_tmpl_num=-1,
+    gremlin_prompt=None,
+)
+print(res.get("graph_only_answer"))
+```
+
+已注册的流程名包括 `rag_raw`、`rag_vector_only`、`rag_graph_only`、`rag_graph_vector`、`text2gremlin`、`build_examples_index`、`build_vector_index`、`graph_extract`、`import_graph_data`、`update_vid_embeddings`、`get_graph_index_info`、`build_schema` 和 `prompt_generate`。`schedule_stream_flow` 是对应的异步流式版本。
 
 ## 开发检查
 
+先在仓库根目录安装模块和开发工具，再运行与 CI 一致的检查：
+
 ```bash
 cd hugegraph-ai
-./style/code_format_and_analysis.sh
+uv sync --extra llm --extra dev
+uv run ruff format --check .
+uv run ruff check .
+
 cd hugegraph-llm
-pytest
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/config/ src/tests/document/ src/tests/middleware/ \
+  src/tests/operators/ src/tests/models/ src/tests/indices/ src/tests/test_utils.py -v --tb=short
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/integration/test_graph_rag_pipeline.py \
+  src/tests/integration/test_kg_construction.py src/tests/integration/test_rag_pipeline.py -v --tb=short
+```
+
+Git hook 通过 pre-commit 启用：
+
+```bash
+cd hugegraph-ai
+pre-commit install
+pre-commit run --all-files
 ```
diff --git a/content/cn/docs/quickstart/hugegraph-ai/quick_start.md b/content/cn/docs/quickstart/hugegraph-ai/quick_start.md
index 8585ca1f1..721fdf026 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/quick_start.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/quick_start.md
@@ -6,6 +6,10 @@ weight: 3
 
 本文说明 HugeGraph-LLM Web 页面的处理流程。服务启动方式见 [HugeGraph-LLM](./hugegraph-llm.md)。
 
+## 0. 配置面板
+
+标签页上方是可折叠的配置面板，共五个部分：`1. Set up the HugeGraph server.`、`2. Set up the LLM.`、`3. Set up the Embedding.`、`4. Set up the Reranker.` 和 `5. Set up the vector engine.`。每部分都有独立的应用按钮，应用后会把受支持的字段写回 `.env`。页面顶部还会显示当前提示词语言。
+
 ## 1. 构建 RAG 索引
 
 第一个标签页负责两类索引：
@@ -23,15 +27,24 @@ flowchart TD
     F --> G[更新顶点向量索引]
 ```
 
+输入来自 `text` 子页或 `file` 子页。上传支持 `.txt`、`.docx` 和 `.pdf`，可一次选择多个文件。
+
 页面包含文档、Schema、抽取提示词和结果区域。常用操作有：
 
 1. `Import into Vector`：切分文档并建立 chunk 向量索引。
-2. `Extract Graph Data`：按 Schema 抽取图数据。
-3. `Load into GraphDB`：把抽取结果写入 HugeGraph，并更新顶点向量。
-4. `Update Vid Embedding`：重新生成顶点向量。
+2. `Extract Graph Data (1)`：按 Schema 抽取图数据。
+3. `Load into GraphDB (2)`：把抽取结果写入 HugeGraph，并自动更新顶点向量。
+4. `Update Vid Embedding`：重新生成顶点向量，通常只在图中已有数据时才需要单独执行。
+
+这些按钮旁的 `Graph Extraction Split Type` 下拉框可选 `document`、`paragraph` 或 `sentence`。`document` 把输入整体作为一个单元，另外两种会在抽取前先切分长文档。
 
 页面还可以查看或清除 chunk 索引、顶点索引和图数据。清除操作会删除已有数据，执行前先确认当前图和索引是否仍被其他查询使用。
 
+主控件下方还有两个折叠的辅助工具：
+
+- `Graph Schema Generator`：根据查询示例和少样本示例生成 Schema，填入 Graph Schema 字段。
+- `Graph Extraction Prompt Generator`：根据期望场景（例如社交关系、金融知识图谱）和选定的参考示例生成 Graph Extract Prompt Header。
+
 ## 2. GraphRAG 查询
 
 第二个标签页提供四种回答范围：
@@ -57,24 +70,40 @@ flowchart TD
 
 图召回先用关键词精确匹配 HugeGraph 顶点，找不到时再用顶点向量做近似匹配。匹配结果会进入 Text2Gremlin；生成或执行失败时，流程可以回退到预定义的图遍历。
 
-`Template Num` 控制 Text2Gremlin 使用的示例数量。小于等于 0 表示不提供模板，大于 0 表示从示例索引中取相应数量的相近模板。
+`Template Num` 控制 Text2Gremlin 在图召回中的参与方式：
+
+- 小于 0：完全跳过 Text2Gremlin，图召回直接使用预定义的图遍历。
+- 等于 0：不带任何示例生成 Gremlin（zero-shot）。
+- 大于 0：从示例索引中取相应数量的相近示例，并采用带模板的生成结果。示例数量会被限制在 0 到 10 之间。
+
+该标签页的其他控件还有 `Rerank method`（`bleu` 或 `reranker`）、`Graph Ratio`、`Near neighbor first` 和 `Query related information`，以及可编辑的 `Query Prompt` 和 `Keywords Extraction Prompt`。
+
+单条问答面板下方是批量回归测试面板。上传 `.xlsx` 或 `.csv` 问题文件，设置 `Max Lines To Show`，点击 `Generate Answer (Batch)`。答案会显示在预览表格中，并可下载为文件。上传控件旁提供模板文件下载。
 
 ## 3. Text2Gremlin
 
-第三个标签页把自然语言转换成 Gremlin：
+第三个标签页分为两部分。上半部分用问题与 Gremlin 对照文件（`.json` 或 `.csv`）构建示例向量索引；未上传文件时使用内置的 `resources/demo/text2gremlin.csv`。
+
+下半部分把自然语言转换成 Gremlin：
 
 1. 读取当前图的 Schema。
 2. 从示例向量索引取回相近的自然语言与 Gremlin 对。
 3. 把问题、Schema、示例和已匹配顶点填入提示词。
 4. 调用 LLM 生成 Gremlin，并按所选输出类型决定是否执行。
 
+`Number of refer examples` 设置取回的示例数量，范围 0 到 10，默认 2。结果显示在四个字段中：带模板的 Gremlin、不带模板的 Gremlin，以及两者各自的执行输出。
+
 ![RAG 查询范围选择](/images/docs/hugegraph-ai/quick-start-03.jpg)
 
 自定义提示词必须包含 `{query}`、`{schema}`、`{example}` 和 `{vertices}`。缺少任一占位符时，REST API 会拒绝请求。
 
 ## 4. 图工具与管理工具
 
-`Graph Tools` 标签页用于直接执行图操作。`Admin Tools` 提供日志等管理能力。启用登录后，页面和 API 需要使用 `USER_TOKEN`；日志接口还要求单独配置安全的 `ADMIN_TOKEN`。
+`Graph Tools` 标签页可直接对当前图执行 Gremlin 查询、手动触发图备份，并通过 beta 操作初始化 HugeGraph 演示数据。后台还有两个任务：每天 01:00 自动备份图数据，以及在进程运行期间持续更新顶点 id 向量。
+
+`Admin Tools` 需要密码。输入已配置的 `ADMIN_TOKEN` 后可查看 `logs/llm-server.log` 的末尾内容（每 60 秒自动刷新），并可手动刷新或清空该文件。`ADMIN_TOKEN` 为空或仍是占位值 `xxxx` 时，访问会被拒绝。
+
+设置 `ENABLE_LOGIN=True` 后，Web 页面会要求基础认证，用户名固定为 `rag`，密码是 `USER_TOKEN`；REST API 则要求把 `USER_TOKEN` 作为 Bearer token。日志接口还要求单独配置安全的 `ADMIN_TOKEN`。
 
 ![RAG 界面中抽取的关键词](/images/docs/hugegraph-ai/quick-start-04.png)
 
diff --git a/content/cn/docs/quickstart/hugegraph-ai/rest-api.md b/content/cn/docs/quickstart/hugegraph-ai/rest-api.md
index b0d301ee0..a99d6f49e 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/rest-api.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/rest-api.md
@@ -13,6 +13,20 @@ python -m hugegraph_llm.demo.rag_demo.app \
   --port 8001
 ```
 
+所有接口都使用 `POST`：
+
+| 路径 | 成功状态码 | 用途 |
+|---|---|---|
+| `/rag` | 200 | 按所选召回方式回答问题 |
+| `/rag/graph` | 200 | 只做图召回，不生成最终答案 |
+| `/graph/extract` | 200 | 从文本抽取顶点和边 |
+| `/text2gremlin` | 200 | 由自然语言生成 Gremlin |
+| `/config/graph` | 201 | 更新 HugeGraph 连接 |
+| `/config/llm` | 201 | 更新语言模型 |
+| `/config/embedding` | 201 | 更新嵌入模型 |
+| `/config/rerank` | 201 | 更新重排序模型 |
+| `/logs` | 200 | 流式返回服务日志 |
+
 ## 认证
 
 在 `.env` 中启用登录：
@@ -28,6 +42,8 @@ USER_TOKEN=replace-with-a-secret
 Authorization: Bearer replace-with-a-secret
 ```
 
+同一开关也会给 Gradio 页面加上基础认证，用户名固定为 `rag`，密码是 `USER_TOKEN`。token 不正确时返回 401，并带上 `WWW-Authenticate: Bearer` 响应头。`ENABLE_LOGIN` 保持 `False` 时所有接口都不做鉴权。
+
 ## RAG
 
 ### `POST /rag`
@@ -67,7 +83,11 @@ curl -X POST http://localhost:8001/rag \
 }
 ```
 
-其他可选参数包括 `graph_ratio`、`rerank_method`（`bleu` 或 `reranker`）、`near_neighbor_first`、`custom_priority_info`，以及三类自定义提示词。
+其他可选参数包括 `graph_ratio`（默认 `0.5`）、`rerank_method`（`bleu` 或 `reranker`，默认 `bleu`）、`near_neighbor_first`（默认 `false`）、`custom_priority_info`，以及三个自定义提示词字段 `answer_prompt`、`keywords_extract_prompt` 和 `gremlin_prompt`。省略提示词字段时使用 `config_prompt.yaml` 中的值。
+
+`gremlin_tmpl_num` 决定图召回阶段 Text2Gremlin 的执行方式：小于 0 表示跳过 Text2Gremlin，直接使用预定义的图遍历；等于 0 表示不带示例生成 Gremlin；大于 0 表示从示例索引中取相应数量的示例。
+
+`query` 为空或只有空白字符时返回 400。
 
 ### `POST /rag/graph`
 
@@ -84,7 +104,9 @@ curl -X POST http://localhost:8001/rag/graph \
   }'
 ```
 
-响应的 `graph_recall` 可能包含 `keywords`、`match_vids`、`gremlin`、`graph_result` 和 `vertex_degree_list`。设置 `get_vertex_only=true` 可在顶点匹配后提前返回。
+响应的 `graph_recall` 可能包含 `query`、`keywords`、`match_vids`、`graph_result_flag`、`gremlin`、`graph_result` 和 `vertex_degree_list`。设置 `get_vertex_only=true` 可在顶点匹配后提前返回，此时接口会把 `match_vids` 替换为完整的顶点详情。
+
+`query` 为空返回 400，请求类型错误返回 400，其他失败返回 500。
 
 ## 图抽取
 
@@ -117,9 +139,22 @@ curl -X POST http://localhost:8001/graph/extract \
   }'
 ```
 
-`texts` 可以是字符串或字符串数组。`language` 可选 `zh`、`en`，`split_type` 可选 `document`、`paragraph`、`sentence`。
+请求字段：
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `texts` | 必填 | 字符串或字符串数组；空白项会被丢弃，全部为空时报错 |
+| `schema` | 必填 | 内联 JSON 对象或字符串，或现有图名 |
+| `example_prompt` | 提示词 YAML 中的值 | 抽取提示词头部 |
+| `extract_type` | `property_graph` | 目前仅接受该值 |
+| `language` | `zh` | `zh` 或 `en`，用于文本切分 |
+| `split_type` | `document` | `document`、`paragraph` 或 `sentence` |
+| `include_meta` | `false` | 在 `meta` 中加入 `vertex_count`、`edge_count` 和 `text_count` |
+| `client_config` | 无 | 仅在 `schema` 为图名时允许传入 |
 
-若 `schema` 传现有图名，必须同时传入 `client_config`，且 `client_config.graph` 必须和图名相同：
+内联 Schema 必须是包含 `vertexlabels` 和 `edgelabels` 两个列表的对象。每个顶点标签需要非空的 `name` 和非空的 `properties` 列表；每条边标签需要非空的 `name`、`source_label` 和 `target_label`。`propertykeys` 可选，若存在必须是列表。
+
+若 `schema` 传现有图名，必须同时传入 `client_config`，且 `client_config.graph` 必须和图名相同。这里的 `client_config` 只接受 `graph`、`user`、`pwd` 和 `gs`，未知字段会被拒绝，且没有 `url` 字段：
 
 ```json
 {
@@ -134,7 +169,7 @@ curl -X POST http://localhost:8001/graph/extract \
 }
 ```
 
-成功响应固定包含 `status`、`result.vertices`、`result.edges`、`warnings` 和 `meta`。
+成功响应固定包含 `status`（始终为 `succeeded`）、`result.vertices`、`result.edges`、`warnings` 和 `meta`。`include_meta` 不为 `true` 时 `meta` 为空。
 
 ## Text2Gremlin
 
@@ -158,7 +193,9 @@ curl -X POST http://localhost:8001/text2gremlin \
 - `template_execution_result`
 - `raw_execution_result`
 
-省略该字段时默认只返回 `template_gremlin`；传空数组表示由实现返回全部输出。自定义 `gremlin_prompt` 必须包含 `{query}`、`{schema}`、`{example}` 和 `{vertices}`。
+省略该字段时默认只返回 `template_gremlin`；传空数组表示由实现返回全部输出。自定义 `gremlin_prompt` 必须包含 `{query}`、`{schema}`、`{example}` 和 `{vertices}`，缺少占位符时请求校验失败，并会列出缺失的占位符。
+
+`example_num` 默认是 `0`，表示不使用模板，取值会被限制在 0 到 10 之间。`client_config` 只在单次请求内覆盖 HugeGraph 连接，生成时使用的 Schema 是当前生效的图名。`query` 为空返回 400，生成失败返回 500。
 
 ## 运行时配置
 
@@ -174,9 +211,11 @@ curl -X POST http://localhost:8001/text2gremlin \
 }
 ```
 
+`user` 和 `pwd` 默认是空字符串，`gs` 可选。
+
 ### `POST /config/llm` 与 `POST /config/embedding`
 
-两个端点使用同一个请求模型。OpenAI 或 LiteLLM 示例：
+两个端点使用同一个请求模型。`/config/llm` 会把 `chat_llm_type`、`extract_llm_type` 和 `text2gql_llm_type` 一起设为相同的值；要分别设置各任务的类型，只能通过 `.env` 或 Web 页面。OpenAI 或 LiteLLM 示例：
 
 ```json
 {
@@ -213,7 +252,9 @@ Ollama 请求仍要提供公共字段；`api_key` 和 `api_base` 可传空字符
 
 `reranker_type` 可选 `cohere`、`siliconflow`。Cohere 还可以传 `cohere_base_url`。
 
-这些配置端点会改动进程当前配置，并可能同步到 `.env`。`/rag`、`/rag/graph` 和 `/text2gremlin` 的 `client_config` 只在单次请求期间覆盖 HugeGraph 连接；当前实现仍会临时改动进程全局设置，不适合用不同连接并发发起长请求。
+四个配置端点成功时都返回 201。它们会改动进程当前配置，并可能同步到 `.env`。`/config/llm`、`/config/embedding` 和 `/config/rerank` 在应用过程中抛出异常时会回滚到原有取值，`/config/graph` 不会。
+
+`/rag`、`/rag/graph` 和 `/text2gremlin` 的 `client_config` 只在单次请求期间覆盖 HugeGraph 连接，且仅应用请求中实际出现的字段。当前实现仍会临时改动进程全局设置，不适合用不同连接并发发起长请求。
 
 ## 日志
 
@@ -228,4 +269,8 @@ Ollama 请求仍要提供公共字段；`api_key` 和 `api_base` 可传空字符
 }
 ```
 
-`log_file` 只能是 `logs/` 目录下的文件名，不能包含路径分隔符。
+`log_file` 默认是 `llm-server.log`，只能是 `logs/` 目录下的文件名，不能是绝对路径、不能包含路径分隔符，也不能解析为 `.` 或 `..`。非法文件名返回 400。
+
+`ADMIN_TOKEN` 未设置或仍是占位值时，在比对 token 之前就返回 403；token 不匹配时返回内容为 `Invalid admin_token` 的 403 响应。
+
+成功时返回 `text/plain` 流：先回放文件末尾 125 行，然后像 `tail -f` 一样持续输出新内容。
diff --git a/content/en/docs/quickstart/hugegraph-ai/_index.md b/content/en/docs/quickstart/hugegraph-ai/_index.md
index ccd3c6af8..aef6e58f8 100644
--- a/content/en/docs/quickstart/hugegraph-ai/_index.md
+++ b/content/en/docs/quickstart/hugegraph-ai/_index.md
@@ -15,14 +15,31 @@ weight: 3
 - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client): a Python SDK for managing schemas and graph data and running Gremlin queries.
 - [vermeer-python-client](https://github.com/apache/hugegraph-ai/tree/main/vermeer-python-client): a Python SDK for the Vermeer graph computing service.
 
-The repository uses a `uv` workspace to manage the LLM and Python client packages. HugeGraph-ML is a path dependency rather than a workspace member.
+The repository uses a `uv` workspace whose members are `hugegraph-llm` and `hugegraph-python-client`. `hugegraph-ml` and `vermeer-python-client` are editable path dependencies rather than workspace members. The current repository version is `1.7.0`.
 
 ## Requirements
 
-- HugeGraph-LLM: Python 3.10 or 3.11
-- HugeGraph-ML and the Python clients: Python 3.10 or later
+- HugeGraph-LLM: Python 3.10 or 3.11 (`>=3.10,<3.12`)
+- HugeGraph-ML: Python 3.10 or later
+- HugeGraph Python client and Vermeer Python client: Python 3.9 or later
 - `uv` 0.7 or later
-- HugeGraph Server 1.5 or later
+- HugeGraph Server 1.3 or later (1.5 or later recommended)
+
+## Optional Dependency Groups
+
+The root project declares one extra per module plus a few combined ones:
+
+| Extra | Installs |
+|---|---|
+| `llm` | `hugegraph-llm` |
+| `ml` | `hugegraph-ml` |
+| `python-client` | `hugegraph-python-client` |
+| `vermeer` | `vermeer-python-client` |
+| `dev` | pytest, pytest-cov, coverage, pylint, ruff, mypy, ty, pre-commit |
+| `nk-llm` | `hugegraph-llm`, `hugegraph-python-client`, and Nuitka for the compiled image |
+| `all` | all four module packages |
+
+`hugegraph-llm` itself declares a `vectordb` extra that adds `pymilvus` and `qdrant-client`.
 
 ## Deploy with Docker Compose
 
@@ -70,6 +87,7 @@ Example scripts are under `hugegraph-ml/src/hugegraph_ml/examples/`.
 ## Next Steps
 
 - [HugeGraph-LLM](./hugegraph-llm.md)
+- [HugeGraph-LLM workflow](./quick_start.md)
 - [Configuration reference](./config-reference.md)
 - [REST API](./rest-api.md)
 - [HugeGraph-ML](./hugegraph-ml.md)
diff --git a/content/en/docs/quickstart/hugegraph-ai/config-reference.md b/content/en/docs/quickstart/hugegraph-ai/config-reference.md
index 7e5824f73..bc9092691 100644
--- a/content/en/docs/quickstart/hugegraph-ai/config-reference.md
+++ b/content/en/docs/quickstart/hugegraph-ai/config-reference.md
@@ -6,6 +6,12 @@ weight: 4
 
 HugeGraph-LLM reads runtime settings from `hugegraph-llm/.env`. Prompts are stored separately in `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml` and are not written to `.env`.
 
+The `.env` path is resolved in this order:
+
+1. `HUGEGRAPH_LLM_ENV_PATH`, if that environment variable is set. A leading `~` is expanded.
+2. `hugegraph-llm/.env`, when the package runs from a source checkout.
+3. `.env` in the current working directory, for an installed package.
+
 Create or update the files from configuration-class defaults with:
 
 ```bash
@@ -13,6 +19,8 @@ cd hugegraph-ai/hugegraph-llm
 python -m hugegraph_llm.config.generate --update
 ```
 
+`--update` is on by default, so running the module without arguments does the same thing. The command writes the HugeGraph, admin, LLM, and index settings, then regenerates the prompt YAML. If `.env` already exists, it asks for confirmation before overwriting.
+
 `.env` contains keys and passwords. Do not commit it to version control.
 
 ## Basic Options
@@ -91,25 +99,28 @@ The default host is `127.0.0.1` and the default port is `11434`. Model names hav
 | `TOPK_PER_KEYWORD` | `1` | Candidates per keyword |
 | `TOPK_RETURN_RESULTS` | `20` | Results returned after reranking |
 
-## External Vector Databases
+## Vector Index Backend
 
-The default implementation can use local FAISS. After enabling optional dependencies, the following settings are also available:
+| Setting | Default | Description |
+|---|---|---|
+| `CUR_VECTOR_INDEX` | `Faiss` | Active vector store: `Faiss`, `Milvus`, or `Qdrant` |
+| `QDRANT_HOST` | empty | |
+| `QDRANT_PORT` | `6333` | |
+| `QDRANT_API_KEY` | empty | |
+| `MILVUS_HOST` | empty | |
+| `MILVUS_PORT` | `19530` | |
+| `MILVUS_USER` | empty | |
+| `MILVUS_PASSWORD` | empty | |
 
-| Setting | Default |
-|---|---|
-| `QDRANT_HOST` | empty |
-| `QDRANT_PORT` | `6333` |
-| `QDRANT_API_KEY` | empty |
-| `MILVUS_HOST` | empty |
-| `MILVUS_PORT` | `19530` |
-| `MILVUS_USER` | empty |
-| `MILVUS_PASSWORD` | empty |
+FAISS is local and needs no extra dependency. Selecting `Milvus` or `Qdrant` without the optional dependencies raises an error that names the missing package, so install them first:
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
+The same choice is available in the `5. Set up the vector engine.` panel of the Web UI, which also persists the connection settings for the selected engine.
+
 ## Login and Log API
 
 | Setting | Default | Description |
@@ -146,9 +157,13 @@ GRAPH_PWD=your-password
 
 Configuration classes supply code defaults and then apply overrides from `.env` and the process environment. The Web UI and configuration APIs can update current settings at runtime and write supported fields back to `.env`. Restart the service after editing `.env` manually; prompt YAML can be refreshed by the page-loading logic.
 
+Unknown keys in `.env` are ignored rather than rejected, and empty values fall back to the code default. Keys are matched case-insensitively.
+
 Configuration definitions are in:
 
 - `hugegraph-llm/src/hugegraph_llm/config/llm_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/hugegraph_config.py`
+- `hugegraph-llm/src/hugegraph_llm/config/index_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/admin_config.py`
 - `hugegraph-llm/src/hugegraph_llm/config/prompt_config.py`
+- `hugegraph-llm/src/hugegraph_llm/config/models/base_config.py` for the loading and file-sync behaviour
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-llm.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-llm.md
index f83080742..d817d80fe 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-llm.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-llm.md
@@ -10,9 +10,9 @@ HugeGraph-LLM connects graph databases with large language models for knowledge
 
 > AI-generated project documentation: [Ask DeepWiki](https://deepwiki.com/apache/hugegraph-ai)
 
-- Python 3.10 or 3.11
+- Python 3.10 or 3.11 (`>=3.10,<3.12`)
 - `uv` 0.7 or later
-- HugeGraph Server 1.5 or later
+- HugeGraph Server 1.3 or later (1.5 or later recommended)
 
 ## Deploy with Docker Compose
 
@@ -31,6 +31,32 @@ docker compose -f docker-compose-network.yml ps
 
 After startup, HugeGraph Server is available at `http://localhost:8080`, and the RAG service and Web UI are available at `http://localhost:8001`.
 
+The Compose file mounts `${PROJECT_PATH}/hugegraph-llm/.env` into the container at `/home/work/hugegraph-llm/.env`, so the file has to exist before the container starts. The resource directory `hugegraph-llm/src/hugegraph_llm/resources` can be mounted the same way; the mount is commented out by default.
+
+## Container Images
+
+| Image | Built from | Contents |
+|---|---|---|
+| `hugegraph/rag` | `docker/Dockerfile.llm` | Python 3.10 runtime with the source tree, started with `python -m hugegraph_llm.demo.rag_demo.app --host 0.0.0.0 --port 8001` |
+| `hugegraph/rag-bin` | `docker/Dockerfile.nk` | Nuitka-compiled binary built from the `nk-llm` extra, started with `./app.dist/app.bin` |
+
+Both images expose port `8001`, run as the non-root user `work`, declare a volume for `hugegraph-llm/src/hugegraph_llm/resources`, and use `curl -f http://localhost:8001/` as their health check.
+
+`scripts/build_llm_image.sh` builds `docker/Dockerfile.llm` and tags the result `hugegraph/graphrag:1.7.0`.
+
+## Deploy on Kubernetes
+
+`docker/charts/hg-llm` is a Helm chart for the RAG service. It deploys the `hugegraph/graphrag` image and, by default, publishes a `NodePort` service that maps node port `8039` and service port `8080` onto container port `8001`. The release name is fixed to `hg-llm-service`. Ingress and horizontal pod autoscaling are present but disabled by default.
+
+The chart still defaults `image.tag` to `v0.0.1`, so set `--set image.tag=1.7.0` or edit `values.yaml` to match the tag you built.
+
+The chart ships the `.env` and prompt YAML mounts commented out in `values.yaml`. To supply your own configuration, create the two config maps and then uncomment the matching `volumes` and `volumeMounts` blocks:
+
+```bash
+kubectl create configmap hugegraph-llm-env --from-file=/path/to/.env
+kubectl create configmap hugegraph-llm-prompt-config --from-file=/path/to/config_prompt.yaml
+```
+
 ## Start from Source
 
 Install dependencies through the workspace at the repository root:
@@ -52,40 +78,98 @@ python -m hugegraph_llm.demo.rag_demo.app \
   --port 18001
 ```
 
+Set `HG_DEV_RELOAD=1` to start uvicorn with auto-reload during development.
+
 The service stores model, HugeGraph, and login settings in `hugegraph-llm/.env`. Prompts are stored separately in `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`. The configuration code creates missing files with default values.
 
+The `.env` location is resolved in this order: `HUGEGRAPH_LLM_ENV_PATH` if it is set, then `hugegraph-llm/.env` when the package runs from a source checkout, then `.env` in the current working directory.
+
 ## Main Capabilities
 
 ### Build RAG Indexes
 
-The first Web UI tab splits text into a chunk vector index, extracts vertices and edges according to a schema, writes the graph to HugeGraph, and updates the vertex vector index. The schema can be inline JSON or the name of an existing graph. Through the REST API, a graph name requires a matching `client_config.graph`; inline JSON neither connects to HugeGraph nor accepts `client_config`.
+The first Web UI tab splits text into a chunk vector index, extracts vertices and edges according to a schema, writes the graph to HugeGraph, and updates the vertex vector index. Input can be typed into the `text` tab or uploaded through the `file` tab, which accepts `.txt`, `.docx`, and `.pdf` files and allows selecting several at once. Encrypted PDFs and scanned PDFs without an extractable text layer are rejected.
+
+The schema can be inline JSON or the name of an existing graph. Through the REST API, a graph name requires a matching `client_config.graph`; inline JSON neither connects to HugeGraph nor accepts `client_config`.
+
+The tab also carries two generators. `Graph Schema Generator` derives a schema from query examples plus a few-shot example. `Graph Extraction Prompt Generator` writes an extraction prompt from a described scenario and a selected reference example. A `Graph Extraction Split Type` dropdown chooses `document`, `paragraph`, or `sentence` granularity before extraction.
 
 ### GraphRAG
 
 The query pipeline can combine direct LLM answers, chunk-vector retrieval, and graph retrieval. Graph retrieval first extracts keywords and matches vertices, then attempts Text2Gremlin. If generation or execution fails, it can fall back to predefined graph traversals. Request parameters control result limits, vector distance thresholds, template counts, and reranking.
 
+The same tab has a batch back-testing panel that reads questions from an `.xlsx` or `.csv` file, answers each one, and returns a downloadable file. A template file is offered for download next to the upload control.
+
 ![Knowledge graph builder](/images/docs/hugegraph-ai/gradio-kg.jpg)
 
 ### Text2Gremlin
 
 `POST /text2gremlin` generates Gremlin from natural language, the graph schema, and optional examples. A custom prompt must retain `{query}`, `{schema}`, `{example}`, and `{vertices}`.
 
+The matching UI tab can first build the example vector index from a `.json` or `.csv` file of question and Gremlin pairs. The bundled `resources/demo/text2gremlin.csv` is used when no file is supplied.
+
+### Graph and Admin Tools
+
+The `Graph Tools` tab runs a Gremlin query directly, triggers a manual graph backup, and can initialize demo data in HugeGraph. The `Admin Tools` tab shows the last lines of `logs/llm-server.log` behind an `ADMIN_TOKEN` prompt, and can refresh or clear that file.
+
+Two background tasks run for the lifetime of the process: a cron job that backs up the graph every day at 01:00, and a task that keeps vertex-id embeddings up to date.
+
 ## Models and Vector Backends
 
-Chat, information extraction, and Text2Gremlin can independently use an OpenAI-compatible endpoint, Ollama, or LiteLLM. The embedding model is configured separately. FAISS is the default vector index; Milvus or Qdrant are available after installing the optional dependencies:
+Chat, information extraction, and Text2Gremlin can independently use an OpenAI-compatible endpoint, Ollama, or LiteLLM. The embedding model is configured separately and supports the same three providers. Reranking supports Cohere and SiliconFlow.
+
+FAISS is the default vector index. `CUR_VECTOR_INDEX` selects `Faiss`, `Milvus`, or `Qdrant`, and the same choice is available in the `5. Set up the vector engine.` panel of the Web UI. Milvus and Qdrant require the optional dependencies:
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
-See the [configuration reference](./config-reference.md) and [REST API](./rest-api.md) for details.
+See the [workflow guide](./quick_start.md), the [configuration reference](./config-reference.md), and the [REST API](./rest-api.md) for details.
+
+## Programmatic Use
+
+The former `RAGPipeline` and `KgBuilder` classes were replaced by a pipeline scheduler. Call a flow by name through `SchedulerSingleton`:
+
+```python
+from hugegraph_llm.flows.scheduler import SchedulerSingleton
+
+scheduler = SchedulerSingleton.get_instance()
+res = scheduler.schedule_flow(
+    "rag_graph_only",
+    query="Tell me about Al Pacino.",
+    graph_only_answer=True,
+    vector_only_answer=False,
+    raw_answer=False,
+    gremlin_tmpl_num=-1,
+    gremlin_prompt=None,
+)
+print(res.get("graph_only_answer"))
+```
+
+The registered flow names are `rag_raw`, `rag_vector_only`, `rag_graph_only`, `rag_graph_vector`, `text2gremlin`, `build_examples_index`, `build_vector_index`, `graph_extract`, `import_graph_data`, `update_vid_embeddings`, `get_graph_index_info`, `build_schema`, and `prompt_generate`. `schedule_stream_flow` is the async streaming variant.
 
 ## Development Checks
 
+Install the module and the development tools from the repository root, then run the checks that mirror CI:
+
 ```bash
 cd hugegraph-ai
-./style/code_format_and_analysis.sh
+uv sync --extra llm --extra dev
+uv run ruff format --check .
+uv run ruff check .
+
 cd hugegraph-llm
-pytest
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/config/ src/tests/document/ src/tests/middleware/ \
+  src/tests/operators/ src/tests/models/ src/tests/indices/ src/tests/test_utils.py -v --tb=short
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/integration/test_graph_rag_pipeline.py \
+  src/tests/integration/test_kg_construction.py src/tests/integration/test_rag_pipeline.py -v --tb=short
+```
+
+Git hooks are available through pre-commit:
+
+```bash
+cd hugegraph-ai
+pre-commit install
+pre-commit run --all-files
 ```
diff --git a/content/en/docs/quickstart/hugegraph-ai/quick_start.md b/content/en/docs/quickstart/hugegraph-ai/quick_start.md
index 8616ed1d6..5495f1ee3 100644
--- a/content/en/docs/quickstart/hugegraph-ai/quick_start.md
+++ b/content/en/docs/quickstart/hugegraph-ai/quick_start.md
@@ -6,6 +6,10 @@ weight: 3
 
 This page explains the processing flow in the HugeGraph-LLM Web UI. See [HugeGraph-LLM](./hugegraph-llm.md) for startup instructions.
 
+## 0. Configuration Panel
+
+Above the tabs sits a collapsible configuration panel with five sections: `1. Set up the HugeGraph server.`, `2. Set up the LLM.`, `3. Set up the Embedding.`, `4. Set up the Reranker.`, and `5. Set up the vector engine.`. Each section has its own apply button, and applying a change writes the supported fields back to `.env`. The header also shows the current prompt language.
+
 ## 1. Build RAG Indexes
 
 The first tab splits documents into a chunk vector index. It also extracts vertices and edges according to a schema, writes them to HugeGraph, and maintains a vertex vector index.
@@ -20,7 +24,16 @@ flowchart TD
     F --> G[Update vertex vector index]
 ```
 
-Common operations are `Import into Vector`, `Extract Graph Data`, `Load into GraphDB`, and `Update Vid Embedding`. The page can also inspect or clear chunk indexes, vertex indexes, and graph data. Clearing removes existing data, so first confirm that the current graph and indexes are not still used by other queries.
+Input comes from either the `text` sub-tab or the `file` sub-tab. Uploads accept `.txt`, `.docx`, and `.pdf`, and several files can be selected at once.
+
+Common operations are `Import into Vector`, `Extract Graph Data (1)`, `Load into GraphDB (2)`, and `Update Vid Embedding`. `Load into GraphDB (2)` also refreshes the vertex vector index, so the separate `Update Vid Embedding` step is only needed when the graph already held data. The `Graph Extraction Split Type` dropdown next to these buttons chooses `document`, `paragraph`, or `sentence`. `document` keeps the whole input as one unit; the other two split long documents before extraction.
+
+The page can also inspect or clear chunk indexes, vertex indexes, and graph data. Clearing removes existing data, so first confirm that the current graph and indexes are not still used by other queries.
+
+Two collapsed helpers sit below the main controls:
+
+- `Graph Schema Generator` takes query examples and a few-shot example and produces a schema for the Graph Schema field.
+- `Graph Extraction Prompt Generator` takes an expected scenario, such as social relationships or a financial knowledge graph, and a selected reference example, and produces a Graph Extract Prompt Header.
 
 ## 2. GraphRAG Queries
 
@@ -42,11 +55,21 @@ flowchart TD
 
 Graph retrieval first matches HugeGraph vertices exactly by keyword and then uses vector similarity if no exact match exists. The matched vertices are passed to Text2Gremlin. If generation or execution fails, the pipeline can fall back to a predefined traversal.
 
-`Template Num` controls how many examples Text2Gremlin uses. A value less than or equal to zero supplies no templates; a positive value retrieves that many similar examples.
+`Template Num` controls how Text2Gremlin participates in graph retrieval:
+
+- A negative value skips Text2Gremlin entirely, so graph retrieval goes straight to the predefined traversal.
+- `0` generates Gremlin without any examples (zero-shot).
+- A positive value retrieves that many similar examples from the example index and uses the template-guided result. The example count is clamped to the range 0 to 10.
+
+Other controls on this tab are `Rerank method` (`bleu` or `reranker`), `Graph Ratio`, `Near neighbor first`, and `Query related information`, plus editable `Query Prompt` and `Keywords Extraction Prompt` fields.
+
+Below the single-question panel is a batch back-testing panel. Upload an `.xlsx` or `.csv` file of questions, set `Max Lines To Show`, and click `Generate Answer (Batch)`. The answers appear in a preview table and can be downloaded as a file. A template file is offered next to the upload control.
 
 ## 3. Text2Gremlin
 
-The third tab reads the graph schema, retrieves similar natural-language and Gremlin examples, fills the prompt with the question, schema, examples, and matched vertices, then generates Gremlin and optionally executes it.
+The third tab has two parts. The upper part builds the example vector index from a `.json` or `.csv` file of question and Gremlin pairs; the bundled `resources/demo/text2gremlin.csv` is used when no file is uploaded.
+
+The lower part reads the graph schema, retrieves similar natural-language and Gremlin examples, fills the prompt with the question, schema, examples, and matched vertices, then generates Gremlin and optionally executes it. `Number of refer examples` sets how many examples are retrieved, from 0 to 10, and defaults to 2. The results appear in four fields: Gremlin with a template, Gremlin without a template, and the execution output for each.
 
 ![RAG query scope selector](/images/docs/hugegraph-ai/quick-start-03.jpg)
 
@@ -54,7 +77,11 @@ A custom prompt must contain `{query}`, `{schema}`, `{example}`, and `{vertices}
 
 ## 4. Graph and Administration Tools
 
-`Graph Tools` runs graph operations directly. `Admin Tools` provides functions such as log access. When login is enabled, the UI and APIs require `USER_TOKEN`; the log endpoint additionally requires a separately configured, secure `ADMIN_TOKEN`.
+`Graph Tools` runs a Gremlin query directly against the configured graph, triggers a manual graph backup, and can initialize demo data in HugeGraph through a beta action. A background job also backs up the graph every day at 01:00, and a second background task keeps vertex-id embeddings up to date while the process runs.
+
+`Admin Tools` is password protected. Entering the configured `ADMIN_TOKEN` reveals the tail of `logs/llm-server.log`, which refreshes every 60 seconds, along with buttons to refresh or clear it. Access is refused while `ADMIN_TOKEN` is empty or still set to the placeholder `xxxx`.
+
+When `ENABLE_LOGIN=True`, the Web UI asks for basic credentials with the fixed user name `rag` and `USER_TOKEN` as the password, and the REST API requires `USER_TOKEN` as a Bearer token. The log endpoint additionally requires a separately configured, secure `ADMIN_TOKEN`.
 
 ![Keywords extracted in the RAG UI](/images/docs/hugegraph-ai/quick-start-04.png)
 
diff --git a/content/en/docs/quickstart/hugegraph-ai/rest-api.md b/content/en/docs/quickstart/hugegraph-ai/rest-api.md
index bff66982d..4d1f51ad9 100644
--- a/content/en/docs/quickstart/hugegraph-ai/rest-api.md
+++ b/content/en/docs/quickstart/hugegraph-ai/rest-api.md
@@ -13,6 +13,20 @@ python -m hugegraph_llm.demo.rag_demo.app \
   --port 8001
 ```
 
+All endpoints are `POST`:
+
+| Path | Success status | Purpose |
+|---|---|---|
+| `/rag` | 200 | Answer a question with the selected retrieval modes |
+| `/rag/graph` | 200 | Graph retrieval only, without a final answer |
+| `/graph/extract` | 200 | Extract vertices and edges from text |
+| `/text2gremlin` | 200 | Generate Gremlin from natural language |
+| `/config/graph` | 201 | Update the HugeGraph connection |
+| `/config/llm` | 201 | Update the language model |
+| `/config/embedding` | 201 | Update the embedding model |
+| `/config/rerank` | 201 | Update the reranker |
+| `/logs` | 200 | Stream the server log |
+
 ## Authentication
 
 Enable login in `.env`:
@@ -28,6 +42,8 @@ Requests then require a Bearer token:
 Authorization: Bearer replace-with-a-secret
 ```
 
+The same setting puts the Gradio UI behind basic authentication, with the fixed user name `rag` and `USER_TOKEN` as the password. A wrong token returns 401 with a `WWW-Authenticate: Bearer` header. When `ENABLE_LOGIN` is left at `False`, every endpoint is open.
+
 ## RAG
 
 ### `POST /rag`
@@ -67,7 +83,11 @@ The response contains only enabled answer fields:
 }
 ```
 
-Other optional parameters include `graph_ratio`, `rerank_method` (`bleu` or `reranker`), `near_neighbor_first`, `custom_priority_info`, and three custom prompt fields.
+Other optional parameters include `graph_ratio` (default `0.5`), `rerank_method` (`bleu` or `reranker`, default `bleu`), `near_neighbor_first` (default `false`), `custom_priority_info`, and the three custom prompt fields `answer_prompt`, `keywords_extract_prompt`, and `gremlin_prompt`. Omitting a prompt field uses the value from `config_prompt.yaml`.
+
+`gremlin_tmpl_num` selects how Text2Gremlin runs during graph retrieval. A negative value skips Text2Gremlin and goes straight to the predefined traversal, `0` generates Gremlin without examples, and a positive value retrieves that many examples from the example index.
+
+An empty or whitespace-only `query` returns 400.
 
 ### `POST /rag/graph`
 
@@ -84,7 +104,9 @@ curl -X POST http://localhost:8001/rag/graph \
   }'
 ```
 
-`graph_recall` in the response can contain `keywords`, `match_vids`, `gremlin`, `graph_result`, and `vertex_degree_list`. Set `get_vertex_only=true` to return immediately after vertex matching.
+`graph_recall` in the response can contain `query`, `keywords`, `match_vids`, `graph_result_flag`, `gremlin`, `graph_result`, and `vertex_degree_list`. Set `get_vertex_only=true` to return immediately after vertex matching; the endpoint then replaces `match_vids` with the full vertex details.
+
+An empty `query` returns 400, a type error in the request returns 400, and any other failure returns 500.
 
 ## Graph Extraction
 
@@ -117,9 +139,22 @@ curl -X POST http://localhost:8001/graph/extract \
   }'
 ```
 
-`texts` can be a string or an array of strings. `language` accepts `zh` or `en`; `split_type` accepts `document`, `paragraph`, or `sentence`.
+Request fields:
+
+| Field | Default | Notes |
+|---|---|---|
+| `texts` | required | A string or an array of strings; empty or blank entries are dropped and an empty result is rejected |
+| `schema` | required | Inline JSON object or string, or the name of an existing graph |
+| `example_prompt` | prompt YAML value | Extraction prompt header |
+| `extract_type` | `property_graph` | Only value currently accepted |
+| `language` | `zh` | `zh` or `en`, used for chunk splitting |
+| `split_type` | `document` | `document`, `paragraph`, or `sentence` |
+| `include_meta` | `false` | Adds `vertex_count`, `edge_count`, and `text_count` to `meta` |
+| `client_config` | none | Only allowed with a graph-name schema |
 
-When `schema` is an existing graph name, also pass `client_config`, and make `client_config.graph` match that name:
+An inline schema must be an object with `vertexlabels` and `edgelabels` lists. Every vertex label needs a non-empty `name` and a non-empty `properties` list; every edge label needs a non-empty `name`, `source_label`, and `target_label`. `propertykeys` is optional and must be a list when present.
+
+When `schema` is an existing graph name, also pass `client_config`, and make `client_config.graph` match that name. `client_config` here accepts only `graph`, `user`, `pwd`, and `gs`; unknown fields are rejected, and there is no `url` field:
 
 ```json
 {
@@ -134,7 +169,7 @@ When `schema` is an existing graph name, also pass `client_config`, and make `cl
 }
 ```
 
-A successful response always contains `status`, `result.vertices`, `result.edges`, `warnings`, and `meta`.
+A successful response always contains `status` (always `succeeded`), `result.vertices`, `result.edges`, `warnings`, and `meta`. `meta` stays empty unless `include_meta` is `true`.
 
 ## Text2Gremlin
 
@@ -158,7 +193,9 @@ curl -X POST http://localhost:8001/text2gremlin \
 - `template_execution_result`
 - `raw_execution_result`
 
-If omitted, only `template_gremlin` is returned by default. An empty array lets the implementation return all outputs. A custom `gremlin_prompt` must contain `{query}`, `{schema}`, `{example}`, and `{vertices}`.
+If omitted, only `template_gremlin` is returned by default. An empty array lets the implementation return all outputs. A custom `gremlin_prompt` must contain `{query}`, `{schema}`, `{example}`, and `{vertices}`; a missing placeholder fails request validation and names the placeholders that are absent.
+
+`example_num` defaults to `0`, which means no templates, and is clamped to the range 0 to 10. `client_config` overrides the HugeGraph connection for the request; the schema used for generation is the active graph name. An empty `query` returns 400, and a generation failure returns 500.
 
 ## Runtime Configuration
 
@@ -174,9 +211,11 @@ If omitted, only `template_gremlin` is returned by default. An empty array lets
 }
 ```
 
+`user` and `pwd` default to empty strings, and `gs` is optional.
+
 ### `POST /config/llm` and `POST /config/embedding`
 
-Both endpoints use the same request model. OpenAI or LiteLLM example:
+Both endpoints use the same request model. `/config/llm` sets `chat_llm_type`, `extract_llm_type`, and `text2gql_llm_type` to the same value; per-task types can only be set separately through `.env` or the Web UI. OpenAI or LiteLLM example:
 
 ```json
 {
@@ -213,7 +252,9 @@ Ollama requests still require the common fields; `api_key` and `api_base` can be
 
 `reranker_type` accepts `cohere` or `siliconflow`. Cohere also accepts `cohere_base_url`.
 
-These endpoints change the process's active configuration and may write values back to `.env`. `client_config` in `/rag`, `/rag/graph`, and `/text2gremlin` overrides the HugeGraph connection for one request. The current implementation still changes process-global settings temporarily, so do not issue long-running requests with different connections concurrently.
+All four configuration endpoints return 201 on success. They change the process's active configuration and may write values back to `.env`. `/config/llm`, `/config/embedding`, and `/config/rerank` restore the previous values if applying a change raises; `/config/graph` does not.
+
+`client_config` in `/rag`, `/rag/graph`, and `/text2gremlin` overrides the HugeGraph connection for one request, and only the fields actually present in the request are applied. The current implementation still changes process-global settings temporarily, so do not issue long-running requests with different connections concurrently.
 
 ## Logs
 
@@ -228,4 +269,8 @@ This endpoint requires `ADMIN_TOKEN` in `.env` to be changed to a secure value.
 }
 ```
 
-`log_file` must be a file name under `logs/` and cannot contain path separators.
+`log_file` defaults to `llm-server.log`, must be a file name under `logs/`, and cannot be absolute, contain path separators, or resolve to `.` or `..`. Invalid names return 400.
+
+An unset or placeholder `ADMIN_TOKEN` returns 403 before the token is even compared, and a wrong token returns a 403 body with the message `Invalid admin_token`.
+
+The successful response is a `text/plain` stream that first replays the last 125 lines of the file and then follows it, in the manner of `tail -f`.