@researai/deepscientist 1.5.9 → 1.5.11

package/docs/en/00_QUICK_START.md

@@ -1,152 +1,347 @@
 # 00 Quick Start: Launch DeepScientist and Run Your First Project
 
-This is the fastest way to go from installation to a running project.
+Think of DeepScientist as a local workspace for long-running research tasks. You define the task, prepare the resources it needs, and DeepScientist keeps the files, branches, notes, and results on your machine.
+
+This guide is written for first-time users. It is intentionally hands-on: one step, one action, one explanation.
 
 You will do four things:
 
 1. install DeepScientist
 2. start the local runtime
-3. create a new project from the home page
-4. reopen old projects from the project list
+3. open the home page
+4. create a real project with a worked example
 
 The screenshots in this guide use the current live web UI at `deepscientist.cc:20999` as an example. Your local UI at `127.0.0.1:20999` should look the same or very close.
 
-## 1. Install
+Current platform support: DeepScientist currently supports Linux and macOS only. Windows is not supported in the current release.
+
+## Safety First: Isolate Before You Start
+
+Before your first DeepScientist run, strongly adopt this baseline:
+
+- if your environment allows it, prefer Docker, a virtual machine, or an equivalent isolation boundary
+- always run DeepScientist under a non-root account
+- do not use a production host, critical server, or sensitive-data machine for the first run
+- do not casually share a `0.0.0.0` binding, reverse-proxy URL, or the web entry with other people
+- if you plan to bind WeChat, QQ, Lingzhu, or other connectors later, be even more conservative about public exposure
+
+The reason is simple: DeepScientist can execute commands, modify files, install dependencies, send external messages, and read or write project data. If you give it too much privilege, or expose it carelessly, the outcome can include server damage, data loss, secret leakage, connector misuse, or fabricated research outputs that are not caught in time.
+
+See the full notice here:
+
+- [11 License And Risk Notice](./11_LICENSE_AND_RISK.md)
+
+## 0. Before You Start
+
+Prepare these first:
+
+- Node.js `>=18.18` and npm `>=9`; install them from the official download page: https://nodejs.org/en/download
+- a working Codex CLI setup; before the first `ds`, run `codex --login` (or `codex`) and finish authentication
+- 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
+- code, data, or repository links if the task starts from an existing baseline
+- optionally, one connector such as QQ if you want updates outside the web workspace
+
+If you are still choosing a coding plan or subscription, these are practical starting points:
+
+- 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
+- GLM Coding Plan: https://docs.bigmodel.cn/cn/coding-plan/overview
+- 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
+
+## 1. Install Node.js and DeepScientist
+
+DeepScientist currently supports Linux and macOS only.
+
+Before installing DeepScientist itself, install Node.js from the official page:
+
+https://nodejs.org/en/download
 
-Install DeepScientist globally:
+Make sure your environment satisfies:
+
+- Node.js `>=18.18`
+- npm `>=9`
+
+Run:
 
 ```bash
 npm install -g @researai/deepscientist
 ```
 
-If you plan to compile LaTeX locally later, you can also install the lightweight PDF runtime:
+This installs the `ds` command globally.
+
+DeepScientist depends on a working Codex CLI. The npm package tries to bring the bundled Codex dependency with it, but if `codex` is still missing afterward, repair it explicitly:
 
 ```bash
-ds latex install-runtime
+npm install -g @openai/codex
 ```
 
-## 2. Start DeepScientist
-
-Start the local daemon and web workspace:
+If you want local PDF compilation later, also run:
 
 ```bash
-ds
+ds latex install-runtime
 ```
 
-DeepScientist now uses `uv` to manage a locked local Python runtime. If a conda environment is active and already provides Python `>=3.11`, `ds` will prefer that environment automatically. Otherwise `uv` will provision a managed Python under the DeepScientist home.
+This installs a lightweight TinyTeX runtime for local paper compilation.
+
+## 2. Finish Codex Setup Before The First `ds`
 
-If `uv` is missing on your machine, `ds` will bootstrap a local copy automatically during the first start. The npm package also ships with the Codex CLI dependency, so you do not need a separate `npm install -g @openai/codex`. You may still need to run `codex` once later to finish login.
+Run:
 
-By default, the DeepScientist home is `~/DeepScientist` on macOS and Linux, and `%USERPROFILE%\\DeepScientist` on Windows. You can override it with `ds --home <path>`.
+```bash
+codex --login
+```
 
