@researai/deepscientist 1.5.17 → 1.6.0

package/docs/en/01_SETTINGS_REFERENCE.md

@@ -2,6 +2,13 @@
 
 This manual documents the current DeepScientist `Settings` surface and the YAML files it actually edits. The structure intentionally follows a PyTorch-style reference pattern: short summary, schema, parameters, defaults, allowed values, runtime effect, and practical notes.
 
+If DeepScientist is already running, this should be your first stop. The intended path is:
+
+1. start DeepScientist
+2. open the web `Settings` page
+3. use the structured UI first
+4. edit raw YAML only when you are headless, automating setup, or doing bulk changes
+
 Implementation sources:
 
 - `src/ui/src/components/settings/settingsFormCatalog.ts`
@@ -12,12 +19,19 @@ Implementation sources:
 
 ## Overview
 
+This guide works best if you use it in two passes:
+
+1. first read the page-level sections in this document to find the right `Settings` page
+2. then read the field reference only for the page you are actually using
+
+If you try to read the entire file from top to bottom as one long schema, it will feel heavier than it needs to.
+
 The `Settings` page writes directly to the following files:
 
 | File | UI category | Purpose |
 | --- | --- | --- |
 | `~/DeepScientist/config/config.yaml` | Runtime | Main runtime config: home path, daemon, UI, logging, Git, skill sync, cloud, ACP |
-| `~/DeepScientist/config/runners.yaml` | Models | Runner config: `codex` / `claude` binary path, model defaults, approval policy, sandbox, retries |
+| `~/DeepScientist/config/runners.yaml` | Models | Runner config for `codex` / `claude` / `kimi` / `opencode`: binary path, model defaults, permissions, sandbox, retries, env |
 | `~/DeepScientist/config/connectors.yaml` | Connectors | QQ, Telegram, Discord, Slack, Feishu, WhatsApp, Lingzhu connector config |
 | `~/DeepScientist/config/plugins.yaml` | Extensions | Plugin discovery, enable/disable overrides, trust policy |
 | `~/DeepScientist/config/mcp_servers.yaml` | MCP | External MCP servers only; not built-in `memory`, `artifact`, or `bash_exec` |
@@ -28,10 +42,246 @@ Button semantics:
 - `Check` / `Validate`: local schema validation only.
 - `Test`: run a lightweight readiness probe. The exact behavior depends on the file type and is described later in this document.
 
+## Most Common Jobs After First Launch
+
+If you are new to the `Settings` page, start from the task you actually want to complete:
+
+| What you want to do | Open this page first |
+| --- | --- |
+| Change the default language, home path, daemon defaults, web port, or Git policy | `Runtime` |
+| Switch the default runner or configure Claude / Kimi / OpenCode after launch | `Models` |
+| Bind a chat platform or inspect connector state | `Connectors` |
+| Reuse or publish baselines | `Baselines` |
+| Enable and test DeepXiv | `DeepXiv` |
+| Add plugins or plugin load paths | `Extensions` |
+| Register external MCP servers | `MCP` |
+
 Connector-specific setup guides:
 
 - `docs/en/03_QQ_CONNECTOR_GUIDE.md`
 - `docs/en/04_LINGZHU_CONNECTOR_GUIDE.md`
