@researai/deepscientist 1.5.9 → 1.5.12

package/docs/en/00_QUICK_START.md

@@ -1,152 +1,379 @@
 # 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
+- one working Codex path:
+  - default OpenAI login path: `codex --login` (or `codex`)
+  - provider-backed path: one working Codex profile such as `minimax`, `glm`, `ark`, or `bailian`
+- 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
+
+If you plan to use a provider-backed Codex profile instead of the default OpenAI login flow, read this next:
+
+- [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
+
+## 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
+npm install -g @openai/codex
+```
+
+If you want local PDF compilation later, also run:
 
 ```bash
 ds latex install-runtime
 ```
 
-## 2. Start DeepScientist
+This installs a lightweight TinyTeX runtime for local paper compilation.
+
+## 2. Finish Codex Setup Before The First `ds`
+
+Choose one of these two paths.
 
-Start the local daemon and web workspace:
+### 2.1 Default OpenAI login path
+
+Run:
 
 ```bash
-ds
+codex --login
 ```
 
-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.
+If your Codex CLI version does not expose `--login`, run:
 
-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.
+```bash
+codex
+```
 
-By default, the DeepScientist home is `~/DeepScientist` on macOS and Linux, and `%USERPROFILE%\\DeepScientist` on Windows. You can override it with `ds --home <path>`.
+and finish the interactive authentication there.
 
-If you want to place the DeepScientist home under the current working directory, run:
+Then verify:
 
 ```bash
-ds --here
+ds doctor
 ```
 
-This is equivalent to `ds --home "$PWD/DeepScientist"`.
+### 2.2 Provider-backed Codex profile path
 
-If you install from a source checkout and want another default base path for the bundled CLI tree, use:
+If you already use a named Codex profile for MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another provider-backed path, verify that profile first in a terminal:
 
 ```bash
-bash install.sh --dir /data/DeepScientist
+codex --profile minimax
 ```
 
-If you already have a populated DeepScientist home and need to move it to another path later, use:
+Then run DeepScientist through the same profile:
 
 ```bash
-ds migrate /data/DeepScientist
+ds doctor --codex-profile minimax
 ```
 
-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.
+and later:
 
-By default, the web UI is served at:
+```bash
+ds --codex-profile minimax
+```
 
-```text
-http://127.0.0.1:20999
+Replace `minimax` with the real profile name you created, such as `m27`, `glm`, `ark`, or `bailian`.
+
+DeepScientist blocks startup until Codex can pass a real hello probe. By default, the runner model in `~/DeepScientist/config/runners.yaml` is `gpt-5.4`. If your profile expects the model to come from the profile itself, use `model: inherit` in `runners.yaml`, or simply launch with `--codex-profile <name>` and let that session inherit the profile-defined model.
+
+## 3. Start the Local Runtime
+
+Run:
+
+```bash
+ds
 ```
 
-If the browser does not open automatically, paste that address into your browser manually.
+This starts the local daemon and the web workspace.
+
+Again, strongly recommended:
+
+- 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.
 
-If you want another port:
+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 --port 21000
+ds --here
 ```
 
-If you want the web UI to bind on all interfaces:
+This is equivalent to `ds --home "$PWD/DeepScientist"`.
+
+If you want another port, run:
 
 ```bash
-ds --host 0.0.0.0 --port 21000
+ds --port 21000
 ```
 
-## 3. Understand the Home Page
+This keeps everything the same, but serves the web UI on port `21000`.
+
+By default, the local web UI is:
+
+```text
+http://127.0.0.1:20999
+```
+
+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`.
+
+The example task is:
 
-## 4. Create a New Project With Start Research
+- 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 launch dialog.
+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
 
-The most important fields are:
+Use these values:
 
-- `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
+| 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 |
 
-For a first test, keep it simple:
+### 5.2 Paste the main research request
 
-- write one clear research question
-- leave baseline empty unless you already have one
-- use `Balanced` or `Sprint`
-- keep decision mode on `Autonomous`
+Paste this into `Primary research request`:
 
-Then click the final `Start Research` action in the dialog.
+```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.
+```
+
+Why this is a good request:
+
+- 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
+
+### 5.3 Add the baseline and reference sources
+
+If this is your first run, leave `Reusable baseline` empty.
+
+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`
 
-## 5. Reopen an Existing Project With Open Project
+This matters because the dialog does not only create a project. It also writes a structured `startup_contract` that later prompt building keeps reading.
 
-Click `Open Project` on the home page to open the existing project list.
+### 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 +381,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

@@ -392,6 +392,7 @@ codex:
   enabled: true
   binary: codex
   config_dir: ~/.codex
+  profile: ""
   model: gpt-5.4
   model_reasoning_effort: xhigh
   approval_policy: on-request
@@ -429,6 +430,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`**
 
@@ -437,12 +440,23 @@ claude:
 - UI label: `Config directory`
 - Meaning: global runner home for auth and global config.
 
+**`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>`.
+
 **`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.
 
 **`model_reasoning_effort`**