@researai/deepscientist 1.5.16 → 1.6.0

package/docs/en/26_CITATION_AND_ATTRIBUTION.md

@@ -0,0 +1,119 @@
+# 26 Citation And Attribution
+
+This page explains how we hope people cite and acknowledge DeepScientist.
+
+This document is intentionally gentle:
+
+- it is a request for fair academic attribution
+- it is not an extra restriction added to the software license
+- it is not legal advice
+
+## Short version
+
+If DeepScientist materially helps a paper, report, benchmark write-up, or public research artifact, please:
+
+1. cite the DeepScientist paper
+2. disclose meaningful AI assistance honestly
+3. avoid presenting AI-generated or AI-simulated results as purely human or purely real if that would mislead readers
+
+If you only used DeepScientist in a minor operational way, such as opening files, launching a shell, or checking a repository layout, citation is usually not necessary.
+
+## When we strongly encourage citation
+
+Citation is strongly encouraged when DeepScientist materially contributes to work such as:
+
+- research planning or task decomposition
+- baseline restoration or experiment orchestration
+- literature triage or structured paper analysis
+- result analysis, synthesis, or writing support
+- figure, draft, or rebuttal preparation
+
+The practical rule is simple:
+
+- if DeepScientist changed the substance, speed, or shape of the research output in a meaningful way, please cite it
+
+## When citation is usually not necessary
+
+Citation is usually unnecessary when DeepScientist was used only as:
+
+- a local launcher
+- a terminal convenience layer
+- a generic code or file browser
+- a one-off operational helper without material research contribution
+
+## Preferred citation
+
+Paper link:
+
+- `https://openreview.net/forum?id=cZFgsLq8Gs`
+
+BibTeX:
+
+```bibtex
+@inproceedings{
+weng2026deepscientist,
+title={DeepScientist: Advancing Frontier-Pushing Scientific Findings Progressively},
+author={Yixuan Weng and Minjun Zhu and Qiujie Xie and QiYao Sun and Zhen Lin and Sifan Liu and Yue Zhang},
+booktitle={The Fourteenth International Conference on Learning Representations},
+year={2026},
+url={https://openreview.net/forum?id=cZFgsLq8Gs}
+}
+```
+
+## Suggested acknowledgment text
+
+If DeepScientist materially assisted the project, a short acknowledgment like the following is usually enough:
+
+```text
+We used DeepScientist to assist parts of the research workflow, including selected planning, implementation, experiment orchestration, analysis, and/or writing support. Final judgments, claims, and reported real experimental results remain the responsibility of the human authors.
+```
+
+You can shorten or adapt this wording to match venue norms.
+
+## Optional FermiLink attribution
+
+DeepScientist's science-evidence workflow was informed by FermiLink's
+scientific simulation and package-knowledge design. If your project materially
+uses FermiLink itself, cite it directly in addition to DeepScientist.
+
+Repository:
+
+- `https://github.com/TaoELi/FermiLink`
+
+Paper:
+
+- Gang Meng, Andres Felipe Bocanegra Vargas, Xinwei Ji, Federico Garcia-Gaitan,
+  Felipe Reyes-Osorio, Jalil Varela-Manjarres, Yafei Ren, Mohammadhasan
+  Dinpajooh, Branislav K. Nikolic, Tao E. Li. *FermiLink: A Unified Agent
+  Framework for Multidomain Autonomous Scientific Simulations*. arXiv:2604.03460
+  (2026).
+
+## AI assistance disclosure
+
+We strongly encourage clear disclosure when DeepScientist contributed to:
+
+- writing
+- coding
+- experiment setup
+- result interpretation
+- figure generation
+- literature review
+
+The disclosure does not need to overstate use.
+It should simply help readers understand where meaningful AI assistance existed.
+
+## Not a license condition
+
+This citation guidance does not change the repository software license.
+
+In particular:
+
+- it is not a new license condition
+- it does not terminate your software rights if you forget to cite
+- it is a community and academic attribution request, not a software-usage gate
+
+## Related files
+
+- [../../CITATION.cff](../../CITATION.cff)
+- [../../TRADEMARK.md](../../TRADEMARK.md)
+- [11 License And Risk Notice](./11_LICENSE_AND_RISK.md)

package/docs/en/27_KIMI_CODE_PROVIDER_SETUP.md

