@researai/deepscientist 1.5.16 → 1.6.0

package/docs/en/02_START_RESEARCH_GUIDE.md

@@ -67,12 +67,14 @@ https://arxiv.org/abs/2602.00428
 
 `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.
@@ -93,7 +95,7 @@ https://arxiv.org/abs/2602.00428
 If you leave `Reusable baseline` empty and choose `Balanced`, the current frontend derives:
 
 - `scope = baseline_plus_direction`
-- `baseline_mode = restore_from_url`
+- `baseline_mode = auto`
 - `resource_policy = balanced`
 - `time_budget_hours = 24`
 - `git_strategy = semantic_head_plus_controlled_integration`
@@ -139,6 +141,18 @@ type StartResearchTemplate = {
 
 Important point: `scope`, `baseline_mode`, `resource_policy`, `time_budget_hours`, and `git_strategy` are no longer edited directly in the form. They are derived from `research_intensity` plus whether a reusable baseline is selected.
 
+New explicit launch-time controls also exist:
+
+- `baseline_source_mode`
+- `execution_start_mode`
+- `baseline_acceptance_target`
+
+These are not replacements for the derived contract. They are stronger user-facing route preferences that tell the agent:
+
+- whether to verify a local existing system, attach a reusable baseline, reproduce from source, repair a stale baseline, or defer baseline work until it is actually blocking
+- whether to stop after a bounded plan for approval before heavy execution
+- how strong the baseline must be before the quest should move into idea selection and experiments
+
 ### Derived contract fields
 
 ```ts
@@ -320,6 +334,12 @@ This is the main public knob for round depth.
 - `user_gated`
   - the agent may raise a blocking decision only when continuation truly depends on the user
 
+Waiting-state visibility:
+
+- When the runtime intentionally parks a quest, Studio shows a **Waiting for feedback** banner and the bound connector receives a matching notice.
+- If `decision_policy=autonomous`, ordinary wait states such as paper-bundle checkpoints are converted back into automatic continuation and surfaced as **Auto-resumed** instead of silently blocking.
+- True blocking cases can still wait in autonomous mode when user input is required for credentials, privacy/data-export boundaries, high external cost, or final quest-completion approval.
+
 Practical note on workspace mode:
 
 - DeepScientist also distinguishes a user-directed `copilot` workspace mode from the default `autonomous` mode.
@@ -416,6 +436,7 @@ Current preset mapping:
 Override rule:
 
 - if `baseline_id` is selected, derived `baseline_mode` becomes `existing`
+- if `baseline_source_mode` is explicitly set, treat it as the stronger route preference and use `baseline_mode` only as the compact derived summary
 
 ## Prompt compilation behavior
 

package/docs/en/03_QQ_CONNECTOR_GUIDE.md

@@ -102,7 +102,18 @@ DeepScientist currently uses this path:
 
 Open:
 
