diff --git a/CHANGELOG.md b/CHANGELOG.md
index a81a598..32b72ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@ All notable changes to this project will be documented in this file.
 - Fix `doctor` reporting `configuration.ready`/`credentials_ready: true` while `embedding.base_url`/`model` were still the install template's placeholder values.
 - Fix the CLI entrypoint always exiting `0`: `main()`'s return value (notably `doctor`'s pass/fail code) was never applied to `process.exitCode`, so scripted checks against the exit code always saw success.
 - Warn when `chilon-recall qoder` is run from an `npx` temporary cache: the generated `.qoder/mcp.json` embeds that ephemeral path, which breaks silently on the next cache clear or version bump.
+- Fix `chilon-recall key` hanging forever when the pasted key contained a newline: raw-mode stdin delivers a paste as one multi-character chunk, which was treated as a single unknown keystroke. Input is now processed per character, so a multi-line paste submits at its first line break and the rest is discarded.
+- Fix a header-unsafe key (for example one with an embedded newline) leaking in plaintext inside the error message and being misreported as a network failure. The key is now validated before any request, and redacted from any error that still surfaces.
+- Fix model recommendation suggesting a reranker (e.g. a `bge-reranker-*` model) as the embedding model; rerank matches are excluded from the embedding candidates first.
+- Fix a `base_url` that already ends with the endpoint suffix (e.g. `.../embeddings`) getting the suffix appended twice, in both the Python engine and the `key` model lookup.
+- Configuration validation errors (a typo'd key, a wrong type) are now reported as a readable sentence in MCP tool errors and `doctor`, instead of a raw JSON dump of the validation issues.
+- The first-run engine setup (virtual environment + `pip install`) now reports its progress and the underlying process output on stderr instead of running silently for up to a minute; stdout still carries only the single JSON result.
+- Document that the `key` wizard's `setx` / `>> ~/.bashrc` commands store the key in plaintext (registry / shell profile) if run, and that all printed commands remain in shell history and scrollback.
 
 ## [0.1.3] - 2026-09-18
 
diff --git a/README.md b/README.md
index c23822d..338ccdd 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,15 @@ $env:RAG_API_KEY = "your-provider-key"
 npx -y chilon-recall@0.1.4 doctor
 ```
 
-Not sure which model to pick? `chilon-recall key --base-url https://api.example.com/v1` prompts for the key once (hidden input), calls the provider's own `/models` endpoint to suggest an embedding and reranker model, and prints ready-to-run `$env:`/`setx`/`export` commands with the key already filled in. The key is used for that one request only — it is never written to a file.
+`doctor` is an offline check: it catches the template placeholders and a missing key, but it never contacts your provider, so a real-looking `base_url` with a typo, or a wrong key, still passes. Then confirm them online with the key wizard:
+
+```powershell
+npx -y chilon-recall@0.1.4 key --base-url https://your-provider.example/v1
+```
+
+It prompts for the key once (hidden input), calls the provider's own `/models` endpoint — a mistyped URL fails here, and so does a key the provider rejects — suggests an embedding and reranker model, and prints ready-to-run `$env:`/`setx`/`export` commands with the key already filled in. chilon-recall uses the key for that one request only and never writes it to a file; the printed `setx` / `>> ~/.bashrc` commands do store it in plaintext if you run them.
+
+> **Paste the key as a single line.** The prompt submits at the first line break it receives, including one inside the pasted text: anything after it is discarded. If your clipboard holds more than the key (for example a copied `KEY=...` block), copy the key alone.
 
 ### 3. Connect one client
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index ff9aadf..c5504b1 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -58,7 +58,15 @@ $env:RAG_API_KEY = "your-provider-key"
 npx -y chilon-recall@0.1.4 doctor
 ```
 
-不确定该填哪个 model？`chilon-recall key --base-url https://api.example.com/v1` 会提示你粘贴一次 key（终端隐藏输入），调用该 provider 自己的 `/models` 接口，推荐一个 embedding 和一个 reranker 模型，并打印出已经填好真实 key、可直接复制运行的 `$env:` / `setx` / `export` 命令。这个 key 只用于这一次请求，绝不会被写入任何文件。
+`doctor` 是离线检查：它能发现模板占位值和缺失的 key，但不会联系你的 provider，所以一个"看起来真实但拼错了一个字母"的 `base_url`，或者一个错误的 key，仍然会通过。接下来用 key 向导做一次在线确认：
+
+```powershell
+npx -y chilon-recall@0.1.4 key --base-url https://your-provider.example/v1
+```
+
+它会提示你粘贴一次 key（终端隐藏输入），调用该 provider 自己的 `/models` 接口——URL 拼错会在这一步直接报错，被 provider 拒绝的 key 也一样——推荐一个 embedding 和一个 reranker 模型，并打印出已经填好真实 key、可直接复制运行的 `$env:` / `setx` / `export` 命令。chilon-recall 只把这个 key 用于这一次请求，绝不写入任何文件；但打印出的 `setx` / `>> ~/.bashrc` 命令如果你执行了，会把 key 以明文存进注册表或 shell 配置文件。
+
+> **请把 key 作为单行粘贴。** 输入框在收到第一个换行时就会提交，粘贴内容中间的换行也算：换行之后的内容会被丢弃。如果剪贴板里不止 key 本身（例如复制了一段 `KEY=...` 配置），请只复制 key。
 
 ### 3. 连接一个客户端