-If you want to place the DeepScientist home under the current working directory, run:
+If your Codex CLI version does not expose `--login`, run:
 
 ```bash
-ds --here
+codex
 ```
 
-This is equivalent to `ds --home "$PWD/DeepScientist"`.
+and finish the interactive authentication there.
 
-If you install from a source checkout and want another default base path for the bundled CLI tree, use:
+Then verify the environment before startup:
 
 ```bash
-bash install.sh --dir /data/DeepScientist
+ds doctor
 ```
 
-If you already have a populated DeepScientist home and need to move it to another path later, use:
+DeepScientist blocks startup until Codex can pass a real hello probe. In the current release, that probe first tries the runner model configured in `~/DeepScientist/config/runners.yaml`, which defaults to `gpt-5.4`. If that model is unavailable to your Codex setup, DeepScientist falls back to the current Codex default model and persists `model: inherit` for future runs.
+
+## 3. Start the Local Runtime
+
+Run:
 
 ```bash
-ds migrate /data/DeepScientist
+ds
 ```
 
-The migration command prints the absolute source and target paths, stops the managed daemon, asks for a double confirmation, verifies the copied tree, updates launcher wrappers, and removes the old path only after the migration succeeds.
+This starts the local daemon and the web workspace.
 
-By default, the web UI is served at:
+Again, strongly recommended:
 
-```text
-http://127.0.0.1:20999
+- prefer Docker or another isolated environment
+- always run under a non-root user
+- do not expose the service publicly for your first run
+
+DeepScientist now uses `uv` to manage a locked local Python runtime. If a conda environment is already active and provides Python `>=3.11`, `ds` will prefer it. Otherwise it will bootstrap a managed Python under the DeepScientist home.
+
+By default, the DeepScientist home is:
+
+- macOS / Linux: `~/DeepScientist`
+
+If you want to place the DeepScientist home under the current working directory instead, run:
+
+```bash
+ds --here
 ```
 
-If the browser does not open automatically, paste that address into your browser manually.
+This is equivalent to `ds --home "$PWD/DeepScientist"`.
 
-If you want another port:
+If you want another port, run:
 
 ```bash
 ds --port 21000
 ```
 
-If you want the web UI to bind on all interfaces:
+This keeps everything the same, but serves the web UI on port `21000`.
 
-```bash
-ds --host 0.0.0.0 --port 21000
+By default, the local web UI is:
+
+```text
+http://127.0.0.1:20999
 ```
 
-## 3. Understand the Home Page
+If the browser does not open automatically, paste that address into your browser manually.
+
+## 4. Open the Home Page
 
 When DeepScientist starts, open the home page at `/`.
 
 ![DeepScientist home page](../images/quickstart/00-home.png)
 
-The home page is intentionally simple. The two main entry buttons are:
+After 12 hours of running, the projects surface will often look more like this:
+
+![DeepScientist projects surface](../assets/branding/projects.png)
+
+The two main entry points are:
 
 - `Start Research`: create a new project and launch a new research run
 - `Open Project`: reopen an existing project
 
-If you are using DeepScientist for the first time, start with `Start Research`.
+For your first run, click `Start Research`.
+
+## 5. Create Your First Project With A Worked Example
+
+This walkthrough uses a cleaned-up version of a real project input from quest `025`.
 
-## 4. Create a New Project With Start Research
+The example task is:
 
-Click `Start Research` to open the launch dialog.
+- 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
+
+Click `Start Research` to open the dialog.
 
 ![Start Research dialog](../images/quickstart/01-start-research.png)
 
-This dialog creates a new project repository and writes the startup contract for the agent.
+### 5.1 Fill the short identity fields first
+
+Use these values:
+
+| Field in the UI | Example value | Why |
+|---|---|---|
+| `Project title` | `Mandela-Effect Reproduction and Truth-Preserving Collaboration` | Short, clear, and easy to recognize later in the project list |
+| `Project ID` | leave blank, or enter `025` | Leave it blank if you want automatic sequential numbering; enter a fixed id only when you need one |
+| `Connector delivery` | `Local only` for the first run | Keep the first run simple; if QQ or another connector is already configured, you can bind one target here |
+
+### 5.2 Paste the main research request
 
-The most important fields are:
+Paste this into `Primary research request`:
 