@@ -0,0 +1,180 @@
+# Kimi Code Provider Setup
+
+Use this guide when you want DeepScientist to run through the official Kimi Code CLI as a separate builtin runner instead of reusing the Claude path.
+
+The right order is:
+
+1. install the official `kimi` CLI
+2. complete the login flow directly in the terminal
+3. confirm `kimi` works on its own
+4. run `ds doctor --runner kimi`
+5. only then switch DeepScientist to the `kimi` runner
+
+## What DeepScientist expects
+
+- Install the official `kimi` CLI and make sure `kimi --version` works in the same shell that launches DeepScientist.
+- Complete the first-run login flow once with `kimi login` or by starting `kimi` interactively.
+- Your global Kimi home should normally live at `~/.kimi/`.
+
+## What success looks like
+
+Before you switch DeepScientist over to Kimi, these should already be true:
+
+- `kimi --version` prints a real version
+- `kimi login` has completed successfully
+- the CLI can answer at least one minimal prompt
+- `ds doctor --runner kimi` passes the Kimi startup probe
+
+If one of those is still false, stay with terminal-level Kimi troubleshooting first.
+
+## Step 1: install and verify the Kimi CLI
+
+Use the official installation path for the current Kimi Code CLI.
+
+After installation, verify the binary you will actually use:
+
+```bash
+which kimi
+kimi --version
+```
+
+If `which kimi` prints nothing, fix the shell PATH first before touching DeepScientist settings.
+
+## Step 2: complete Kimi login directly
+
+Run:
+
+```bash
+kimi login
+```
+
+If your local Kimi setup prefers an interactive first-run flow, start `kimi` once directly and complete login there.
+
+Do this before opening DeepScientist settings for Kimi.
+
+## Step 3: validate Kimi directly
+
+The smallest practical check is:
+
+```bash
+kimi --print --input-format text --output-format stream-json --yolo
+```
+
+Then send a tiny prompt such as:
+
+```text
+Reply with exactly HELLO.
+```
+
+What you want to prove here is simple:
+
+- the CLI starts
+- the login state is valid
+- the session can produce a normal answer
+
+## Settings-first path after launch
+
+If DeepScientist is already running, use the visual `Models` page first:
+
+- route: `/settings/runners`
+
+Use it to:
+
+- switch the global default runner to `Kimi`
+- enable the Kimi runner
+- fill `binary`, `config_dir`, `model`, `agent`, `thinking`, and `yolo`
+
+![Models settings page](../images/settings/settings-runners-en.png)
+
+Recommended first values:
+
+- `binary`: `kimi`
+- `config_dir`: `~/.kimi`
+- `model`: `inherit`
+- `agent`: leave empty unless your direct Kimi CLI already depends on a named agent
+- `thinking`: leave `false` first unless you already know you want longer default reasoning
+- `yolo`: keep `true` for unattended local automation
+- `mcp_tool_timeout_ms`: keep a large value when long `bash_exec` waits or other long MCP calls are expected
+
+## Recommended `runners.yaml` shape
+
+```yaml
+kimi:
+  enabled: true
+  binary: kimi
+  config_dir: ~/.kimi
+  model: inherit
+  agent: ""
+  thinking: false
+  yolo: true
+  mcp_tool_timeout_ms: 172800000
+```
+
+Use raw `runners.yaml` editing only when:
+
+- the web UI is not available
+- you are scripting setup
+- you want repeatable machine provisioning
+
+## Runtime behavior
+
+- DeepScientist copies your configured `~/.kimi` home into an isolated quest runtime under `.ds/kimi-home/.kimi`.
+- Quest-local skills are mirrored into `.kimi/skills`.
+- Builtin DeepScientist MCP servers are injected through a generated `.kimi/mcp.json`.
+- Prompts are sent over stdin, so long DeepScientist turns do not hit argv length limits.
+
+## Step 4: validate DeepScientist before switching globally
+
+Run:
+
+```bash
+ds doctor --runner kimi
+```
+
+You want the Kimi section to confirm:
+
+- the `kimi` binary is found
+- the configured `config_dir` is readable
+- the startup probe succeeds
+
+Only after that should you switch the global default runner to `kimi`.
+
+## Step 5: switch the default runner
+
+You can do that in either place:
+
+- `Settings -> Runtime -> Default runner`
+- `~/DeepScientist/config/config.yaml`
+
+Once DeepScientist is already running, the visual Settings page is the intended path.
+
+## Common failure cases
+
+### `kimi` is not on PATH
+
+Check:
+
+```bash
+which kimi
+kimi --version
+```
+
+If needed, set the absolute binary path in the `Models` page or `runners.yaml`.
+
+### `kimi login` worked once, but `ds doctor --runner kimi` still fails
+
+Usually one of these is wrong:
+
+- the shell used by DeepScientist is not the same shell where `kimi` was tested
+- `config_dir` points at the wrong Kimi home
+- the local Kimi session was only partially initialized
+
+### Kimi works directly, but DeepScientist still should not use it yet
+
+Do not switch the default runner immediately if:
+
+- the CLI only works intermittently
+- you still need manual interactive confirmations
+- the startup probe fails even though interactive mode works
+
+In that case, keep Codex as the default until the Kimi path is stable.