+- `docs/en/10_WEIXIN_CONNECTOR_GUIDE.md`
+- `docs/en/16_TELEGRAM_CONNECTOR_GUIDE.md`
+- `docs/en/17_WHATSAPP_CONNECTOR_GUIDE.md`
+- `docs/en/18_FEISHU_CONNECTOR_GUIDE.md`
+- `docs/en/28_DISCORD_CONNECTOR_GUIDE.md`
+- `docs/en/29_SLACK_CONNECTOR_GUIDE.md`
+
+## Visual Tour Of The Core Settings Pages
+
+The pages below cover the main configuration surfaces you should use after launch.
+
+### Runtime
+
+Route:
+
+- `/settings/config`
+
+This page edits:
+
+- `~/DeepScientist/config/config.yaml`
+
+Use this page when you need to change:
+
+- home path, default locale, and default runner
+- daemon policy, web binding, logging, Git, and skill sync defaults
+- hardware prompt policy and cloud / ACP compatibility knobs
+
+How to use it:
+
+1. open the page
+2. change only the fields related to the task you are doing right now
+3. click `Save`
+4. use `Check` or `Test` if you want confirmation before leaving
+
+Good first tasks here:
+
+- switch `default_locale`
+- change the web port
+- adjust `default_runner`
+- review Git and logging defaults
+
+Do not start here when:
+
+- you are trying to bind one specific connector
+- you are trying to configure one specific runner in detail
+- you need runtime diagnostics rather than configuration
+
+![Runtime settings page](../images/settings/settings-config-en.png)
+
+### Models
+
+Route:
+
+- `/settings/runners`
+
+This page edits:
+
+- `~/DeepScientist/config/runners.yaml`
+
+Use this page when you need to:
+
+- switch the global default runner
+- confirm which runner is currently active
+- configure Codex / Claude Code / Kimi Code / OpenCode without editing `runners.yaml` by hand
+
+How to use it:
+
+1. decide which runner you want to use by default
+2. enable only the runner you actually want active
+3. fill the runner-specific path, config dir, model, and runtime knobs
+4. click `Save`
+5. click `Check` and then `Test`
+
+Good first tasks here:
+
+- enable Claude after `claude` already works in the terminal
+- enable Kimi after `kimi` already works in the terminal
+- reuse an existing OpenCode install
+
+Do not start here when:
+
+- the real problem is a connector delivery issue
+- the real problem is that DeepScientist is unhealthy before any runner even starts
+
+![Models settings page](../images/settings/settings-runners-en.png)
+
+### Connectors
+
+Route:
+
+- `/settings/connector`
+
+This page edits:
+
+- `~/DeepScientist/config/connectors.yaml`
+
+Use this page when you need to:
+
+- choose which connector to configure next
+- jump from the connector catalog into a specific platform page
+- keep connector setup visual-first instead of opening `connectors.yaml` immediately
+
+How to use it:
+
+1. start from the catalog page
+2. open one connector at a time
+3. save that connector before sending real test traffic
+4. only after the first real inbound message, expect discovered targets and runtime state to become useful
+
+Do not start here when:
+
+- you need system-wide diagnosis before touching any connector
+- the runtime itself is not healthy enough to host connectors at all
+
+![Connectors overview page](../images/settings/settings-connectors-overview-en.png)
+
+### Baselines
+
+Route:
+
+- `/settings/baselines`
+
+This page edits:
+
+- the baseline registry under the DeepScientist home rather than one raw config file
+
+Use this page when you need to:
+
+- inspect reusable published baselines
+- attach an existing baseline before launch
+- publish a confirmed quest baseline into the shared registry
+
+How to use it:
+
+1. open this page before launch if you already have a reusable baseline
+2. open it after a quest succeeds if you want to publish that baseline for future reuse
+3. stay here for registry-level baseline work; go back to quest pages for quest-specific work
+
+![Baselines settings page](../images/settings/settings-baselines-en.png)
+
+### DeepXiv
+
+Route:
+
+- `/settings/deepxiv`
+
+This page edits:
+
+- the `literature.deepxiv` block in `~/DeepScientist/config/config.yaml`
+
+Use this page when you need to:
+
+- enable or disable DeepXiv
+- configure the literature token and timeout defaults
+- use the guided setup flow instead of editing `config.yaml` manually
+
+How to use it:
+
+1. open the page
+2. start the guided setup flow if you do not already know the exact fields
+3. save the token and defaults
+4. test the route from the same page before relying on it in real work
+
+![DeepXiv settings page](../images/settings/settings-deepxiv-en.png)
+
+### Extensions
+
+Route:
+
+- `/settings/plugins`
+
+This page edits:
+
+- `~/DeepScientist/config/plugins.yaml`
+
+Use this page when you need to:
+
+- configure plugin discovery paths
+- enable or disable optional local extensions
+- adjust plugin trust policy
+
+How to use it:
+
+1. keep the default path if you are not actively using local plugins
+2. add plugin paths only when you actually have plugins to load
+3. treat this page as a plugin registry page, not a general runtime diagnosis page
+
+![Extensions settings page](../images/settings/settings-plugins-en.png)
+
+### MCP
+
+Route:
+
+- `/settings/mcp_servers`
+
+This page edits:
+
+- `~/DeepScientist/config/mcp_servers.yaml`
+
+Use this page when you need to:
+
+- register or edit external MCP servers
+- review MCP connection settings without touching the built-in MCP namespaces
+- validate external MCP integration before using it in quests
+
+How to use it:
+
+1. add one external MCP server at a time
+2. keep built-in MCP expectations separate from external MCP setup
+3. validate the external MCP server before using it in a real quest
+
+![MCP settings page](../images/settings/settings-mcp-servers-en.png)
+
+## How To Read The Rest Of This Document
+
+From this point onward, the file switches into field-level reference mode.
+
+The fastest way to use the remaining sections is:
+
+1. find the page you actually need
+2. skim its screenshot and operational notes above
+3. jump to the field reference below only for the fields you are about to change
 
 ## `config.yaml`
 