-- `Project ID`: usually auto-generated in sequence such as `00`, `01`, `02`
-- `Primary request` / research goal: the actual scientific task you want the agent to work on
-- `Reuse Baseline`: optional; choose an existing baseline if you want to continue from an earlier result
-- `Research intensity`: how aggressive the run should be
-- `Decision mode`: `Autonomous` means the agent should keep going by itself unless a true approval is needed
-- `Research paper`: choose whether the run should also aim to produce paper-style output
-- `Language`: choose the user-facing language for the run
+```text
+Please reproduce the official Mandela-Effect repository and paper, then study how to improve truth-preserving collaboration under mixed correct and incorrect social signals.
+
+The core research question is: how can a multi-agent system remain factually robust under social influence while still learning from correct peers?
+
+Keep the task definition and evaluation protocol aligned with the original work. Focus on prompt-based or system-level methods that improve truth preservation without simply refusing all social information.
+```
 
-For a first test, keep it simple:
+Why this is a good request:
 
-- write one clear research question
-- leave baseline empty unless you already have one
-- use `Balanced` or `Sprint`
-- keep decision mode on `Autonomous`
+- it states the baseline to reproduce
+- it names the research question explicitly
+- it gives a boundary: stay on the same task and protocol
+- it hints at promising directions without over-prescribing the implementation
 
-Then click the final `Start Research` action in the dialog.
+### 5.3 Add the baseline and reference sources
 
-## 5. Reopen an Existing Project With Open Project
+If this is your first run, leave `Reusable baseline` empty.
 
-Click `Open Project` on the home page to open the existing project list.
+If you already imported a reusable official baseline into the registry, select it here instead. That lets DeepScientist attach the trusted baseline directly.
+
+Paste this into `Baseline links`:
+
+```text
+https://github.com/bluedream02/Mandela-Effect
+```
+
+Paste this into `Reference papers / repos`:
+
+```text
+https://arxiv.org/abs/2602.00428
+```
+
+These fields tell DeepScientist where the baseline comes from and what prior work defines the task.
+
+### 5.4 Add the runtime constraints
+
+Paste this into `Runtime constraints`:
+
+```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.
+- 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.
+- Record failed, degraded, or inconclusive runs honestly instead of hiding them.
+```
+
+This is one of the most important fields in the whole dialog. It turns vague operational wishes into hard project rules.
+
+### 5.5 Add the goals
+
+Paste this into `Goals`:
+
+```text
+1. Restore and verify the official Mandela-Effect baseline as a trustworthy starting point.
+2. Measure key metrics and failure modes on the designated `gpt-oss-120b` setup.
+3. Propose at least one literature-grounded direction for stronger truth-preserving collaboration.
+4. Produce experiment and analysis artifacts that are strong enough to support paper writing.
+```
+
+This field should describe the outcomes of the first meaningful research cycle, not a vague aspiration like “do something new”.
+
+### 5.6 Choose the policy fields
+
+For this example, use these settings:
+
+| Field in the UI | Example value | What it means |
+|---|---|---|
+| `Research paper` | `On` | The project should continue through analysis and paper-ready outputs |
+| `Research intensity` | `Balanced` | Secure the baseline first, then test one justified direction |
+| `Decision mode` | `Autonomous` | The run should keep moving unless a real user decision is needed |
+| `Launch mode` | `Standard` | Start from the ordinary research graph |
+| `Language` | `English` | Use English for the kickoff prompt and user-facing artifacts by default |
+
+What the frontend derives automatically from these choices:
+
+- `scope = baseline_plus_direction`
+- `baseline_mode = restore_from_url` if no reusable baseline is selected
+- `baseline_mode = existing` if a reusable baseline is selected
+- `resource_policy = balanced`
+- `time_budget_hours = 24`
+- `git_strategy = semantic_head_plus_controlled_integration`
+
+This matters because the dialog does not only create a project. It also writes a structured `startup_contract` that later prompt building keeps reading.
+
+### 5.7 Review the preview, then create the project
+
+Look at the prompt preview on the right before you click `Create project`.
+
+Check that it clearly includes:
+
+- the primary research request
+- the baseline repository
+- the reference paper
+- the runtime constraints
+- the goals
+- the chosen delivery and decision mode
+
+When it looks right, click `Create project`.
+
+At this point, the frontend submits:
+
+- a compiled kickoff prompt
+- an optional `requested_baseline_ref`
+- an optional `requested_connector_bindings`
+- a structured `startup_contract`
+
+If you want to understand that payload in detail, read [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md).
+
+## 6. Reopen an Existing Project
+
+Click `Open Project` on the home page to open the project list.
 
 ![Open Project dialog](../images/quickstart/02-list-quest.png)
 
