@researai/deepscientist 1.5.11 → 1.5.13

package/docs/en/00_QUICK_START.md

@@ -36,7 +36,9 @@ See the full notice here:
 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
+- 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
@@ -52,6 +54,10 @@ If you are still choosing a coding plan or subscription, these are practical sta
 - 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.
@@ -73,7 +79,7 @@ npm install -g @researai/deepscientist
 
 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:
+DeepScientist depends on a working Codex CLI. It prefers the `codex` already available on your machine and only falls back to the bundled npm dependency when no local Codex path is available. If `codex` is still missing afterward, repair it explicitly:
 
 ```bash
 npm install -g @openai/codex
@@ -89,6 +95,10 @@ This installs a lightweight TinyTeX runtime for local paper compilation.
 
 ## 2. Finish Codex Setup Before The First `ds`
 
+Choose one of these two paths.
+
+### 2.1 Default OpenAI login path
+
 Run:
 
 ```bash
@@ -103,13 +113,54 @@ codex
 
 and finish the interactive authentication there.
 
-Then verify the environment before startup:
+Then verify:
 
 ```bash
 ds doctor
 ```
 
-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.
+### 2.2 Provider-backed Codex profile path
+
+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
+codex --profile m27
+```
+
+Then run DeepScientist through the same profile:
+
+```bash
+ds doctor --codex-profile m27
+```
+
+and later:
+
+```bash
+ds --codex-profile m27
+```
+
+If you need one specific Codex binary for this run, add `--codex` too:
+
+```bash
+ds doctor --codex /absolute/path/to/codex --codex-profile m27
+ds --codex /absolute/path/to/codex --codex-profile m27
+```
+
+`m27` is the MiniMax profile name used consistently in this repo. MiniMax's own page currently uses `m21`, but the profile name is only a local alias; if you created a different name, use that same name in all commands.
+
+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.
+
+MiniMax note:
+
+- if the current `@openai/codex` latest does not work with MiniMax, install `npm install -g @openai/codex@0.57.0`
+- create a MiniMax `Coding Plan Key` first
+- clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
+- use `https://api.minimaxi.com/v1`
+- the `codex-MiniMax-*` model names shown on MiniMax's current Codex CLI page did not pass reliably through Codex CLI in local testing with the provided key
+- the locally verified working model name is `MiniMax-M2.7`
+- DeepScientist can auto-adapt MiniMax's profile-only `model_provider` / `model` config shape during probe and runtime
+- if you also want plain terminal `codex --profile <name>` to work directly, add `model_provider = "minimax"` and `model = "MiniMax-M2.7"` at the top level of `~/.codex/config.toml`
+- DeepScientist automatically downgrades `xhigh` to `high` when it detects an older Codex CLI that does not support `xhigh`
 
 ## 3. Start the Local Runtime
 

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`.
+- 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 `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`.
 
@@ -439,6 +442,16 @@ 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>`.
+- Combined note: one-off profile and binary overrides can be combined as `ds --codex /absolute/path/to/codex --codex-profile <name>`.
+
 **`model`**
 
 - Type: `string`