-- [Settings > Connectors > QQ](/settings/connectors#connector-qq)
+- [Settings > Connectors > QQ](/settings/connector/qq)
+
+### Settings page at a glance
+
+This is the real QQ connector page after launch. Use it to:
+
+- add the QQ connector entry
+- save `App ID` and `App Secret`
+- review runtime state, discovered targets, and recent activity
+- confirm that `openid` was learned after the first inbound QQ message
+
+![QQ connector settings page](../images/connectors/connector-qq-en.png)
 
 The link jumps directly to the `QQ` connector card. The page is now organized into these anchored setup steps:
 
@@ -192,7 +203,7 @@ If the connector is working, DeepScientist will auto-detect the `openid` for tha
 
 ### Step 5: go back to the Settings page and confirm the state
 
-Refresh or reopen `Settings > Connectors > QQ`, or jump back to [#connector-qq-step-success](/settings/connectors#connector-qq-step-success), and check:
+Refresh or reopen `Settings > Connectors > QQ`, or jump back to [#connector-qq-step-success](/settings/connector/qq#connector-qq-step-success), and check:
 
 - whether `Detected OpenID` is now filled automatically
 - whether the `Snapshot` panel shows something close to:
@@ -323,7 +334,7 @@ If you only want the shortest path that works:
 
 1. create the QQ bot
 2. save `AppID` and `AppSecret`
-3. open [Settings > Connectors > QQ](/settings/connectors#connector-qq)
+3. open [Settings > Connectors > QQ](/settings/connector/qq)
 4. enable QQ and fill `App ID` / `App secret`
 5. save and click `Check`
 6. send `/help` to the bot from your QQ private chat

package/docs/en/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -34,6 +34,8 @@ Make sure:
 
 You no longer need to manually edit host, port, agent, OpenClaw snippets, or extra probe steps in the main flow.
 
+![Lingzhu connector settings page](../images/connectors/connector-lingzhu-en.png)
+
 ## 3. What is auto-generated
 
 After you click `Add Lingzhu (Rokid Glasses)`, the popup shows these copyable values:

package/docs/en/05_TUI_GUIDE.md

@@ -64,6 +64,21 @@ Meaning:
 - `ds --status`: inspect daemon status.
 - `ds --stop`: stop the daemon itself, not just one quest.
 
+When you need to debug TUI rendering or routing, temporarily enable debug mode:
+
+```bash
+ds --tui --debug
+ds --tui --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+You can also use environment variables:
+
+```bash
+DEEPSCIENTIST_TUI_DEBUG=1 DEEPSCIENTIST_TUI_DEBUG_LOG=/tmp/deepscientist_tui_debug.jsonl ds --tui
+```
+
+Debug mode is for troubleshooting. Do not leave it on for ordinary daily use.
+
 ## 3. What To Look At First After Entering TUI
 
 When the TUI opens, the first useful signals are:
@@ -124,6 +139,7 @@ You should then see:
 
 - the quest is already bound
 - the history area starts showing messages, artifacts, or operations
+- on long-running quests, TUI restores a recent history window first so reopening stays responsive, then continues streaming new events from the latest cursor
 - the status line shows the active quest id
 
 ### Step 4. Send one normal message
@@ -176,6 +192,7 @@ That matters because TUI and Web are looking at the same daemon, the same quest,
 - `/config qq`: open QQ config directly
 - `/config weixin`: open Weixin config directly
 - `/config lingzhu`: open Lingzhu config directly
+- `/debug`: open the current TUI debug inspector
 
 ### Keys
 
@@ -186,6 +203,7 @@ That matters because TUI and Web are looking at the same daemon, the same quest,
 - `Ctrl+R`: force refresh
 - `Ctrl+O`: open the Web workspace
 - `Ctrl+G`: open the config home directly
+- `Ctrl+D`: open the debug inspector from any screen; inside the config editor it opens as a non-destructive overlay
 - `Ctrl+B`: leave the current quest; if you are in config first, close config
 - `Ctrl+C`: quit the TUI
 - `Shift+↑/↓`: scroll the history area by one line
@@ -451,7 +469,141 @@ So:
 So if you only want to pause for a while, prefer `/pause`.
 If you want to cut off the current turn clearly, prefer `/stop`.
 
-## 15. Troubleshooting
+## 15. TUI Debug Mode
+
+TUI debug mode answers three questions:
+
+1. what surface the terminal is actually rendering
+2. whether Enter will run a local command, forward to the backend, send quest chat, or get blocked locally
+3. which Web page is the closest equivalent for this TUI surface
+
+Enable it with:
+
+```bash
+ds --tui --debug
+```
+
+Choose a log path:
+
+```bash
+ds --tui --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+If you run the TUI bundle directly:
+
+```bash
+node src/tui/dist/index.js --base-url http://127.0.0.1:20999 --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+### What appears on screen
+
+Debug mode shows a small diagnostic strip above the input area:
+
+- `surface`: the current TUI surface, such as `home`, `quest:<id>`, `config:root:browse`, or `config:files:edit`
+- `web`: the closest Web page, such as `Web Settings` or `Web quest workspace`
+- `route`: the route type for the current input
+- `target`: the endpoint, utility panel, or local action that would receive the input
+- `parse / preview`: the parsed command and a short input preview
+
+Press `Ctrl+D` from any screen to open the `TUI Debug` panel. The panel shows:
+
+- `Submitted Route`: where the current input would have gone before opening the debug panel
+- `Input`: a redacted input summary
+- `Screen`: the current main surface, composer, selected item, and redaction state
+- `Render`: quest/config/utility counts and selection index
+- `Capture`: status line, session id, log path, and snapshot signature
+
+### JSONL logs
+
+Debug mode writes snapshots as JSONL. The default path is:
+
+```text
+/tmp/deepscientist_tui_debug.jsonl
+```
+
+Each line is one snapshot. Common fields:
+
+- `surface`
+- `web_analog`
+- `route`
+- `input`
+- `screen`
+- `counts`
+- `status_line`
+
+Config editor buffers and connector secret fields are redacted. Example:
+
+```json
+{
+  "surface": "config:files:edit",
+  "route": {
+    "kind": "config-save",
+    "arg": "[redacted: config editor buffer; 53 chars]"
+  },
+  "input": {
+    "raw": "[redacted: config editor buffer; 53 chars]",
+    "redacted": true,
+    "redaction_reason": "config editor buffer"
+  },
+  "screen": {
+    "main": "Config editor: config.yaml",
+    "input_redacted": true
+  }
+}
+```
+
+Important: the JSONL log redacts config buffers, but terminal recording tools such as `script`, tmux logs, or screen recordings capture the real editor view. That is expected because the editor must show the file content. Do not post terminal transcripts containing real tokens in public issues.
+
+### When to use debug mode
+
+Use debug mode when:
+
+- `/config`, `/benchstore`, `/tasks`, or another command does not appear to open the expected surface
+- you need to know whether a slash command is local, backend-forwarded, or blocked
+- you are in the config editor and need to know which draft Enter would save
+- TUI and Web look inconsistent and you need the `web_analog`
+- you need reproducible route/screen evidence for an issue or regression test
+
+Avoid debug mode when:
+
+- you are just chatting with a quest normally
+- you are editing real secrets and also recording the full terminal output
+- you only need daemon log verbosity; use `logging.level` for that
+
+### Relationship to Web debug
+
+Web also has a lightweight debug inspector for the Settings surface. Enable it with a query flag:
+
+```text
+/settings/connector/qq?debug=1
+```
+
+or persist it in the browser console:
+
+```js
+localStorage.setItem('deepscientist.debug', '1')
+```
+
+To keep an in-browser JSONL buffer for the current page session:
+
+```js
+localStorage.setItem('deepscientist.debug.log', '1')
+```
+
+Remove the key or use `?debug=0` to turn it off.
+
+The Web inspector appears in the bottom-right corner. It shows the current Settings surface, route, selected section or connector, dirty/loading/saving/testing flags, config/connector/quest counts, action disabled reasons, recent API request status, and a redacted JSON snapshot. Use `Copy JSON` or `Download JSONL` when attaching evidence to an issue. When `deepscientist.debug.log` is enabled, `Download JSONL` exports the accumulated in-browser snapshot log; otherwise it exports the current snapshot.
+
+For a strict Web/TUI comparison:
+
+1. record TUI JSONL with `--debug-log`
+2. open the matching Web page with `?debug=1`, such as `/settings/connector/qq?debug=1`
+3. compare TUI `surface`, `web_analog`, and `route.target` with Web `surface`, `route`, `selected`, `flags`, and `actions`
+4. confirm neither snapshot contains real token, secret, password, API key, credential, auth AK, or app secret values
+
+Current scope: the first Web implementation covers Settings, especially connector and config pages. Quest workspace and BenchStore snapshots are planned follow-ups.
+
+## 16. Troubleshooting
 
 ### Problem 1: I entered TUI, but plain text does nothing
 
@@ -505,7 +657,24 @@ Confirm:
 - it is not `localhost`, `127.0.0.1`, or a private LAN address
 - the Rokid platform is using the values shown in the top guide, not a local address
 
-## 16. A Simple Final Check
+### Problem 6: The TUI does not seem to run my command
+
+Start with debug enabled:
+
+```bash
+ds --tui --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+Reproduce the input once and inspect:
+
+- whether `route.kind` is `blocked`
+- whether `route.target` is the endpoint or panel you expected
+- whether `surface` changed to the expected page
+- whether `web_analog` points to the Web page you expected
+
+If you are inside the config editor, press `Ctrl+D` to open the debug inspector. Do not type `/debug`, because normal text is part of the editor buffer there.
+
+## 17. A Simple Final Check
 
 If you want to know whether you can really run the TUI flow end to end, check whether all four are true:
 

package/docs/en/07_MEMORY_AND_MCP.md

@@ -259,9 +259,10 @@ Then inspect:
 ```text
 bash_exec.bash_exec(mode="list", status="running")
 bash_exec.bash_exec(mode="read", id="<bash_id>")
+bash_exec.bash_exec(mode="await", id="<bash_id>", wait_timeout_seconds=1800)
 ```
 
-Use `kill` only when the quest truly needs to stop the session.
+If that bounded `await` returns while the session is still `running`, the process keeps going in the background. Read the saved log, judge real forward progress, and then decide whether another `1800s` wait is warranted. Use `kill` only when the quest truly needs to stop the session.
 
 ## 6. Prompt-level expectations
 
@@ -274,7 +275,42 @@ The agent should normally follow this discipline:
 5. `bash_exec` for durable shell work
 6. `memory.write(...)` only after a real durable finding appears
 
-## 7. UI expectation
+## 7. Cross-quest recall via the file system
+
+Cards are quest-scoped by default and `memory.search` is substring-only, so the durable cross-quest channel is the file system rather than the card index. This channel is available only when the runtime prompt says `cross_quest_recall_enabled: true`, which corresponds to `memory.read_visibility_mode = shared_across_quests`.
+
+When enabled, `idea` and any other stage that benefits from prior-quest context may:
+
+1. enumerate sibling quests with `bash_exec ls -t ~/DeepScientist/quests/*/brief.md`
+2. read briefs to find same-domain prior quests
+3. for any material overlap, deep-read the source quest's `~/DeepScientist/quests/<id>/paper/latex/main.tex`, especially its `Conclusion` and `Limitations / Discussion` sections — that is where prescriptive guidance for follow-up quests is recorded (the `write` checklist now requires it)
+4. read `~/DeepScientist/framework_quirks.md` if it exists for known framework-layer pitfalls before committing to a route that would touch the same surfaces
+
+When disabled, agents must not scan sibling quests or read/write global quirk files unless the user explicitly provides those files in the current task.
+
+## 8. Framework quirks
+
+`~/DeepScientist/framework_quirks.md` is a runtime-wide append-only document for framework-layer pitfalls (validator path quirks, closure-protocol gotchas, anything that cannot or will not be fixed in code and that future quests should know about before exercising the same surfaces). The file is scaffolded by `ensure_home_layout` with a usage header, but agents should use it only when cross-quest recall is enabled by the runtime prompt.
+
+Add an entry only when:
+
+- the surface cannot be fixed at the framework level, or
+- a fix is in flight but the workaround is durable enough to record while the fix lands.
+
+If a quirk should be fixed in code, file an issue and fix it; do not let the file accumulate permanent shims.
+
+## 9. System quirks
+
+`~/DeepScientist/system_quirks.md` is a runtime-wide append-only document for confirmed DeepScientist runtime or system bugs. It is separate from `framework_quirks.md`:
+
+- `framework_quirks.md` is for framework-layer pitfalls that may shape future idea, decision, or finalize behavior.
+- `system_quirks.md` is for confirmed system bugs that may help admin/debug issue reports.
+
+Each `system_quirks.md` entry should include expected behavior, actual behavior, reproduction, impact, workaround, suggested fix, evidence paths, and status. Do not store secrets, tokens, private hostnames, private paths, or raw logs. The settings Issue Report page may include this file in a GitHub issue draft only when the operator explicitly enables that option.
+
+Agents should read or append `system_quirks.md` only when the runtime prompt enables cross-quest recall. The Settings Issue Report checkbox is separate: it only controls whether the current file contents are copied into the issue draft for operator review.
+
+## 10. UI expectation
 
 In `/projects/{id}` Studio trace:
 

package/docs/en/09_DOCTOR.md

@@ -2,6 +2,16 @@
 
 Use `ds doctor` when DeepScientist does not start cleanly after installation.
 
+If DeepScientist already launches and you can reach the web UI, do not start from raw logs first. Start from the visual operator path:
+
+1. open [30 Settings Control Center Guide](./30_SETTINGS_CONTROL_CENTER_GUIDE.md)
+2. check `Summary`, `Runtime`, `Diagnostics`, and `Errors`
+3. only then fall back to `ds doctor` or raw config edits if the visual surface is not enough
+
+The `Diagnostics` page is the operator-facing surface that pairs best with `ds doctor`:
+
+![Settings diagnostics page](../images/admin/admin-diagnostics-en.png)
+
 ## Recommended flow
 
 1. Install DeepScientist:
@@ -15,7 +25,7 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    Default OpenAI path:
 
    ```bash
-   codex --login
+   codex login
    ```
 
    Provider-backed profile path:
@@ -53,12 +63,32 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 - whether `uv` is available to manage the local Python runtime
 - whether `git` is installed and configured
 - whether required config files are valid
-- whether the current release is still using `codex` as the runnable runner
+- whether the enabled/default runner configuration is internally consistent
 - whether the Codex CLI can be found and passes a startup probe
+- whether a recent quest runtime failure already points to a known provider / protocol / retry problem
 - whether an optional local `pdflatex` runtime is available for paper PDF compilation
 - whether the web and TUI bundles exist
 - whether the configured web port is free or already running the correct daemon
 
+Important Codex distinction: `codex login` only proves that the Codex CLI completed its
+authentication flow. The `ds doctor` runner check is stricter: it sends a real
+non-interactive `codex exec` request and expects a `HELLO` response. A machine can
+therefore show "Successfully logged in" from `codex login` while `ds doctor`
+still fails because the model is unavailable, the provider key is missing from
+the DeepScientist process environment, the proxy is not inherited, or the Codex
+profile/config directory differs from the one you tested manually.
+
+`ds doctor` now tries to render failed checks in a more operational form:
+
+- `Problem`: what failed
+- `Why`: why DeepScientist believes it failed
+- `Fix`: the concrete next steps to try
+- `Evidence`: the quest/run/request clues that matched the diagnosis
+
+For failed runner probes, the report also includes the useful low-level evidence
+when available: exit code, probe command, selected profile/model, stdout excerpt,
+and stderr excerpt. Use those fields before retrying blindly.
+
 ## Common fixes
 
 ### Codex is missing
@@ -80,13 +110,29 @@ npm install -g @openai/codex
 Run:
 
 ```bash
-codex --login
+codex login
 ```
 
-If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+If you prefer the interactive first-run flow, run `codex` and finish the setup there.
 
 Finish login once, then rerun `ds doctor`.
 
+If `codex login` says success but `ds doctor` still fails, run the same kind of
+non-interactive smoke test that DeepScientist uses:
+
+```bash
+printf 'Reply with exactly HELLO.' | codex --search exec --json --cd /tmp --skip-git-repo-check -
+```
+
+If that command fails, fix Codex, the selected model, the profile, the provider
+key, or the proxy first. If that command succeeds but `ds doctor` fails, compare:
+
+- `which codex`
+- `CODEX_HOME`
+- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
+- `~/DeepScientist/config/runners.yaml`
+- any `runners.codex.env` values needed by provider-backed profiles
+
 ### Codex profile works in the terminal, but DeepScientist still fails
 
 Run DeepScientist with the same profile explicitly:
@@ -108,7 +154,9 @@ ds --codex /absolute/path/to/codex --codex-profile m27
 Also check:
 
 - the same shell still exports the provider API key
+- if `codex --profile <name>` works but `ds doctor` or `ds docker` still reports a missing provider environment variable, also put that key in `~/DeepScientist/config/runners.yaml` under `runners.codex.env`
 - the profile points at the provider's Coding Plan endpoint, not the generic API endpoint
+- if you are using Qwen through Alibaba Bailian, use the Bailian Coding Plan endpoint only; the generic Bailian or DashScope Qwen API is not supported here
 - `~/DeepScientist/config/runners.yaml` uses `model: inherit` if the provider expects the model to come from the profile itself
 
 MiniMax-specific note:
@@ -125,6 +173,8 @@ MiniMax-specific note:
 - DeepScientist also strips conflicting `OPENAI_*` auth variables automatically for providers that set `requires_openai_auth = false`
 - if you also want plain terminal `codex --profile <name>` to work directly, put `model_provider = "minimax"` and the matching top-level model such as `MiniMax-M2.7` or `MiniMax-M2.5` in `~/.codex/config.toml`
 - DeepScientist automatically downgrades `xhigh` to `high` when it detects a Codex CLI older than `0.63.0`
+- if the provider returns `tool call result does not follow tool call (2013)`, treat it as a request-ordering/protocol error rather than a transient network failure
+- if the provider returns malformed tool-call argument errors such as `invalid function arguments json string` or `failed to parse tool call arguments`, fix the tool-call serialization path before retrying again
 
 ### The configured Codex model is unavailable
 
@@ -176,6 +226,18 @@ ds --stop
 
 Then run `ds` again.
 
+If `ds doctor` says the port is already serving another DeepScientist home, use
+the home path printed in the error. For example:
+
+```bash
+ds --home /path/printed/by/doctor doctor
+ds --home /path/printed/by/doctor --stop
+```
+
+This usually means you started DeepScientist once from one directory/home and are
+now running `ds doctor` against another home. Either use the already running home
+or change this home to a different port.
+
 If another service already uses the port, change `ui.port` in:
 
 ```text
@@ -220,15 +282,24 @@ git config --global user.name "Your Name"
 git config --global user.email "you@example.com"
 ```
 
-### Claude was enabled by mistake
+### Runner switching and enablement
+
+Current releases support `codex`, `claude`, `kimi`, and `opencode`.
 
-Current open-source releases keep `claude` as a TODO/reserved slot only.
-Set it back to disabled in:
+If a non-default runner was enabled by mistake, check:
 
 ```text
+~/DeepScientist/config/config.yaml
 ~/DeepScientist/config/runners.yaml
 ```
 
+Then confirm:
+
+- `default_runner` points at the runner you actually want
+- the selected runner has `enabled: true`
+- disabled runners stay disabled if you are not using them
+- `ds doctor` passes for the enabled runner before you switch quests over
+
 ## Notes
 
 - `ds docker` is kept as a compatibility alias, but the official command is `ds doctor`.

package/docs/en/10_WEIXIN_CONNECTOR_GUIDE.md

@@ -48,7 +48,18 @@ This reference screenshot is only there to remind you to use the phone that alre
 
 Open:
 
-- [Settings > Connectors > WeChat](/settings/connectors#connector-weixin)
+- [Settings > Connectors > WeChat](/settings/connector/weixin)
+
+### Settings page at a glance
+
+Use the WeChat page to:
+
+- start the QR-based binding flow
+- inspect the current runtime status after login
+- verify the saved account identity and connector state
+- keep the whole binding path inside DeepScientist instead of a separate local bridge
+
+![WeChat connector settings page](../images/connectors/connector-weixin-en.png)
 
 Then:
 
@@ -141,6 +152,32 @@ Check:
 
 If the QR expires, DeepScientist refreshes it automatically.
 
+### QR code does not appear behind a proxy
+
+If DeepScientist is started with `ds --proxy ...`, or if the shell has
+`HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` set, the Weixin login and polling
+requests can inherit that proxy. Some local HTTP proxy tunnels work for model
+traffic but make the Weixin iLink QR login stall, fail to render the QR image, or
+wait forever after the phone confirmation.
+
+When this happens, keep the global proxy for other outbound traffic but bypass
+the Weixin iLink and CDN hosts with `NO_PROXY` and `no_proxy`:
+
+```bash
+export NO_PROXY="ilinkai.weixin.qq.com,novac2c.cdn.weixin.qq.com,127.0.0.1,localhost"
+export no_proxy="$NO_PROXY"
+ds --proxy http://127.0.0.1:7890
+```
+
+If you already have a `NO_PROXY` value, append these hosts instead of replacing
+the existing list.
+
+This keeps model or GitHub requests on the configured proxy while allowing the
+Weixin QR login, long polling, and media CDN requests to connect directly. If QR
+login still does not work, temporarily unset `HTTP_PROXY`, `HTTPS_PROXY`,
+`ALL_PROXY`, `http_proxy`, `https_proxy`, and `all_proxy`, then restart
+DeepScientist and retry the binding flow.
+
 ### I only see text, but not inbound media
 
 Re-test with a real image, video, or file. After a successful inbound media message, confirm that the quest now contains:

package/docs/en/11_LICENSE_AND_RISK.md

@@ -14,10 +14,14 @@ DeepScientist is released under the Apache License 2.0.
 The full license text is in the repository root:
 
 - [LICENSE](../../LICENSE)
+- [TRADEMARK.md](../../TRADEMARK.md)
+- [26 Citation And Attribution](./26_CITATION_AND_ATTRIBUTION.md)
 
 The practical meaning is:
 
 - DeepScientist is distributed under Apache 2.0
+- the software license does not grant trademark rights in the DeepScientist name or logo
+- citation guidance is a separate academic attribution request, not an extra software license condition
 - DeepScientist is provided on an "AS IS" basis, without warranties
 - the project authors and maintainers are not responsible for any direct or indirect consequence caused by using, deploying, modifying, redistributing, or exposing DeepScientist
 - you are responsible for runtime environment control, permission boundaries, public exposure, third-party account binding, output review, data handling, and compliance

package/docs/en/12_GUIDED_WORKFLOW_TOUR.md

@@ -42,6 +42,12 @@ Use `Open Project` when the quest already exists and you want to continue it.
 
 For a first run, click `Start Research`.
 
+If you only want one practical rule:
+
+- click `Start Research` when you already know what project you want to start
+- click `BenchStore` when you want the system to help you choose a benchmark first
+- click `Settings` when you are not starting a project yet and only want to configure the system
+
 ## 3. Understand what the dialog is doing
 
 The `Start Research` dialog has two jobs:
@@ -245,6 +251,15 @@ Check for:
 
 This is the cheapest correction point in the whole workflow.
 
+If you are unsure what the shortest real-project path looks like, it is:
+
+1. `Start Research`
+2. `Autonomous`
+3. fill `Project title`
+4. fill `Primary research request`
+5. review the right-side prompt
+6. click `Create project`
+
 ## 5. Click Create project
 
 In real project mode, this creates a real local quest and opens its workspace.

package/docs/en/14_PROMPT_SKILLS_AND_MCP_GUIDE.md

@@ -345,6 +345,10 @@ These are auxiliary entry or quality-control skills:
 | `intake-audit` | the quest already has meaningful prior state | trust-rank old assets and choose the correct next anchor |
 | `review` | a substantial draft already exists | run a skeptical paper-like audit before claiming done |
 | `rebuttal` | reviewer comments or revision requests exist | map reviewer pressure into experiments, text deltas, and response artifacts |
+| `nature-polishing` | Nature-style manuscript wording or CN-to-EN academic polish is requested | polish prose after evidence and claim boundaries are explicit |
+| `nature-data` | Data Availability, source data, dataset citation, repository, restricted-data, or FAIR metadata work is needed | draft Nature-ready data availability and metadata material from verified records |
+| `nature-figure` | a Nature/high-impact-journal figure package is the deliverable | define the figure contract, backend, export plan, and QA path |
+| `nature-paper2ppt` | the requested deliverable is a PPT/PPTX from a scientific paper | build a Chinese paper-sharing or journal-club deck |
 
 ### 6.3 The important design point
 
@@ -376,6 +380,10 @@ These are the durable outputs you should expect:
 | `review` | review report, revision log, experiment TODO list |
 | `rebuttal` | review matrix, response letter, text deltas, evidence-update plan |
 | `figure-polish` | final polished figure assets and render-checked outputs |
+| `nature-polishing` | polished manuscript section plus unresolved evidence or claim-boundary notes |
+| `nature-data` | Data Availability statement, repository plan, dataset citation checklist, unresolved metadata fields |
+| `nature-figure` | figure contract, selected backend, exported figure assets, QA notes |
+| `nature-paper2ppt` | PPTX deck, extracted source figures/notes when needed, lightweight QA report |
 
 ## 8. Built-in MCP structure
 
@@ -502,6 +510,7 @@ The design rule is simple:
 
 - anything shell-like should go through `bash_exec`
 - do not hide important execution in transient shell snippets
+- for already running managed sessions, prefer bounded waits such as `bash_exec.bash_exec(mode='await', id=..., wait_timeout_seconds=1800)`; if the wait window ends first, the process keeps running and the next step should usually be reading logs rather than killing the session
 
 ## 9. How the three MCP namespaces divide responsibility