@bndynet/ragbox 0.1.0 → 0.1.1

package/README.md

@@ -41,6 +41,11 @@ Before continuing, edit `ragbox.config.json`: add your model settings and point
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "./docs",
     "outputDir": "./.ragbox-index"
@@ -67,6 +72,13 @@ Use `start` when you want one foreground process for indexing, watching, and ser
 ragbox start
 ```
 
+For a quick detached local run, use `--background`:
+
+```bash
+ragbox start --background
+ragbox stop
+```
+
 You can still pass explicit paths when you want to override the config for one command:
 
 ```bash
@@ -122,7 +134,7 @@ The default setup needs:
 | Avoid repeating paths | use the `ragbox.config.json` written by `ragbox setup pageindex`, or run `ragbox init` |
 | Query several docs folders together | Configure `sources`, run `ragbox index --source <name>`, then `ragbox query --all-sources "..."` |
 | Debug answer quality | `ragbox query --trace --json "..."` or `ragbox trace query "..."` |
-| Check whether an index is usable | `ragbox status ./.ragbox-index` |
+| Check index and HTTP server status | `ragbox status ./.ragbox-index` |
 | Diagnose local setup issues | `ragbox doctor` |
 | Keep docs indexed while editing | `ragbox watch ./docs --output-dir ./.ragbox-index --jsonl` |
 | Run the full local service loop | `ragbox start --auth-token <token>` |
@@ -144,6 +156,11 @@ The default setup needs:
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "./docs",
     "outputDir": "./.ragbox-index"
@@ -158,7 +175,7 @@ ragbox init
 ragbox init --docs-dir ./content --output-dir ./.idx
 ```
 
-Relative paths are resolved from the config file directory. Server-side deployments can keep `baseUrl`, `model`, and `apiKey` together in a private `ragbox.config.json` or environment-specific config such as `ragbox.config.prod.json`. If a config file is committed or shared, keep `apiKey` in environment variables or a secret manager instead.
+Relative paths are resolved from the config file directory. Server-side deployments can keep `baseUrl`, `model`, `serve.host`, `serve.port`, and `apiKey` together in a private `ragbox.config.json` or environment-specific config such as `ragbox.config.prod.json`. If a config file is committed or shared, keep `apiKey` in environment variables or a secret manager instead.
 
 For one documentation source, use the top-level `docs` object. No `--source` flag is needed. If a project needs multiple named sources, use the optional `sources` map.
 
@@ -186,6 +203,11 @@ For multiple documentation directories, name each one under `sources`. This is u
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "sources": {
     "ragbox": {
       "rootDir": "./ragbox",
@@ -227,22 +249,23 @@ ragbox --config ./ragbox.config.prod.json query "How do I deploy?"
 
 ## Configuration
 
-For server-side use, keep the stable settings in `ragbox.config.json`: PageIndex paths, docs paths, LLM `baseUrl`, `model`, and, when the file is private, `apiKey`. Environment variables and CLI flags are still supported for overrides, secret managers, and one-off runs.
+For server-side use, keep the stable settings in `ragbox.config.json`: PageIndex paths, docs paths, serve host/port, LLM `baseUrl`, `model`, and, when the file is private, `apiKey`. Environment variables and CLI flags are still supported for overrides, secret managers, and one-off runs.
 
 Resolution order is command-line flags, then `ragbox.config.json`, then environment variables, then defaults.
 
-| Setting | Env | CLI flag | Used by | Default |
+| Setting | Env | Config / CLI | Used by | Default |
 | --- | --- | --- | --- | --- |
-| PageIndex script | `PAGEINDEX_CLI` | `ragbox setup pageindex` writes config | `index`, `watch` | required when indexing |
-| Python executable | `PAGEINDEX_PYTHON` | `--pageindex-python` | `index`, `watch` | `python3` |
-| Output directory | `RAGBOX_OUTPUT_DIR` | `--output-dir` | `index`, `watch` | `<folder>/.pageindex` |
-| Concurrency | `PAGEINDEX_CONCURRENCY` | `--concurrency` | `index`, `watch` | `1` |
+| PageIndex script | `PAGEINDEX_CLI` | `ragbox setup pageindex` writes config | `index`, `watch`, `start` | required when indexing |
+| Python executable | `PAGEINDEX_PYTHON` | `--pageindex-python` | `index`, `watch`, `start` | `python3` |
+| Output directory | `RAGBOX_OUTPUT_DIR` | `--output-dir` | `index`, `watch`, `start` | `<folder>/.pageindex` |
+| Concurrency | `PAGEINDEX_CONCURRENCY` | `--concurrency` | `index`, `watch`, `start` | `1` |
+| PageIndex runner | `PAGEINDEX_RUNNER` | `--pageindex-runner` | `index`, `watch`, `start` | `auto` |
 | API base URL | `OPENAI_BASE_URL` | `--base-url` | `index`, `watch`, `query` | `https://api.openai.com/v1` |
 | API key | `OPENAI_API_KEY` | `--api-key` | `index`, `watch`, `query` | required for query and usually PageIndex |
 | Model | `PAGEINDEX_MODEL`, `LLM_MODEL` | `--model` | `index`, `watch`, `query` | `gpt-4o-mini` |