@@ -109,10 +359,10 @@ acp:
 
 - Type: `string`
 - Default: `codex`
-- Allowed values: currently `codex`, `claude`
+- Allowed values: `codex`, `claude`, `kimi`, `opencode`
 - UI label: `Default runner`
 - Meaning: runner used when a project does not override it.
-- Notes: in the current branch, `codex` is the primary path and `claude` remains a reserved slot.
+- Notes: new quests inherit this default; existing quests may override it in project settings. Switch only to a runner that is enabled and already passes `ds doctor`.
 
 **`default_locale`**
 
@@ -192,6 +442,37 @@ acp:
 - UI label: `Default start mode`
 - Meaning: preferred startup surface when launching DeepScientist.
 
+### TUI debug launch switches
+
+TUI debug is not a persistent config field. It is a per-launch diagnostic switch for inspecting the current TUI surface, input route, Web analog, and render summary.
+
+Start with:
+
+```bash
+ds --tui --debug
+ds --tui --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+Environment variables:
+
+- `TUI_DEBUG=1`
+- `DEEPSCIENTIST_TUI_DEBUG=1`
+- `TUI_DEBUG_LOG=/tmp/deepscientist_tui_debug.jsonl`
+- `DEEPSCIENTIST_TUI_DEBUG_LOG=/tmp/deepscientist_tui_debug.jsonl`
+
+Default log path:
+
+```text
+/tmp/deepscientist_tui_debug.jsonl
+```
+
+Safety requirements:
+
+- Config editor buffers and password/secret/token fields are redacted in debug JSONL.
+- Debug JSONL can be attached to issue reports or regression notes, but search it for real tokens first.
+- Terminal recordings, tmux logs, and `script` transcripts capture the real screen; they are outside the JSONL redaction boundary.
+- Web does not yet have an equivalent `?debug=1` inspector; TUI currently provides only the `web_analog` mapping.
+
 ### Logging
 
 **`logging.level`**
@@ -413,10 +694,32 @@ These settings are compatibility knobs for ACP-style external consumers.
 
 ### Summary
 
-`runners.yaml` defines which runner executes projects and what its default model, approval policy, sandbox, and retry behavior should be. In the current open-source release:
+`runners.yaml` defines which CLI runner DeepScientist can launch, which model defaults it should use, how retries behave, and which runner-specific flags should be passed through.
+
+Current built-in runners:
+
+- `codex`
+  - OpenAI Codex CLI path, including Codex-compatible provider profiles
+- `claude`
+  - Claude Code CLI path, including Anthropic or compatible gateway setups that already work in Claude Code
+- `kimi`
+  - Official Kimi Code CLI path, including login state and config already working in `~/.kimi`
+- `opencode`
+  - OpenCode CLI path, including provider/model configurations managed directly by OpenCode
 
-- `codex`: primary path, enabled by default
-- `claude`: TODO / reserved slot, disabled by default, not runnable yet
+The Settings page maps DeepScientist to an already-working CLI runner. Gemini, Ollama, MiniMax, GLM, Bailian, and other providers still need to be configured in the corresponding CLI first:
+
+- Codex provider / profile: see [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
+- Claude Code / Anthropic-compatible / Ollama: see [24 Claude Code Setup](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+- OpenCode / Gemini / Ollama: see [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md)
+- vLLM, Ollama, SGLang, and local backend overview: see [21 Local Model Backends Guide](./21_LOCAL_MODEL_BACKENDS_GUIDE.md)
+
+Recommended validation order:
+
+1. make the underlying CLI work first, such as `codex exec ...`, `claude -p ...`, or `opencode run ...`
+2. fill `binary`, `config_dir`, `profile` / `model`, and `env` in Settings
+3. click `Test` or run `ds doctor --runner <name>`
+4. only then start a real quest
 
 ### Schema
 
@@ -426,25 +729,63 @@ codex:
   binary: codex
   config_dir: ~/.codex
   profile: ""
-  model: gpt-5.4
+  model: inherit
   model_reasoning_effort: xhigh
   approval_policy: never
   sandbox_mode: danger-full-access
   retry_on_failure: true
-  retry_max_attempts: 5
-  retry_initial_backoff_sec: 1.0
-  retry_backoff_multiplier: 2.0
-  retry_max_backoff_sec: 8.0
-  mcp_tool_timeout_sec: 180000
+  retry_max_attempts: 7
+  retry_initial_backoff_sec: 10.0
+  retry_backoff_multiplier: 6.0
+  retry_max_backoff_sec: 1800.0
+  mcp_tool_timeout_sec: 172800
   env: {}
 claude:
   enabled: false
   binary: claude
   config_dir: ~/.claude
   model: inherit
-  model_reasoning_effort: ""
+  permission_mode: bypassPermissions
+  mcp_timeout_ms: 172800000
+  mcp_tool_timeout_ms: 172800000
+  retry_on_failure: true
+  retry_max_attempts: 4
+  retry_initial_backoff_sec: 10.0
+  retry_backoff_multiplier: 4.0
+  retry_max_backoff_sec: 600.0
+  env: {}
+  status: supported
+kimi:
+  enabled: false
+  binary: kimi
+  config_dir: ~/.kimi
+  model: inherit
+  agent: ""
+  thinking: false
+  yolo: true
+  mcp_tool_timeout_ms: 172800000
+  retry_on_failure: true
+  retry_max_attempts: 4
+  retry_initial_backoff_sec: 10.0
+  retry_backoff_multiplier: 4.0
+  retry_max_backoff_sec: 600.0
   env: {}
-  status: reserved_todo
+  status: supported
+opencode:
+  enabled: false
+  binary: opencode
+  config_dir: ~/.config/opencode
+  model: inherit
+  default_agent: ""
+  variant: ""
+  mcp_timeout_ms: 172800000
+  retry_on_failure: true
+  retry_max_attempts: 4
+  retry_initial_backoff_sec: 10.0
+  retry_backoff_multiplier: 4.0
+  retry_max_backoff_sec: 600.0
+  env: {}
+  status: supported
 ```
 
 ### Editable fields