@@ -446,6 +459,7 @@ claude:
 - 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`**
 
@@ -454,6 +468,7 @@ claude:
 - UI label: `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`**
 

package/docs/en/02_START_RESEARCH_GUIDE.md

@@ -115,13 +115,21 @@ type StartResearchTemplate = {
   baseline_variant_id: string
   baseline_urls: string
   paper_urls: string
+  review_materials: string
   runtime_constraints: string
   objectives: string
   need_research_paper: boolean
   research_intensity: 'light' | 'balanced' | 'sprint'
   decision_policy: 'autonomous' | 'user_gated'
   launch_mode: 'standard' | 'custom'
-  custom_profile: 'continue_existing_state' | 'revision_rebuttal' | 'freeform'
+  custom_profile: 'continue_existing_state' | 'review_audit' | 'revision_rebuttal' | 'freeform'
+  review_followup_policy: 'audit_only' | 'auto_execute_followups' | 'user_gated_followups'
+  baseline_execution_policy:
+    | 'auto'
+    | 'must_reproduce_or_verify'
+    | 'reuse_existing_only'
+    | 'skip_unless_blocking'
+  manuscript_edit_mode: 'none' | 'copy_ready_text' | 'latex_required'
   entry_state_summary: string
   review_summary: string
   custom_brief: string
@@ -179,6 +187,9 @@ The dialog submits:
     decision_policy,
     launch_mode,
     custom_profile,
+    review_followup_policy,
+    baseline_execution_policy,
+    manuscript_edit_mode,
     scope,
     baseline_mode,
     resource_policy,
@@ -188,6 +199,7 @@ The dialog submits:
     objectives: string[],
     baseline_urls: string[],
     paper_urls: string[],
+    review_materials: string[],
     entry_state_summary,
     review_summary,
     custom_brief,
@@ -256,12 +268,18 @@ The dialog submits:
 
 **`baseline_urls`**
 
-- Fallback source links when there is no registered reusable baseline.
+- Fallback source links or absolute local file/folder paths when there is no registered reusable baseline.
 - Submitted as `string[]`.
 
 **`paper_urls`**
 
-- Papers, repos, benchmarks, or leaderboards that shape early scouting.
+- Papers, repos, manuscripts, benchmarks, leaderboards, or absolute local file/folder paths that shape early scouting or writing work.
+- Submitted as `string[]`.
+
+**`review_materials`**
+
+- Only meaningful for `review_audit` or `revision_rebuttal`.
+- Use one URL or one absolute local file/folder path per line for reviewer comments, decision letters, meta-review notes, or revision packets.
 - Submitted as `string[]`.
 
 ### Constraints and objectives
@@ -317,12 +335,49 @@ Only meaningful when `launch_mode = custom`.
 - `continue_existing_state`
   - start by auditing existing baselines, results, drafts, or mixed project assets
   - prompt builder should steer the agent toward `intake-audit`
+- `review_audit`
+  - start from a substantial draft or paper package that needs an independent skeptical audit
+  - prompt builder should steer the agent toward `review`
 - `revision_rebuttal`
   - start from reviewer comments, revision packets, or a rebuttal task
   - prompt builder should steer the agent toward `rebuttal`
 - `freeform`
+  - use this as the “Other” path
   - follow a custom brief with minimal forced workflow assumptions
 
+**`baseline_execution_policy`**
+
+- Only meaningful when `launch_mode = custom`.
+- `auto`
+  - let the startup contract and current evidence decide
+- `must_reproduce_or_verify`
+  - verify or recover the rebuttal-critical baseline/comparator before reviewer-linked follow-up work
+- `reuse_existing_only`
+  - trust the current baseline/results unless they are inconsistent or unusable
+- `skip_unless_blocking`
+  - skip baseline reruns unless a named review/rebuttal item truly depends on a missing comparator
+
+**`review_followup_policy`**
+
+- Mainly meaningful for `review_audit`.
+- `audit_only`
+  - stop after the audit artifacts and route recommendation
+- `auto_execute_followups`
+  - continue automatically into the justified experiments and manuscript deltas after the audit
+- `user_gated_followups`
+  - finish the audit first, then ask for approval before expensive follow-up work
+
+**`manuscript_edit_mode`**
+
+- Mainly meaningful for `review_audit` and `revision_rebuttal`.
+- `none`
+  - planning artifacts only
+- `copy_ready_text`
+  - produce section-level revision text that is ready to paste into the manuscript
+- `latex_required`
+  - prefer the provided LaTeX tree as the writing surface and produce LaTeX-ready replacement text
+  - if you choose this mode, it is best to provide the LaTeX source tree via local path / folder input
+
 **`entry_state_summary`**
 
 - Plain-language summary of what already exists.
@@ -378,6 +433,9 @@ Custom launch behavior is explicit:
 - `custom + continue_existing_state`
   - tells the agent to audit and normalize existing assets first
   - explicitly prefers `intake-audit`
+- `custom + review_audit`
+  - tells the agent that the current draft/paper state is the active contract
+  - explicitly prefers `review`
 - `custom + revision_rebuttal`
   - tells the agent to interpret reviewer comments and current paper state first
   - explicitly prefers `rebuttal`
@@ -477,6 +535,9 @@ Custom launch behavior is explicit:
     "decision_policy": "user_gated",
     "launch_mode": "custom",
     "custom_profile": "revision_rebuttal",
+    "review_followup_policy": "audit_only",
+    "baseline_execution_policy": "skip_unless_blocking",
+    "manuscript_edit_mode": "latex_required",
     "scope": "baseline_plus_direction",
     "baseline_mode": "restore_from_url",
     "resource_policy": "balanced",
@@ -490,6 +551,9 @@ Custom launch behavior is explicit:
     ],
     "baseline_urls": [],
     "paper_urls": [],
+    "review_materials": [
+      "/absolute/path/to/review-comments.md"
+    ],
     "entry_state_summary": "A draft and previous experiment outputs already exist.",
     "review_summary": "Reviewers asked for one stronger ablation, one extra baseline, and a clearer limitation paragraph.",
     "custom_brief": "Treat the current manuscript and review packet as the active contract."
@@ -500,7 +564,7 @@ Custom launch behavior is explicit:
 ## Operational implications
 
 - The startup contract is durable project state, not only UI state.
-- Prompt building later reads `launch_mode`, `custom_profile`, and related summaries again.
+- Prompt building later reads `launch_mode`, `custom_profile`, `review_followup_policy`, `baseline_execution_policy`, `manuscript_edit_mode`, `entry_state_summary`, `review_summary`, `review_materials`, and `custom_brief` again.
 - This means `Start Research` shapes not just the first turn, but later routing decisions too.
 
 ## Validation checklist

package/docs/en/09_DOCTOR.md

@@ -10,20 +10,26 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    npm install -g @researai/deepscientist
    ```
 
-2. Make sure Codex is installed and authenticated:
+2. Make sure Codex itself is working first:
+
+   Default OpenAI path:
 
    ```bash
    codex --login
    ```
 
+   Provider-backed profile path:
+
+   ```bash
+   codex --profile m27
+   ```
+
    If `codex` is missing, repair it explicitly with:
 
    ```bash
    npm install -g @openai/codex
    ```
 