-Use this dialog when you want to:
+Use this when you want to:
 
-- reopen a project that is already running or already finished
-- search by project title or project id
-- jump back into a previous workspace quickly
+- reopen a running project
+- reopen a finished project
+- search by project title or id
 
-Each row corresponds to one project repository. Click a project card to open it.
+Each row is one project repository. Click the card to open it.
 
-## 6. What Happens After Opening a Project
+## 7. What Happens After Opening a Project
 
 After you create or open a project, DeepScientist takes you to the workspace page for that project.
 
-Inside the workspace, the usual flow is:
+The usual first loop is:
 
-1. watch agent progress in Copilot / Studio
+1. watch progress in Copilot / Studio
 2. inspect files, notes, and generated artifacts
-3. use Canvas to understand the current project graph and stage progress
-4. stop the run only when you intentionally want to interrupt it
+3. use Canvas to understand the project graph and stage progress
+4. let the run continue unless you intentionally want to interrupt it
 
-## 7. Useful Runtime Commands
+## 8. Useful Runtime Commands
 
 Check status:
 
@@ -154,21 +349,64 @@ Check status:
 ds --status
 ```
 
-Stop the current local daemon:
+This shows whether the local runtime is up.
+
+Stop the daemon:
 
 ```bash
 ds --stop
 ```
 
-Run diagnostics if something looks broken:
+This stops the local DeepScientist daemon.
+
+Run diagnostics:
 
 ```bash
 ds doctor
 ```
 
-## 8. What To Read Next
+Use this when startup, config, runner, or connector behavior looks wrong.
+
+## 9. What To Read Next
+
+- [DeepScientist Docs Index](./README.md)
+- [12 Guided Workflow Tour](./12_GUIDED_WORKFLOW_TOUR.md)
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [13 Core Architecture Guide](./13_CORE_ARCHITECTURE_GUIDE.md)
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [03 QQ Connector Guide](./03_QQ_CONNECTOR_GUIDE.md)
+- [05 TUI Guide](./05_TUI_GUIDE.md)
+
+## 10. Short FAQ
+
+### How do I install from a source checkout into another base directory?
+
+Run:
+
+```bash
+bash install.sh --dir /data/DeepScientist
+```
+
+Use this when you are working from a repository checkout but want the bundled CLI installed into a separate runtime location.
+
+### How do I move an existing DeepScientist home safely?
+
+Run:
+
+```bash
+ds migrate /data/DeepScientist
+```
+
+This is the supported way to migrate an existing DeepScientist home to a new path.
+
+### How do I bind on all interfaces?
+
+Run:
+
+```bash
+ds --host 0.0.0.0 --port 21000
+```
+
+Only do this when you really need external reachability, and review the risk notice first:
 
-- [01 Settings Reference: Configure DeepScientist](./01_SETTINGS_REFERENCE.md)
-- [02 Start Research Guide: Fill the Start Research Contract](./02_START_RESEARCH_GUIDE.md)
-- [03 QQ Connector Guide: Use QQ With DeepScientist](./03_QQ_CONNECTOR_GUIDE.md)
-- [05 TUI Guide: Use the Terminal Interface](./05_TUI_GUIDE.md)
+- [11 License And Risk Notice](./11_LICENSE_AND_RISK.md)

package/docs/en/01_SETTINGS_REFERENCE.md

@@ -429,6 +429,8 @@ claude:
 - UI label: `Binary`
 - Meaning: command name or absolute path used to launch the runner.
 - `Test` behavior: checks whether the binary is on `PATH`.
+- First-run note: DeepScientist does not finish Codex authentication for you. Before the first `ds`, make sure `codex --login` (or `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`.
 
 **`config_dir`**
 
@@ -443,6 +445,7 @@ claude:
 - 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`.
 
 **`model_reasoning_effort`**
 

package/docs/en/02_START_RESEARCH_GUIDE.md

@@ -16,6 +16,92 @@ Implementation sources:
 3. binds an optional reusable baseline
 4. persists a structured `startup_contract` for later prompt building
 
