@researai/deepscientist 1.5.16 → 1.6.0

package/docs/en/00_QUICK_START.md

@@ -36,9 +36,11 @@ See the full notice here:
 Prepare these first:
 
 - Node.js `>=18.18` and npm `>=9`; install them from the official download page: https://nodejs.org/en/download
-- one working Codex path:
-  - default OpenAI login path: `codex --login` (or `codex`)
-  - provider-backed path: one working Codex profile such as `minimax`, `glm`, `ark`, or `bailian`
+- one working runner path:
+  - `codex` should already work as `codex` in your shell
+  - `claude` should already work as `claude` in your shell
+  - `kimi` should already work as `kimi` in your shell
+  - `opencode` should already work as `opencode` in your shell
 - a model or API credential if your project needs external inference
 - GPU or server access if your experiments are compute-heavy
 - if you plan to run DeepScientist for real work, prepare Docker or another isolated environment and a dedicated non-root user
@@ -47,6 +49,7 @@ Prepare these first:
 
 If you are still choosing a coding plan or subscription, these are practical starting points:
 
+- If you just want one simple starting recommendation, start with the Codex + OpenAI login path. If you want Gemini, do not just put a Gemini model name into DeepScientist; first make OpenCode + Gemini work with [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md).
 - ChatGPT pricing: https://openai.com/chatgpt/pricing/
 - ChatGPT Plus help: https://help.openai.com/en/articles/6950777-what-is-chatgpt-plus%3F.eps
 - MiniMax Coding Plan: https://platform.minimaxi.com/docs/guides/pricing-codingplan
@@ -54,9 +57,16 @@ If you are still choosing a coding plan or subscription, these are practical sta
 - Alibaba Cloud Bailian Coding Plan: https://help.aliyun.com/zh/model-studio/coding-plan
 - Volcengine Ark Coding Plan: https://www.volcengine.com/docs/82379/1925115?lang=zh
 