-| Serve host | `RAGBOX_SERVE_HOST` | `--host` | `serve` | `127.0.0.1` |
-| Serve port | `RAGBOX_SERVE_PORT` | `--port` | `serve` | `8787` |
-| Serve token | `RAGBOX_SERVE_TOKEN` | `--auth-token` | `serve` | none |
+| Serve host | `RAGBOX_SERVE_HOST` | `serve.host`, `--host` | `start`, `serve`, `status`, `doctor` | `127.0.0.1` |
+| Serve port | `RAGBOX_SERVE_PORT` | `serve.port`, `--port` | `start`, `serve`, `status`, `doctor` | `8787` |
+| Serve token | `RAGBOX_SERVE_TOKEN` | `serve.authToken`, `--auth-token` | `start`, `serve` | none |
 | Watch debounce | `RAGBOX_WATCH_DEBOUNCE_MS` | `--debounce-ms` | `watch` | `500` |
 | Watch retry attempts | `RAGBOX_WATCH_RETRY_ATTEMPTS` | `--retry-attempts` | `watch` | `0` |
 | Watch retry delay | `RAGBOX_WATCH_RETRY_DELAY_MS` | `--retry-delay-ms` | `watch` | `1000` |
@@ -335,7 +358,7 @@ ragbox inspect --all-sources --json
 
 ### `ragbox status [target]`
 
-Checks whether an index is ready to query. This is useful in CI, deploy scripts, and smoke checks.
+Checks whether an index is ready to query and whether the local HTTP server health endpoint is reachable. The server probe uses `serve.host` / `serve.port`, then `RAGBOX_SERVE_HOST` / `RAGBOX_SERVE_PORT`, defaulting to `127.0.0.1:8787`.
 
 ```bash
 ragbox status ./.ragbox-index
@@ -345,7 +368,7 @@ ragbox status --json
 
 ### `ragbox doctor [target]`
 
-Checks the local setup: config, PageIndex CLI path, LLM settings, API key presence, and index validity. It does not call the network.
+Checks the local setup: config, PageIndex CLI path, LLM settings, API key presence, index validity, and local HTTP server health.
 
 ```bash
 ragbox doctor
@@ -404,23 +427,40 @@ Fatal query errors include the stage that failed, for example `Query failed duri
 
 ### `ragbox start [folder]`
 
-Runs the complete local service loop: index first, watch for future changes, and serve the HTTP query API.
+Runs the complete local service loop: start watch, serve the HTTP query API, and keep indexes fresh.
 
 ```bash
 ragbox start
 ragbox start --auth-token dev-token
 ragbox start --host 127.0.0.1 --port 8787 --jsonl