+## Worked example: a cleaned-up version of quest 025
+
+The quickest way to understand the dialog is to walk through a real example.
+
+This example is adapted from a real project input in quest `025`, but normalized into a cleaner public form. The task is:
+
+- reproduce the official Mandela-Effect baseline
+- keep the original task and evaluation protocol
+- study stronger truth-preserving collaboration under mixed correct and incorrect social signals
+- use two local OpenAI-compatible endpoints to keep throughput high
+
+### Short fields in the current frontend
+
+| Field in the dialog | Example value | Why |
+|---|---|---|
+| `Project title` | `Mandela-Effect Reproduction and Truth-Preserving Collaboration` | Clear project title for cards, workspace headers, and later search |
+| `Project ID` | leave blank, or set `025` | Leave blank for automatic sequential ids; only pin it manually if you need a fixed id |
+| `Connector delivery` | `Local only` for the first run, or one QQ target if already configured | The current frontend allows at most one external connector target per quest |
+| `Reusable baseline` | empty for the first run, or the imported official baseline if already available | If selected, derived `baseline_mode` becomes `existing` |
+| `Research paper` | `On` | Keep paper-oriented analysis and writing in scope |
+| `Research intensity` | `Balanced` | Secure the baseline, then probe one justified direction |
+| `Decision mode` | `Autonomous` | Keep moving unless a real blocking decision depends on the user |
+| `Launch mode` | `Standard` | Start from the ordinary research graph |
+| `Language` | `English` | Use English for the kickoff prompt and user-facing artifacts |
+
+### Multi-line fields for the same example
+
+`Primary research request`
+
+```text
+Please reproduce the official Mandela-Effect repository and paper, then study how to improve truth-preserving collaboration under mixed correct and incorrect social signals.
+
+The core research question is: how can a multi-agent system remain factually robust under social influence while still learning from correct peers?
+
+Keep the task definition and evaluation protocol aligned with the original work. Focus on prompt-based or system-level methods that improve truth preservation without simply refusing all social information.
+```
+
+`Baseline links`
+
+```text
+https://github.com/bluedream02/Mandela-Effect
+```
+
+`Reference papers / repos`
+
+```text
+https://arxiv.org/abs/2602.00428
+```
+
+`Runtime constraints`
+
+```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.
+- 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.
+- Record failed, degraded, or inconclusive runs honestly instead of hiding them.
+```
+
+`Goals`
+
+```text
+1. Restore and verify the official Mandela-Effect baseline as a trustworthy starting point.
+2. Measure key metrics and failure modes on the designated `gpt-oss-120b` setup.
+3. Propose at least one literature-grounded direction for stronger truth-preserving collaboration.
+4. Produce experiment and analysis artifacts that are strong enough to support paper writing.
+```
+
+### What the frontend derives from this example
+
+If you leave `Reusable baseline` empty and choose `Balanced`, the current frontend derives:
+
+- `scope = baseline_plus_direction`
+- `baseline_mode = restore_from_url`
+- `resource_policy = balanced`
+- `time_budget_hours = 24`
+- `git_strategy = semantic_head_plus_controlled_integration`
+
+If you select a reusable baseline entry, only one derived field changes:
+
+- `baseline_mode = existing`
+
 ## Current frontend model
 
 ### `StartResearchTemplate`
@@ -75,6 +161,12 @@ The dialog submits:
   title,
   goal: compiled_prompt,
   quest_id,
+  requested_connector_bindings: [
+    {
+      connector,
+      conversation_id
+    }
+  ],
   requested_baseline_ref: {
     baseline_id,
     variant_id
@@ -130,6 +222,26 @@ The dialog submits:
 
 - Declares the preferred user-facing language for kickoff and later interaction.
 
+### Connector delivery
+
+**`requested_connector_bindings`**
+
+- Submitted alongside the project create payload, not inside `startup_contract`.
+- The current frontend allows at most one external connector target per quest.
+- Typical shape:
+
+```ts
+[
+  {
+    connector: 'qq',
+    conversation_id: 'qq:private:openid-123'
+  }
+]
+```
+
+- If you keep the project local-only, this array is empty.
+- If the selected target is already bound to another quest, rebinding this project will replace the old binding.
+
 ### Baseline and references
 
 **`baseline_id`**