-   If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
-
 3. Try to start DeepScientist:
 
    ```bash
@@ -57,7 +63,7 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 
 ### Codex is missing
 
-Run the package install again so the bundled Codex dependency is present:
+DeepScientist prefers the `codex` already available on your machine and only uses the bundled dependency as fallback. If neither is present, run the package install again so the bundled Codex dependency is present:
 
 ```bash
 npm install -g @researai/deepscientist
@@ -81,6 +87,42 @@ If your Codex CLI version does not expose `--login`, run `codex` and finish the
 
 Finish login once, then rerun `ds doctor`.
 
+### Codex profile works in the terminal, but DeepScientist still fails
+
+Run DeepScientist with the same profile explicitly:
+
+```bash
+ds doctor --codex-profile m27
+ds --codex-profile m27
+```
+
+If your working Codex CLI is not the one on `PATH`, point DeepScientist at it explicitly:
+
+```bash
+ds doctor --codex /absolute/path/to/codex --codex-profile m27
+ds --codex /absolute/path/to/codex --codex-profile m27
+```
+
+`m27` is the MiniMax profile name used consistently in this repo. MiniMax's own page currently uses `m21`, but the profile name is only a local alias; if you created a different name, use that same name in both commands.
+
+Also check:
+
+- the same shell still exports the provider API key
+- the profile points at the provider's Coding Plan endpoint, not the generic API endpoint
+- `~/DeepScientist/config/runners.yaml` uses `model: inherit` if the provider expects the model to come from the profile itself
+
+MiniMax-specific note:
+
+- if MiniMax fails on the current `@openai/codex` latest, install `npm install -g @openai/codex@0.57.0`
+- create a MiniMax `Coding Plan Key` first
+- clear `OPENAI_API_KEY` and `OPENAI_BASE_URL` in the current shell before exporting `MINIMAX_API_KEY`
+- use `https://api.minimaxi.com/v1`
+- the `codex-MiniMax-*` model names shown on MiniMax's current Codex CLI page did not pass reliably through Codex CLI in local testing with the provided key
+- the locally verified working model name is `MiniMax-M2.7`
+- DeepScientist can auto-adapt MiniMax's profile-only `model_provider` / `model` config shape during probe and runtime
+- if you also want plain terminal `codex --profile <name>` to work directly, put `model_provider = "minimax"` and `model = "MiniMax-M2.7"` at the top level of `~/.codex/config.toml`
+- DeepScientist automatically downgrades `xhigh` to `high` when it detects a Codex CLI older than `0.63.0`
+
 ### The configured Codex model is unavailable
 
 DeepScientist blocks startup until Codex passes a real startup hello probe. In the current release, that probe first uses the runner model configured in:
@@ -95,6 +137,8 @@ The default is `gpt-5.4`. If your Codex account or CLI config cannot access that
 ds doctor
 ```
 
+For provider-backed Codex profiles, `model: inherit` is usually the right default.
+
 ### `uv` is missing
 
 Normally `ds` will bootstrap a local `uv` automatically. If that bootstrap fails, install it manually:

package/docs/en/12_GUIDED_WORKFLOW_TOUR.md

@@ -118,12 +118,12 @@ Good pattern:
 
 Use these fields to reduce ambiguity before the first round starts.
 
-Put repositories in `Baseline links` when:
+Put repositories or absolute local file/folder paths in `Baseline links` when:
 
 - the quest should restore a known repo
 - the baseline must come from a specific official implementation
 
-Put papers or important external references in `Reference papers / repos` when:
+Put papers, manuscript paths, or important external references in `Paper / reference sources` when:
 
 - the task is defined by a paper
 - the expected protocol comes from prior work
@@ -131,6 +131,9 @@ Put papers or important external references in `Reference papers / repos` when:
 
 If you already know the baseline and paper, do not hide them in the main request. Put them in the dedicated fields.
 
+These reference fields are not web-only.
+You can use network links, absolute local file paths, or absolute local folder paths.
+
 ### 4.5 Reusable baseline
 
 Use this only when you already imported a trusted reusable baseline into the registry.
@@ -177,6 +180,22 @@ Why these defaults are usually correct:
 - `Standard` keeps the workflow on the ordinary path
 - `Research paper = On` keeps analysis and writing in scope
 
+If you switch `Launch mode` to `Custom`, choose the custom task type explicitly:
+
+- `Continue existing state`
+  - for reuse-first work on an existing quest state
+- `Review`
+  - for an independent skeptical audit of a substantial draft or paper package
+- `Rebuttal / revision`
+  - for reviewer-driven work where comments must be mapped into experiments, manuscript deltas, and a response letter
+- `Other / freeform`
+  - for everything else that does not fit the standard custom types
+
+If you choose `Review`, also decide:
+
+- whether the system should stop after the audit or continue automatically into follow-up experiments and manuscript updates
+- whether manuscript-facing output should be ordinary copy-ready text or LaTeX-ready text
+
 ### 4.8 Runtime constraints
 
 Use this field for hard rules, not wishes.