+ragbox start --background
 ragbox start --source ragbox
 ragbox start --all-sources
 ragbox start ./docs --output-dir ./.ragbox-index
 ```
 
-Use `start` after `ragbox setup pageindex` when you want one foreground process for local development, an internal service, or a container. It waits for the initial index run before starting HTTP `serve`, then reloads the serve index snapshot after successful watch updates.
+Use `start` after `ragbox setup pageindex` when you want one foreground process for local development, an internal service, or a container. HTTP `serve` starts as soon as the watchers are registered, so `/` and `/health` respond while the initial index is still running. `/health` returns 503 until the first index snapshot is query-ready, and `start` reloads the serve index snapshot after the initial run and every successful watch update.
+
+Pass `--background` to detach `start` from the current terminal. Background runs write stdout/stderr to `./ragbox.log` and the process id to `./ragbox.pid` by default. Override those paths with `--log-file <path>` and `--pid-file <path>`, or pass `--no-pid-file` when you do not want a pid file.
+
+Use `ragbox stop` from the same working directory to stop the background process recorded in `./ragbox.pid`. Pass `--pid-file <path>` if you started with a custom pid file.
 
 With multiple configured sources, `ragbox start` starts all sources by default. Use `--source ragbox,icharts` to limit the running sources, or `--all-sources` to make the global behavior explicit.
 
 `start` does not create or edit `ragbox.config.json`; run `ragbox setup pageindex` for the default local setup, or `ragbox init` when you want to manage PageIndex yourself.
 
+### `ragbox stop`
+
+Stops a `ragbox start --background` process by reading `./ragbox.pid` in the current working directory.
+
+```bash
+ragbox stop
+ragbox stop --pid-file /var/run/ragbox.pid
+ragbox stop --force
+```
+
+By default, `stop` sends `SIGTERM`, waits for the process to exit, and removes the pid file. Use `--force` to send `SIGKILL`.
+
 ### `ragbox serve [target]`
 
 Starts a foreground HTTP server for external systems. Index first with `ragbox index`, or keep the index fresh with `ragbox watch`.
@@ -451,6 +491,7 @@ Single-index requests:
 ```bash
 curl http://127.0.0.1:8787/
 curl http://127.0.0.1:8787/health
+ragbox status ./.ragbox-index
 
 curl -H "Authorization: Bearer dev-token" \
   http://127.0.0.1:8787/indexes
@@ -479,7 +520,7 @@ curl -X POST http://localhost:8787/query \
 curl -X POST http://localhost:8787/reload
 ```
 
-`serve` is designed for local services, internal services, container sidecars, and docs backends. Do not expose `.ragbox-index` as static files, because it can contain source document text. Browser widgets should call your own backend first; the backend can enforce user auth, rate limits, and audit logging before forwarding requests to `ragbox serve`. In production, bind to localhost or an internal network address and configure `--auth-token` or `RAGBOX_SERVE_TOKEN`.
+`serve` is designed for local services, internal services, container sidecars, and docs backends. Do not expose `.ragbox-index` as static files, because it can contain source document text. Browser widgets should call your own backend first; the backend can enforce user auth, rate limits, and audit logging before forwarding requests to `ragbox serve`. In production, bind to localhost or an internal network address and configure `serve.authToken`, `--auth-token`, or `RAGBOX_SERVE_TOKEN`.
 
 ### `ragbox watch <folder>`
 
@@ -550,8 +591,9 @@ Common patterns:
 - Store the output directory outside the source tree, for example `/var/lib/ragbox/docs-index`.
 - Mount or copy the completed output directory to every app replica that needs querying.
 - Keep API keys in a private server config, environment variables, or your secret manager. Do not commit real keys.
-- Use `RAGBOX_SERVE_TOKEN` or `--auth-token` when `serve` is reachable beyond localhost.
+- Use `serve.authToken`, `RAGBOX_SERVE_TOKEN`, or `--auth-token` when `serve` is reachable beyond localhost. Treat the token like a secret if the config is committed or shared.
 - Start with `--concurrency 1`; raise it only after checking PageIndex and API rate limits.
+- Keep the default `--pageindex-runner auto` for Markdown/MDX indexes; it uses warm PageIndex workers when possible and falls back to the single-file CLI when needed.
 
 Example private server config:
 
@@ -560,13 +602,19 @@ Example private server config:
   "version": 1,
   "pageIndex": {
     "cli": "/opt/PageIndex/run_pageindex.py",
-    "python": "/opt/pageindex-venv/bin/python"
+    "python": "/opt/pageindex-venv/bin/python",
+    "runner": "auto"
   },
   "llm": {
     "baseUrl": "https://api.openai.com/v1",
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "/srv/app/docs",
     "outputDir": "/var/lib/ragbox/docs-index"
@@ -581,14 +629,19 @@ ragbox --config ./ragbox.config.prod.json query "How do I configure authenticati
 
 ### Run In The Background
 
-`ragbox start` intentionally runs in the foreground. For a server, run it under a process supervisor so it survives terminal closes, SSH disconnects, and crashes.
+For quick local or internal testing, `ragbox start --background` detaches the same start loop from the current terminal:
 
-For quick testing, `nohup` is enough:
+```bash
+ragbox --config ./ragbox.config.prod.json start \
+  --background
+```
 
 ```bash