package/docs/en/28_DISCORD_CONNECTOR_GUIDE.md

@@ -0,0 +1,61 @@
+# 28 Discord Connector Guide
+
+Use this guide when you want to configure and operate the built-in Discord connector through the DeepScientist `Settings` page.
+
+Discord now lives under the same connector surface as QQ, Telegram, Slack, Feishu, WhatsApp, WeChat, and Lingzhu. You do not need a separate relay process or a public callback URL for the recommended path.
+
+## 1. Open The Connector Page
+
+Route:
+
+- [Settings > Connectors > Discord](/settings/connector/discord)
+
+This is the page you should use after launch for normal Discord setup.
+
+![Discord connector settings page](../images/connectors/connector-discord-en.png)
+
+## 2. What This Page Is For
+
+Use the Discord page when you need to:
+
+- configure the built-in `gateway` transport
+- enter `bot_token` and `application_id`
+- review runtime status, discovered targets, and connector events
+- save connector changes without editing `connectors.yaml` manually
+
+## 3. Recommended Setup Path
+
+1. Open the Discord Developer Portal.
+2. Create or select the bot application.
+3. Copy the bot token and application id.
+4. Open `Settings > Connectors > Discord`.
+5. Keep `transport: gateway`.
+6. Fill `bot_token` and `application_id`.
+7. Save the connector.
+8. Send one real message to the bot from Discord.
+9. Return to this page and confirm that targets or runtime activity are now visible.
+
+## 4. What To Check On This Page
+
+Before you leave the page, confirm:
+
+- `Transport` still shows `gateway`
+- the connector card saves cleanly
+- runtime status updates after the first real Discord message
+- discovered targets and bindings start appearing once the bot is actually contacted
+
+## 5. When To Use Raw YAML Instead
+
+You can stay in the `Settings` page for ordinary setup.
+
+Open `~/DeepScientist/config/connectors.yaml` directly only when you need:
+
+- scripted provisioning
+- bulk edits across many connectors
+- environment-variable injection patterns that are easier to manage in files
+
+## 6. Related Docs
+
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [30 Settings Control Center Guide](./30_SETTINGS_CONTROL_CENTER_GUIDE.md)
+- [09 Doctor](./09_DOCTOR.md)

package/docs/en/29_SLACK_CONNECTOR_GUIDE.md

@@ -0,0 +1,60 @@
+# 29 Slack Connector Guide
+
+Use this guide when you want to configure and operate the built-in Slack connector through the DeepScientist `Settings` page.
+
+Slack uses the built-in Socket Mode path in the current open-source runtime. The intended operator flow is visual-first: launch DeepScientist, open `Settings`, then complete the connector setup there.
+
+## 1. Open The Connector Page
+
+Route:
+
+- [Settings > Connectors > Slack](/settings/connector/slack)
+
+![Slack connector settings page](../images/connectors/connector-slack-en.png)
+
+## 2. What This Page Is For
+
+Use the Slack page when you need to:
+
+- configure the built-in `socket_mode` transport
+- enter `bot_token` and `app_token`
+- review discovered targets and connector runtime state
+- save Slack setup without manually editing `connectors.yaml`
+
+## 3. Recommended Setup Path
+
+1. Open the Slack App dashboard.
+2. Create or select the Slack app.
+3. Enable Socket Mode.
+4. copy the `bot_token`
+5. copy the `app_token`
+6. open `Settings > Connectors > Slack`
+7. keep `transport: socket_mode`
+8. fill `bot_token` and `app_token`
+9. save the connector
+10. send one real Slack message so DeepScientist can discover the runtime target
+
+## 4. What To Check On This Page
+
+Before leaving the page, confirm:
+
+- `Transport` remains `socket_mode`
+- the connector saves without local validation errors
+- runtime status changes after the first real Slack message
+- discovered targets and bindings become non-empty once the bot has real traffic
+
+## 5. When To Use Raw YAML Instead
+
+Stay in `Settings` for ordinary setup, rotation, and inspection.
+
+Use raw `connectors.yaml` only when you need:
+
+- scripted rollout
+- bulk edits
+- environment-variable injection patterns that are easier to maintain in files
+
+## 6. Related Docs
+
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [30 Settings Control Center Guide](./30_SETTINGS_CONTROL_CENTER_GUIDE.md)
+- [09 Doctor](./09_DOCTOR.md)