-If you plan to use a provider-backed Codex profile instead of the default OpenAI login flow, read this next:
+If you plan to use Qwen through Alibaba Bailian, use the Bailian **Coding Plan** endpoint only. The generic Bailian or DashScope Qwen API is not supported in the Codex-backed DeepScientist path.
+
+If you want the safest recommendation, start with Codex first.
+
+Use the matching runner setup doc before your first real launch:
 
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
+- [24 Claude Code Setup](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+- [27 Kimi Code Setup](./27_KIMI_CODE_PROVIDER_SETUP.md)
+- [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md)
 
 ## 1. Install Node.js and DeepScientist
 
@@ -79,7 +89,19 @@ npm install -g @researai/deepscientist
 
 This installs the `ds` command globally.
 
-DeepScientist depends on a working Codex CLI. It prefers the `codex` already available on your machine and only falls back to the bundled npm dependency when no local Codex path is available. If `codex` is still missing afterward, repair it explicitly:
+DeepScientist ships four built-in runner paths:
+
+- `codex`
+- `claude`
+- `kimi`
+- `opencode`
+
+Important installation detail:
+
+- DeepScientist prefers runner CLIs already available on your machine and only falls back to bundled npm helper copies when a compatible package-local binary is present.
+- DeepScientist does not auto-authenticate Claude Code, Kimi Code, or OpenCode for you. For those paths, make the CLI work first, then let DeepScientist reuse it.
+
+If `codex` is still missing afterward, repair it explicitly:
 
 ```bash
 npm install -g @openai/codex
@@ -89,7 +111,7 @@ If you want the most reliable path, verify the command immediately:
 
 ```bash
 which codex
-codex --login
+codex login
 ```
 
 If `which codex` prints nothing, the issue is usually the npm global bin path rather than DeepScientist itself. Fix the shell PATH first, then rerun `npm install -g @openai/codex`.
@@ -102,19 +124,19 @@ ds latex install-runtime
 
 This installs a lightweight TinyTeX runtime for local paper compilation.
 
-## 2. Finish Codex Setup Before The First `ds`
+## 2. Finish Your Chosen Runner Before The First `ds`
 
-Choose one of these two paths.
+If you are undecided, choose `codex` first.
 
-### 2.1 Default OpenAI login path
+### 2.1 Codex: default OpenAI login path
 
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run:
+If you prefer the interactive first-run flow, run:
 
 ```bash
 codex
@@ -128,9 +150,9 @@ Then verify:
 ds doctor
 ```
 
-### 2.2 Provider-backed Codex profile path
+### 2.2 Codex: provider-backed profile path
 
-If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another provider-backed path, verify that profile first in a terminal:
+If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian Coding Plan, or another provider-backed path, verify that profile first in a terminal:
 
 ```bash
 codex --profile m27
@@ -174,6 +196,72 @@ MiniMax note:
 - if you also want plain terminal `codex --profile <name>` to work directly, add `model_provider = "minimax"` and the matching top-level model such as `MiniMax-M2.7` or `MiniMax-M2.5` to `~/.codex/config.toml`
 - DeepScientist automatically downgrades `xhigh` to `high` when it detects an older Codex CLI that does not support `xhigh`
 
+### 2.3 Claude Code path
+
+Use this when `claude` already works directly in your terminal.
+
+The shortest validation path is:
+
+```bash
+claude --version
+claude -p "Reply with exactly HELLO." --output-format json --tools ""
+ds doctor --runner claude
+```
+
+Then launch DeepScientist through Claude Code:
+
+```bash
+ds --runner claude
+```
+
+If you want the full setup order, config mapping, and gateway notes, continue with:
+
+- [24 Claude Code Setup](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+
+### 2.4 OpenCode path
+
+Use this when `opencode` already works directly in your terminal.
+
+The shortest validation path is:
+
+```bash
+opencode --version
+opencode run --format json --pure "Reply with exactly HELLO"
+ds doctor --runner opencode
+```
+
+Then launch DeepScientist through OpenCode:
+
+```bash
+ds --runner opencode
+```
+
+If you want the full setup order, config mapping, and provider notes, continue with:
+
+- [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md)
+
+### 2.5 Kimi Code path
+
+Use this when `kimi` already works directly in your terminal.
+
+The shortest validation path is:
+
+```bash
+kimi --version
+kimi login
+ds doctor --runner kimi
+```
+
+Then launch DeepScientist through Kimi:
+
+```bash
+ds --runner kimi
+```
+
+If you want the full setup order, config mapping, and a clearer Settings-first path, continue with:
+
+- [27 Kimi Code Setup](./27_KIMI_CODE_PROVIDER_SETUP.md)
+
 ## 3. Start the Local Runtime
 
 Run:
@@ -184,6 +272,35 @@ ds
 
 This starts the local daemon and the web workspace.
 
+If you want this launch to use a non-default runner, add `--runner`:
+
+```bash
+ds --runner claude
+ds --runner opencode
+```
+
+If the target runner passes `ds doctor` and you want to keep using it, switch `config.default_runner` later in `~/DeepScientist/config/config.yaml` or in the Settings page.
+
+### After the first successful launch, use Settings first
+
+Once the browser is open, the easiest next step is usually not raw YAML. It is the `Settings` page.
+
+A simple rule that works well for first-time users:
+
+1. open `Settings`
+2. go to `Runtime` if you want to change the language, web port, home path, or Git / logging defaults
+3. go to `Models` if you want to switch the default runner or configure Claude / Kimi / OpenCode after launch
+4. go to `Connectors` if you want to bind Telegram, Discord, Slack, Feishu, WhatsApp, QQ, WeChat, or Lingzhu
+5. go to `DeepXiv` if you want literature search
+
+Use raw YAML only when you are:
+
+- headless
+- automating setup
+- changing many fields at once
+
+![Models settings page](../images/settings/settings-runners-en.png)
+
 Again, strongly recommended:
 
 - prefer Docker or another isolated environment
@@ -204,6 +321,19 @@ ds --here
 
 This is equivalent to `ds --home "$PWD/DeepScientist"`.
 
+Important:  
+* if you start DeepScientist with `ds --here`, later `ds --status`, `ds --stop`, and `ds --restart` run in the same directory will now usually prefer that local `./DeepScientist` home automatically  
+* if you start with an explicit `--home <path>`, or you keep multiple DeepScientist homes on one machine, it is still safest to pass the same home explicitly for later management commands  
+* using the same `DEEPSCIENTIST_HOME` or `DS_HOME` environment variable for those commands is also fine
+* when multiple non-default homes exist, explicit `--home` remains the most reliable choice  
+
+For example, when using a non-default home, run:  
+
+```bash
+ds --status --home /path/to/DeepScientist  
+ds --stop --home /path/to/DeepScientist
+```
+
 If you want another port, run:
 
 ```bash
@@ -255,7 +385,7 @@ The example task is:
 - reproduce the official Mandela-Effect baseline
 - keep the original task setting and evaluation protocol
 - study how to improve truth-preserving collaboration under mixed correct and incorrect social signals
-- use two local inference endpoints to keep throughput high
+- in this reference example, use two local inference endpoints to keep throughput high
 
 Click `Start Research` / `Start Experiment`, then choose `Autonomous Mode` to follow the flow below.
 
@@ -314,12 +444,14 @@ These fields tell DeepScientist where the baseline comes from and what prior wor
 
 Paste this into `Runtime constraints`:
 
+This snippet is a tutorial reference only, not a DeepScientist default endpoint setup. Replace the endpoints, API key, and model with your real runtime before you paste it.
+
 ```text
 - Keep the task definition and evaluation protocol aligned with the official baseline unless a change is explicitly justified.
-- Use two OpenAI-compatible local inference endpoints for throughput:
-  - `http://127.0.0.1:8004/v1`
-  - `http://127.0.0.1:8008/v1`
-- Use API key `1234` and model `/model/gpt-oss-120b` on both endpoints.
+- Use two OpenAI-compatible inference endpoints for throughput:
+  - `http://127.0.0.1:<port-a>/v1`
+  - `http://127.0.0.1:<port-b>/v1`
+- Use your actual API key `<YOUR_API_KEY>` and model `<YOUR_MODEL>` on both endpoints.
 - Keep generation settings close to the baseline unless a justified adjustment is required.
 - Implement asynchronous execution, automatic retry on request failure, and resumable scripts.
 - Split requests across both endpoints so throughput stays high without overloading the service.
@@ -421,6 +553,12 @@ Check status:
 ds --status
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --status --home /path/to/DeepScientist
+```
+
 This shows whether the local runtime is up.
 
 Stop the daemon:
@@ -429,8 +567,47 @@ Stop the daemon:
 ds --stop
 ```
 
+If you started DeepScientist with a non-default home, specify it explicitly:  
+
+```bash
+ds --stop --home /path/to/DeepScientist
+```
+
 This stops the local DeepScientist daemon.
 
+Uninstall code and runtime, but keep local data:
+
+```bash
+ds uninstall
+```
+
+If you started DeepScientist with a non-default home, specify it explicitly:
+
+```bash
+ds uninstall --home /path/to/DeepScientist --yes
+```
+
+This removes launcher wrappers, local runtime code, and install-local code trees, but preserves:
+
+- `quests/`
+- `memory/`
+- `config/`
+- `logs/`
+- `plugins/`
+- `cache/`
+
+If you installed DeepScientist from npm and also want to remove the global npm package itself, run this after `ds uninstall`:
+
+```bash
+npm uninstall -g @researai/deepscientist
+```
+
+If you really want to delete local data too, remove the DeepScientist home manually after uninstall:
+
+```bash
+rm -rf /path/to/DeepScientist
+```
+
 Run diagnostics:
 
 ```bash