-nohup ragbox --config ./ragbox.config.prod.json start > ragbox.log 2>&1 &
+ragbox stop
 ```
 
+For a long-running server, prefer a process supervisor so crashes are restarted and startup ordering is explicit.
+
 For Linux servers, prefer `systemd`:
 
 ```ini

package/README.zh-CN.md

@@ -39,6 +39,11 @@ ragbox setup pageindex
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "./docs",
     "outputDir": "./.ragbox-index"
@@ -65,6 +70,13 @@ ragbox watch --jsonl
 ragbox start
 ```
 
+如果只是想临时脱离当前终端运行，可以加 `--background`：
+
+```bash
+ragbox start --background
+ragbox stop
+```
+
 需要临时覆盖配置时，仍然可以显式传路径：
 
 ```bash
@@ -120,7 +132,7 @@ ragbox query ./.ragbox-index "怎么配置认证？" \
 | 不想每次重复路径 | 使用 `ragbox setup pageindex` 写入的 `ragbox.config.json`，或运行 `ragbox init` |
 | 多个文档目录一起查询 | 配置 `sources`，分别跑 `ragbox index --source <name>`，再用 `ragbox query --all-sources "..."` |
 | 调试回答质量 | `ragbox query --trace --json "..."` 或 `ragbox trace query "..."` |
-| 检查索引是否可用 | `ragbox status ./.ragbox-index` |
+| 检查索引和 HTTP 服务状态 | `ragbox status ./.ragbox-index` |
 | 诊断本地配置问题 | `ragbox doctor` |
 | 编辑文档时自动更新索引 | `ragbox watch ./docs --output-dir ./.ragbox-index --jsonl` |
 | 跑完整本地服务流程 | `ragbox start --auth-token <token>` |
@@ -142,6 +154,11 @@ ragbox query ./.ragbox-index "怎么配置认证？" \
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "./docs",
     "outputDir": "./.ragbox-index"