@@ -452,153 +793,184 @@ claude:
 **`enabled`**
 
 - Type: `boolean`
-- Default: `codex=true`, `claude=false`
 - UI label: `Enabled`
-- Meaning: whether this runner can be selected and used.
+- Meaning: whether the runner can be selected and executed.
+- Practical rule: enable only the runners whose CLI binary and auth path already work on this machine.
 
 **`binary`**
 
 - Type: `string`
-- Default: `codex` or `claude`
 - UI label: `Binary`
 - Meaning: command name or absolute path used to launch the runner.
-- `Test` behavior: checks whether the binary is on `PATH`.
-- Resolution order for `codex`: env override, explicit path, local `PATH`, then bundled fallback.
-- One-off note: you can temporarily override this with `ds --codex /absolute/path/to/codex`.
-- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex login` (or just `codex`) has completed successfully.
-- Repair note: if the bundled dependency is missing after `npm install -g @researai/deepscientist`, install Codex explicitly with `npm install -g @openai/codex`.
+- Defaults:
+  - `codex -> codex`
+  - `claude -> claude`
+  - `opencode -> opencode`
+- `Test` behavior: checks whether the binary is available on `PATH` or at the configured path.
 
 **`config_dir`**
 
 - Type: `string`
-- Default: `~/.codex` or `~/.claude`
 - UI label: `Config directory`
-- Meaning: global runner home for auth and global config.
+- Meaning: global runner home used for auth and global settings.
+- Defaults:
+  - `codex -> ~/.codex`
+  - `claude -> ~/.claude`
+  - `opencode -> ~/.config/opencode`
 
 **`profile`**
 
 - Type: `string`
-- Default: `""`
 - UI label: `Codex profile`
-- Meaning: optional Codex profile name passed through as `codex --profile <name>`.
-- Use this when your Codex CLI is already configured for a provider-backed setup such as MiniMax, GLM, Volcengine Ark, or Alibaba Bailian.
-- One-off note: you can also leave this field empty and launch with `ds --codex-profile <name>`.
-- Combined note: one-off profile and binary overrides can be combined as `ds --codex /absolute/path/to/codex --codex-profile <name>`.
+- Runners: `codex`
+- Meaning: optional Codex profile passed as `codex --profile <name>`.
+- Use this when Codex itself is already configured for a provider-backed profile.
 
 **`model`**
 
 - Type: `string`
-- Default: `codex=gpt-5.4`, `claude=inherit`
 - UI label: `Default model`
-- Meaning: default model used when a project does not override it.
-- Startup note: DeepScientist's Codex readiness probe uses this configured model first. If your Codex account cannot access it, DeepScientist falls back to the current Codex default model and persists `model: inherit`.
-- Provider-profile note: when `profile` is set, `model: inherit` is usually the right choice so the Codex profile itself controls the provider model.
+- Meaning: default runner model when a quest or request does not override it.
+- Default: `inherit` for all four runners.
+- Recommended rule:
+  - keep `inherit` when the CLI should decide the provider/model itself
+  - set a fixed model only when you want DeepScientist to override every turn
 
 **`model_reasoning_effort`**
 
 - Type: `string`
-- Default: `codex=xhigh`
 - UI label: `Reasoning effort`
+- Runners: `codex`
+- Meaning: default Codex reasoning effort.
 - Allowed values: `""`, `minimal`, `low`, `medium`, `high`, `xhigh`
-- Meaning: default reasoning intensity.
-- Compatibility note: when DeepScientist detects a Codex CLI older than `0.63.0`, it automatically downgrades `xhigh` to `high` for the startup probe and runner command. This covers MiniMax's currently recommended `@openai/codex@0.57.0` path.
 
 **`approval_policy`**
 
 - Type: `string`
-- Default: `never`
 - UI label: `Approval policy`
+- Runners: `codex`
+- Meaning: Codex approval behavior for privileged actions.
 - Allowed values: `never`, `on-failure`, `on-request`, `untrusted`
-- Meaning: how the runner should ask for permission on privileged actions.
-- Runtime note: the launcher now starts Codex in YOLO mode by default. Passing `ds --yolo false` temporarily restores the non-YOLO pair `approval_policy=on-request` and `sandbox_mode=workspace-write`.
 
 **`sandbox_mode`**
 
 - Type: `string`
-- Default: `danger-full-access`
 - UI label: `Sandbox mode`
+- Runners: `codex`
+- Meaning: Codex filesystem / process sandbox mode.
 - Allowed values: `read-only`, `workspace-write`, `danger-full-access`
-- Meaning: filesystem / process access mode for the runner.
 
-**`env`**
+**`permission_mode`**
 
-- Type: `mapping<string, string>`
-- Default: `{}`
-- UI availability:
-  - global settings: editable in the `runners` structured form as `env`
-  - project settings: `Project settings -> Codex environment`
-- Project-settings behavior:
-  - click `Add` to create a new variable row
-  - `OPENAI_BASE_URL` and `OPENAI_API_KEY` are shown by default
-  - changes are not auto-saved; click `Save env vars`
-  - empty values are ignored and are not injected into the Codex process
-- Meaning: extra environment variables passed to Codex when DeepScientist starts a Codex run.
-- Common use: provider-backed Codex setups that need API keys or custom base URLs.
-
-**`retry_on_failure`**
-
-- Type: `boolean`
-- Default: `true`
-- UI label: `Retry on failure`
-- Meaning: retry a failed turn automatically.
+- Type: `string`
+- UI label: `Permission mode`
+- Runners: `claude`
+- Meaning: Claude Code permission mode passed through as `--permission-mode`.
+- Common values: `default`, `bypassPermissions`, `dontAsk`, `acceptEdits`, `delegate`, `plan`
+- Recommended local automation default: `bypassPermissions`
 
-**`retry_max_attempts`**
+**`mcp_timeout_ms`**
 
 - Type: `number`
-- Default: `5`
-- UI label: `Max attempts`
-- Meaning: total allowed attempts for one turn.
-- Notes: runtime hard-caps this at `5`.
+- Runners: `claude`, `opencode`
+- Meaning:
+  - `claude`: MCP server startup timeout forwarded as `MCP_TIMEOUT`
+  - `opencode`: timeout for fetching tools from each MCP server during startup
+- Note: OpenCode's `mcp_timeout_ms` is not tool execution timeout.
 
-**`retry_initial_backoff_sec`**
+**`mcp_tool_timeout_ms`**
 
 - Type: `number`
-- Default: `1.0`
-- UI label: `Initial backoff (s)`
-- Meaning: delay before the first retry.
+- Runners: `claude`, `kimi`
+- Meaning:
+  - `claude`: per-tool MCP timeout forwarded as `MCP_TOOL_TIMEOUT`
+  - `kimi`: MCP tool execution timeout written to `.kimi/config.toml` as `mcp.client.tool_call_timeout_ms`
 
-**`retry_backoff_multiplier`**
+**`agent`**
 
-- Type: `number`
-- Default: `2.0`
-- UI label: `Backoff multiplier`
-- Meaning: exponential backoff multiplier.
+- Type: `string`
+- UI label: `Kimi agent`
+- Runners: `kimi`
+- Meaning: optional Kimi agent name passed through as `kimi --agent <name>`.
+- Leave empty unless the same agent profile already works in direct Kimi CLI usage.
 
-**`retry_max_backoff_sec`**
+**`thinking`**
 
-- Type: `number`
-- Default: `8.0`
-- UI label: `Max backoff (s)`
-- Meaning: upper bound on retry delay after exponential growth.
+- Type: `boolean`
+- UI label: `Thinking mode`
+- Runners: `kimi`
+- Meaning: whether DeepScientist should pass `--thinking` to Kimi by default.
 
-**`status`**
+**`yolo`**
+
+- Type: `boolean`
+- UI label: `Yolo mode`
+- Runners: `kimi`
+- Meaning: whether DeepScientist should pass `--yolo` so Kimi does not stop for interactive approval prompts.
+- Recommended unattended local automation default: `true`
+
+**`default_agent`**
+
+- Type: `string`
+- UI label: `Default agent`
+- Runners: `opencode`
+- Meaning: optional OpenCode agent name passed through as `opencode run --agent <name>`.
+- Leave empty unless the same agent name already works in direct OpenCode CLI usage.
+
+**`variant`**
 
 - Type: `string`
-- Default: `claude=reserved_todo`
-- UI label: `Status note`
-- Meaning: operator-facing note such as `reserved_todo` or `experimental`.
+- UI label: `Variant`
+- Runners: `opencode`
+- Meaning: optional OpenCode provider-specific variant passed through as `--variant`.
+- Use only when your OpenCode provider documents that flag.
 
-### File-level companion fields
+**`env`**
+
+- Type: `mapping<string, string>`
+- UI label: `Environment variables`
+- Meaning: extra environment variables injected only for this runner.
+- Common examples:
+  - Codex: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+  - Claude: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `CLAUDE_CODE_MAX_OUTPUT_TOKENS`
+  - Kimi: usually empty unless your local Kimi CLI path requires extra environment variables
+  - OpenCode: provider-specific environment variables only if your OpenCode provider setup requires them
+
+**`retry_on_failure` / `retry_max_attempts` / `retry_initial_backoff_sec` / `retry_backoff_multiplier` / `retry_max_backoff_sec`**
+
+- Type: `boolean` / `number`
+- Meaning: automatic turn retry policy for the runner.
+- Defaults:
+  - `codex`: more aggressive retry ladder
+  - `claude` / `kimi` / `opencode`: shorter ladder
 
 **`mcp_tool_timeout_sec`**
 
 - Type: `number`
-- Default: `180000`
-- Meaning: allow long-running MCP tool calls, especially durable `bash_exec` flows.
+- Runners: `codex`
+- Meaning: maximum MCP tool wait time, mainly for long `bash_exec` flows.
 
-**`env`**
+**`status`**
 
-- Type: `mapping[string, string]`
-- Default: `{}`
-- UI location: environment editor at the bottom of each runner card
-- Meaning: per-runner environment overrides.
+- Type: `string`
+- Meaning: operator-facing note.
+- Current practical meaning:
+  - `codex`, `claude`, `kimi`, `opencode`: available built-in paths
 
 ### Practical guidance
 
-- For most installs, keep `codex.enabled: true` and `claude.enabled: false`.
-- Do not switch `default_runner` away from `codex` in the current release.
-- Do not lower `mcp_tool_timeout_sec` casually if your workflow uses long-running tools.
-- Keep retry timing close to `1s / 2x / 8s max` unless you have a specific reason to slow recovery down.
+- Use the runner that already works on your machine and matches the provider path you want.
+- Use `claude` when Claude Code already works directly on the machine and you want Anthropic / Claude-native execution.
+- Use `kimi` when the official Kimi Code CLI already works directly on the machine and you want a separate Moonshot-native runner path.
+- Use `opencode` when your model/provider setup already works best through OpenCode.
+- `default_runner` can now be switched away from `codex` safely if the target runner is enabled and passes `ds doctor`.
+- New quests follow `config.default_runner`.
+- Existing quests can override the runner in project settings.
+- Do not lower `mcp_tool_timeout_sec` casually if your workflow uses long-running `bash_exec` sessions.
+- For Kimi, the important timeout is `mcp_tool_timeout_ms`, because the upstream default is much shorter than the long-running `bash_exec` waits DeepScientist often needs.
+- For Claude, the practical execution cap is already large by default; the more common issue is MCP startup timeout, handled by `mcp_timeout_ms`.
+- For OpenCode, `mcp_timeout_ms` only affects MCP tool discovery / startup, not the execution time of one MCP call.
+
 
 ## `connectors.yaml`