@@ -156,7 +173,7 @@ ragbox init
 ragbox init --docs-dir ./content --output-dir ./.idx
 ```
 
-配置文件中的相对路径会按配置文件所在目录解析。Server 端部署可以把 `baseUrl`、`model` 和 `apiKey` 一起放在私有 `ragbox.config.json`，或按环境拆成 `ragbox.config.prod.json`。如果配置文件会提交到仓库或共享给他人，就不要写真实 `apiKey`，改用环境变量或 secret manager。
+配置文件中的相对路径会按配置文件所在目录解析。Server 端部署可以把 `baseUrl`、`model`、`serve.host`、`serve.port` 和 `apiKey` 一起放在私有 `ragbox.config.json`，或按环境拆成 `ragbox.config.prod.json`。如果配置文件会提交到仓库或共享给他人，就不要写真实 `apiKey`，改用环境变量或 secret manager。
 
 只有一个文档源时，用顶层 `docs` 就够了，不需要传 `--source`。项目里确实有多个命名文档源时，再使用可选的 `sources` 映射。
 
@@ -184,6 +201,11 @@ ragbox --config ./ragbox.config.json index
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "sources": {
     "ragbox": {
       "rootDir": "./ragbox",
@@ -225,22 +247,23 @@ ragbox --config ./ragbox.config.prod.json query "怎么部署？"
 
 ## 配置
 
-Server 端使用时，建议把稳定配置集中写在 `ragbox.config.json`：PageIndex 路径、docs 路径、LLM `baseUrl`、`model`，以及私有配置文件里的 `apiKey`。环境变量和命令参数仍然支持，适合覆盖配置、接 secret manager，或临时运行。
+Server 端使用时，建议把稳定配置集中写在 `ragbox.config.json`：PageIndex 路径、docs 路径、serve host/port、LLM `baseUrl`、`model`，以及私有配置文件里的 `apiKey`。环境变量和命令参数仍然支持，适合覆盖配置、接 secret manager，或临时运行。
 
 配置解析优先级为：命令行参数、`ragbox.config.json`、环境变量、默认值。
 
-| 配置 | 环境变量 | 命令参数 | 用于 | 默认值 |
+| 配置 | 环境变量 | 配置 / 命令参数 | 用于 | 默认值 |
 | --- | --- | --- | --- | --- |
-| PageIndex 脚本 | `PAGEINDEX_CLI` | `ragbox setup pageindex` 写入配置 | `index`, `watch` | 索引时必填 |
-| Python 可执行文件 | `PAGEINDEX_PYTHON` | `--pageindex-python` | `index`, `watch` | `python3` |
-| 输出目录 | `RAGBOX_OUTPUT_DIR` | `--output-dir` | `index`, `watch` | `<folder>/.pageindex` |
-| 并发数 | `PAGEINDEX_CONCURRENCY` | `--concurrency` | `index`, `watch` | `1` |
+| PageIndex 脚本 | `PAGEINDEX_CLI` | `ragbox setup pageindex` 写入配置 | `index`, `watch`, `start` | 索引时必填 |
+| Python 可执行文件 | `PAGEINDEX_PYTHON` | `--pageindex-python` | `index`, `watch`, `start` | `python3` |
+| 输出目录 | `RAGBOX_OUTPUT_DIR` | `--output-dir` | `index`, `watch`, `start` | `<folder>/.pageindex` |
+| 并发数 | `PAGEINDEX_CONCURRENCY` | `--concurrency` | `index`, `watch`, `start` | `1` |
+| PageIndex runner | `PAGEINDEX_RUNNER` | `--pageindex-runner` | `index`, `watch`, `start` | `auto` |
 | API Base URL | `OPENAI_BASE_URL` | `--base-url` | `index`, `watch`, `query` | `https://api.openai.com/v1` |
 | API Key | `OPENAI_API_KEY` | `--api-key` | `index`, `watch`, `query` | query 必填，PageIndex 通常也需要 |
 | 模型 | `PAGEINDEX_MODEL`, `LLM_MODEL` | `--model` | `index`, `watch`, `query` | `gpt-4o-mini` |
-| Serve host | `RAGBOX_SERVE_HOST` | `--host` | `serve` | `127.0.0.1` |
-| Serve port | `RAGBOX_SERVE_PORT` | `--port` | `serve` | `8787` |
-| Serve token | `RAGBOX_SERVE_TOKEN` | `--auth-token` | `serve` | 无 |
+| Serve host | `RAGBOX_SERVE_HOST` | `serve.host`, `--host` | `start`, `serve`, `status`, `doctor` | `127.0.0.1` |
+| Serve port | `RAGBOX_SERVE_PORT` | `serve.port`, `--port` | `start`, `serve`, `status`, `doctor` | `8787` |
+| Serve token | `RAGBOX_SERVE_TOKEN` | `serve.authToken`, `--auth-token` | `start`, `serve` | 无 |
 | Watch debounce | `RAGBOX_WATCH_DEBOUNCE_MS` | `--debounce-ms` | `watch` | `500` |
 | Watch 重试次数 | `RAGBOX_WATCH_RETRY_ATTEMPTS` | `--retry-attempts` | `watch` | `0` |
 | Watch 重试延迟 | `RAGBOX_WATCH_RETRY_DELAY_MS` | `--retry-delay-ms` | `watch` | `1000` |
@@ -333,7 +356,7 @@ ragbox inspect --all-sources --json
 
 ### `ragbox status [target]`
 
-检查索引是否已经可以 query。适合 CI、部署脚本和 smoke check。
+检查索引是否已经可以 query，并探测本机 HTTP 服务的 `/health` 是否可达。服务探测会先使用 `serve.host` / `serve.port`，再使用 `RAGBOX_SERVE_HOST` / `RAGBOX_SERVE_PORT`，默认是 `127.0.0.1:8787`。
 
 ```bash
 ragbox status ./.ragbox-index
@@ -343,7 +366,7 @@ ragbox status --json
 
 ### `ragbox doctor [target]`
 
-检查本地配置、PageIndex CLI 路径、LLM 设置、API key 是否存在，以及索引是否有效。这个命令不会发起网络请求。
+检查本地配置、PageIndex CLI 路径、LLM 设置、API key 是否存在、索引是否有效，以及本机 ragbox HTTP 服务是否健康。
 
 ```bash
 ragbox doctor
@@ -409,23 +432,40 @@ indexes/
 
 ### `ragbox start [folder]`
 
-运行完整本地服务流程：先生成初始索引，再持续 watch 文档变化，同时启动 HTTP query API。
+运行完整本地服务流程：启动 watch、提供 HTTP query API，并持续刷新索引。
 
 ```bash
 ragbox start
 ragbox start --auth-token dev-token
 ragbox start --host 127.0.0.1 --port 8787 --jsonl
+ragbox start --background
 ragbox start --source ragbox
 ragbox start --all-sources
 ragbox start ./docs --output-dir ./.ragbox-index
 ```
 
-当你已经通过 `ragbox setup pageindex` 准备好默认本地配置，并希望用一个前台进程跑本地开发、内网服务或容器时，优先使用 `start`。它会等初始索引完成后再启动 HTTP `serve`，之后每次 watch 成功更新索引，都会刷新 serve 里的索引快照。
+当你已经通过 `ragbox setup pageindex` 准备好默认本地配置，并希望用一个前台进程跑本地开发、内网服务或容器时，优先使用 `start`。HTTP `serve` 会在 watcher 注册后立即启动，所以初始索引还在运行时，`/` 和 `/health` 已经可以响应。`/health` 在首个索引快照可查询前返回 503；初始索引完成后，以及之后每次 watch 成功更新索引，都会刷新 serve 里的索引快照。
+
+传入 `--background` 时，`start` 会脱离当前终端后台运行。后台进程默认把 stdout/stderr 写到 `./ragbox.log`，并把 PID 写到 `./ragbox.pid`。可以用 `--log-file <path>` 和 `--pid-file <path>` 覆盖路径；如果不想写 PID 文件，可以传 `--no-pid-file`。
+
+在同一个工作目录运行 `ragbox stop`，会读取 `./ragbox.pid` 并停止对应后台进程。如果启动时用了自定义 pid 文件，停止时也传同一个 `--pid-file <path>`。
 
 配置了多个 source 时，`ragbox start` 默认启动全部 source。可以用 `--source ragbox,icharts` 限定范围，也可以用 `--all-sources` 显式表达全局启动。
 
 `start` 不会创建或修改 `ragbox.config.json`；默认本地 setup 先运行 `ragbox setup pageindex`，如果你想自己管理 PageIndex，再用 `ragbox init` 手动配置。
 
+### `ragbox stop`
+
+读取当前工作目录的 `./ragbox.pid`，停止由 `ragbox start --background` 启动的后台进程。
+
+```bash
+ragbox stop
+ragbox stop --pid-file /var/run/ragbox.pid
+ragbox stop --force
+```
+
+默认发送 `SIGTERM`，等待进程退出后删除 pid 文件。传 `--force` 时发送 `SIGKILL`。
+
 ### `ragbox serve [target]`
 
 启动一个前台 HTTP 服务，供外部系统通过 REST API 查询文档。使用前先通过 `ragbox index` 生成索引，或者用 `ragbox watch` 持续刷新索引。
@@ -456,6 +496,7 @@ Public HTTP contract：
 ```bash
 curl http://127.0.0.1:8787/
 curl http://127.0.0.1:8787/health
+ragbox status ./.ragbox-index
 
 curl -H "Authorization: Bearer dev-token" \
   http://127.0.0.1:8787/indexes
@@ -484,7 +525,7 @@ curl -X POST http://localhost:8787/query \
 curl -X POST http://localhost:8787/reload
 ```
 
-`serve` 首版面向本地服务、内网服务、container sidecar 和 docs backend。不要把 `.ragbox-index` 作为静态目录直接暴露，因为里面可能包含源文档正文。浏览器 widget 不应该直接携带 ragbox token；建议先请求自己的 backend，由 backend 负责用户登录、限流和审计，再转发给 `ragbox serve`。生产环境建议绑定 localhost 或内网地址，并配置 `--auth-token` 或 `RAGBOX_SERVE_TOKEN`。
+`serve` 首版面向本地服务、内网服务、container sidecar 和 docs backend。不要把 `.ragbox-index` 作为静态目录直接暴露，因为里面可能包含源文档正文。浏览器 widget 不应该直接携带 ragbox token；建议先请求自己的 backend，由 backend 负责用户登录、限流和审计，再转发给 `ragbox serve`。生产环境建议绑定 localhost 或内网地址，并配置 `serve.authToken`、`--auth-token` 或 `RAGBOX_SERVE_TOKEN`。
 
 ### `ragbox watch <folder>`
 
@@ -558,8 +599,9 @@ ragbox query ./.ragbox-index "..."
 - 把输出目录放在源码目录外，例如 `/var/lib/ragbox/docs-index`
 - 多副本应用需要读取同一份完整索引，可以挂载只读卷或随部署产物分发
 - API key 可以放私有 server 配置、环境变量或 secret manager；不要提交真实 key
-- 当 `serve` 不只绑定 localhost 时，使用 `RAGBOX_SERVE_TOKEN` 或 `--auth-token`
+- 当 `serve` 不只绑定 localhost 时，使用 `serve.authToken`、`RAGBOX_SERVE_TOKEN` 或 `--auth-token`；如果配置会提交或共享，要把 token 当作密钥处理
 - 先用 `--concurrency 1`，确认 PageIndex 和模型服务限流后再提高
+- Markdown/MDX 索引保持默认 `--pageindex-runner auto`；它会优先使用 PageIndex 热 worker，无法使用时自动回退到单文件 CLI
 - 如果要求零停机更新，可以先索引到 staging 目录，成功后再切换读目录
 
 私有 server 配置示例：
@@ -569,13 +611,19 @@ ragbox query ./.ragbox-index "..."
   "version": 1,
   "pageIndex": {
     "cli": "/opt/PageIndex/run_pageindex.py",
-    "python": "/opt/pageindex-venv/bin/python"
+    "python": "/opt/pageindex-venv/bin/python",
+    "runner": "auto"
   },
   "llm": {
     "baseUrl": "https://api.openai.com/v1",
     "model": "gpt-4o-mini",
     "apiKey": "sk-..."
   },
+  "serve": {
+    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
+    "host": "127.0.0.1",
+    "port": 8787
+  },
   "docs": {
     "rootDir": "/srv/app/docs",
     "outputDir": "/var/lib/ragbox/docs-index"
@@ -590,14 +638,19 @@ ragbox --config ./ragbox.config.prod.json query "怎么配置认证？"
 
 ### 后台运行
 
-`ragbox start` 有意以前台进程运行。Server 部署时，建议交给进程管理器托管，这样关闭终端、SSH 断开或进程崩溃后都能继续运行或自动重启。
+本地或内网临时测试时，可以用 `ragbox start --background` 让同一个 start 流程脱离当前终端：
 
-临时测试可以用 `nohup`：
+```bash
+ragbox --config ./ragbox.config.prod.json start \
+  --background
+```
 
 ```bash
-nohup ragbox --config ./ragbox.config.prod.json start > ragbox.log 2>&1 &
+ragbox stop
 ```
 
+长期运行的 server 仍然建议交给进程管理器托管，这样进程崩溃后可以自动重启，启动顺序也更清晰。
+
 Linux server 推荐用 `systemd`：
 
 ```ini