@researai/deepscientist 1.5.9 → 1.5.12

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`
@@ -29,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
@@ -75,6 +169,12 @@ The dialog submits:
   title,
   goal: compiled_prompt,
   quest_id,
+  requested_connector_bindings: [
+    {
+      connector,
+      conversation_id
+    }
+  ],
   requested_baseline_ref: {
     baseline_id,
     variant_id
@@ -87,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,
@@ -96,6 +199,7 @@ The dialog submits:
     objectives: string[],
     baseline_urls: string[],
     paper_urls: string[],
+    review_materials: string[],
     entry_state_summary,
     review_summary,
     custom_brief,
@@ -130,6 +234,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`**
@@ -144,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
@@ -205,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.
@@ -266,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`
@@ -365,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",
@@ -378,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."
@@ -388,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/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -1,216 +1,99 @@
-# 04 Lingzhu Connector Guide: Configure Lingzhu for DeepScientist
+# 04 Lingzhu Connector Guide: Bind Rokid Glasses to DeepScientist
 
-This guide explains how to configure the Lingzhu companion endpoint from `Settings > Connectors > Lingzhu`.
+Lingzhu now uses a minimal one-step binding flow.
 
-Scope:
+DeepScientist serves the Lingzhu-compatible routes directly on its own daemon / web port:
 
-- configuration only
-- OpenClaw-compatible Lingzhu bridge values
-- local probe and SSE smoke test
-- what to paste into the Lingzhu platform
+- `GET /metis/agent/api/health`
+- `POST /metis/agent/api/sse`
 
-This guide does not cover cloud deployment architecture. You only need one working OpenClaw gateway and one public IP or public domain that the glasses can reach.
+For a real device binding, the address registered on Rokid must be the public DeepScientist address that external devices can reach. It cannot be `127.0.0.1`, `localhost`, or a private-network address.
 
-Reference sources:
+References:
 
-- Rokid forum setup page: https://forum.rokid.com/post/detail/2831
-- packaged bridge root: `assets/connectors/lingzhu/openclaw-bridge`
-- packaged OpenClaw config template: `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+- Rokid developer forum: https://forum.rokid.com/post/detail/2831
+- Rokid agent platform: https://agent-develop.rokid.com/space
 
-## 1. What DeepScientist now provides
+## 1. Prerequisites
 
-The Lingzhu settings card now generates and validates:
+Make sure:
 
-- local health URL
-- local SSE URL
-- public SSE URL
-- `auth_ak`
-- OpenClaw config snippet
-- local probe `curl`
+- DeepScientist is already running
+- the DeepScientist page you opened is the final public address that external devices should use
+- if the current page is local-only or private-network-only, Lingzhu should not be saved yet
 
-The packaged bridge is configured to:
+## 2. What the UI keeps now
 
-- emit one immediate visible receipt acknowledgement before the model starts
-- keep comment heartbeats alive
-- emit lightweight visible progress heartbeats during long silent upstream phases
+`Settings > Connectors > Lingzhu` now keeps only the necessary pieces:
 
-DeepScientist treats Lingzhu as a companion endpoint, not as a full bidirectional chat connector like QQ.
+- one `Add Lingzhu (Rokid Glasses)` entry point
+- the Rokid platform screenshot
+- the auto-generated copyable fields
+- concise binding instructions
+- one save action
 
-## 2. Before you start
+You no longer need to manually edit host, port, agent, OpenClaw snippets, or extra probe steps in the main flow.
 
-Make sure these are already true:
+## 3. What is auto-generated
 
-- DeepScientist is installed and running
-- your OpenClaw gateway is already running locally
-- the OpenClaw HTTP gateway port is known, usually `18789`
-- you have a public IP or public domain
+After you click `Add Lingzhu (Rokid Glasses)`, the popup shows these copyable values:
 
-Important:
+- Custom agent ID
+- Custom agent URL
+- Custom agent AK
+- Agent name
+- Category
+- Capability summary
+- Opening message
+- Input type
+- Icon PNG URL
 
-- `127.0.0.1` only works for local health checks
-- Lingzhu devices need a public address
+Important details:
 
-## 3. Open the settings page
+- `Custom agent URL` is generated as `https://<your-public-address>/metis/agent/api/sse`
+- `AK` is generated automatically and reused after saving
+- the logo uses a PNG DeepScientist asset so it can be uploaded directly to Rokid
 
-Open:
+![Rokid third-party agent creation form](../images/lingzhu/rokid-agent-platform-create.png)
 
-- `Settings > Connectors > Lingzhu`
+## 4. What the user does
 
-The card is organized into:
+On the Rokid platform:
 
-- gateway endpoint
-- auth and identity
-- generated values
-- probe and verify
-- advanced debug
+1. Open `Project Development -> Third-party Agent -> Create`
+2. Choose `Custom Agent`
+3. Copy each generated field from the popup into the matching Rokid field
+4. Upload the DeepScientist PNG logo
+5. Return to DeepScientist and click Save
 
-![Lingzhu settings overview](../images/lingzhu/lingzhu-settings-overview.svg)
+After Save, the Lingzhu binding is complete.
 
-## 4. Fill the endpoint fields
+## 5. How it is used afterward
 
-Recommended values:
+The glasses or platform only need to call:
 
-| Field | Recommended value | Notes |
-| --- | --- | --- |
-| `Enabled` | `true` | turn on the companion config |
-| `Transport` | `openclaw_sse` | fixed, do not change |
-| `Local host` | `127.0.0.1` | used only for local probe |
-| `Gateway port` | `18789` | match your OpenClaw gateway |
-| `Public base URL` | `http://<public-ip>:18789` | must be reachable from the glasses |
+- `POST /metis/agent/api/sse`
 
-If you do not know what to fill for the local endpoint, click:
+with:
 
-- `Use local defaults`
+- `Authorization: Bearer <saved-AK>`
 
-## 5. Generate the AK and identity values
+Usage rules:
 
-Fill or keep:
+- a new task must start with `我现在的任务是 ...`
+- only the text after that prefix is treated as a fresh DeepScientist task
+- if you only want buffered progress, do not repeat the prefix; just say `找DeepScientist` or `继续`
 
-| Field | Recommended value |
-| --- | --- |
-| `Auth AK` | click `Generate AK` |
-| `Agent ID` | `main` |
-| `Lingzhu system prompt` | optional |
+## 6. Common questions
 
-Use the same `auth_ak` and `agent_id` in both places:
+### Why can’t I use `127.0.0.1`?
 
-- OpenClaw Lingzhu plugin config
-- Lingzhu platform config
+Because Rokid and external devices cannot reach your local loopback address. Lingzhu must register a public address.
 
-## 6. Use the generated values
+### Why is `AK` generated automatically?
 
-DeepScientist shows the exact values you need:
+Because `AK` is the Bearer secret for this external entrypoint. Generating and persisting it is safer and more reliable than asking users to type it manually.
 
-- local health URL
-- local SSE URL
-- public SSE URL
-- OpenClaw config snippet
-- probe curl
+### Do I still need to tune a lot of extra parameters after saving?
 
-The public value is the one you should paste into the Lingzhu platform.
-
-![Lingzhu platform values](../images/lingzhu/lingzhu-platform-values.svg)
-
-## 7. Update OpenClaw
-
-Use either:
-
-- the generated snippet in the settings page
-- or the packaged template at `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
-
-Install the packaged bridge with:
-
-```bash
-openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
-```
-
-At minimum, OpenClaw must expose:
-
-```json
-{
-  "gateway": {
-    "port": 18789,
-    "http": {
-      "endpoints": {
-        "chatCompletions": {
-          "enabled": true
-        }
-      }
-    }
-  }
-}
-```
-
-DeepScientist also generates the full Lingzhu plugin block for you:
-
-![OpenClaw config snippet](../images/lingzhu/lingzhu-openclaw-config.svg)
-
-## 8. Run the local probe
-
-After saving the values, click:
-
-- `Run Lingzhu probe`
-
-DeepScientist performs:
-
-1. `GET /metis/agent/api/health`
-2. `POST /metis/agent/api/sse`
-
-Expected result:
-
-- `Connection = reachable`
-- `Auth = ready`
-- probe result returns no errors
-
-## 9. What to paste into the Lingzhu platform
-
-Use:
-
-- `Public SSE URL`
-- `Auth AK`
-
-Do not paste:
-
-- `127.0.0.1`
-- any local-only host name
-
-## 10. Common failure causes
-
-### Health is offline
-
-Usually means:
-
-- OpenClaw is not running
-- wrong `gateway_port`
-- wrong `local_host`
-
-### SSE probe fails
-
-Usually means:
-
-- `auth_ak` mismatch
-- Lingzhu endpoint path is not exposed
-- OpenClaw `chatCompletions.enabled` is still off
-
-### Device still cannot connect
-
-Usually means:
-
-- `Public base URL` is not public
-- firewall or reverse proxy still blocks the port
-
-## 11. Practical note
-
-This settings surface is intentionally registry-first:
-
-- Lingzhu stays in `connectors.yaml`
-- generated values come from the same structured config
-- validation, testing, and frontend rendering consume the same connector record
-
-For long-running tasks, the most stable practical behavior is:
-
-- immediate bridge-level receipt acknowledgement
-- visible progress heartbeats from the bridge during silent upstream phases
-- preserved per-user session continuity across follow-up turns
-
-This improves Lingzhu compatibility, but it still does not remove the platform-side single-request timeout limit.
+No. The goal of the current Lingzhu flow is to show only the necessary values, let the user copy them, and finish with one save.

package/docs/en/09_DOCTOR.md

@@ -10,21 +10,41 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    npm install -g @researai/deepscientist
    ```
 
-2. Try to start DeepScientist:
+2. Make sure Codex itself is working first:
+
+   Default OpenAI path:
+
+   ```bash
+   codex --login
+   ```
+
+   Provider-backed profile path:
+
+   ```bash
+   codex --profile minimax
+   ```
+
+   If `codex` is missing, repair it explicitly with:
+
+   ```bash
+   npm install -g @openai/codex
+   ```
+
+3. Try to start DeepScientist:
 
    ```bash
    ds
    ```
 
-3. If startup fails or looks unhealthy, run:
+4. If startup fails or looks unhealthy, run:
 
    ```bash
    ds doctor
    ```
 
-4. Read the checks from top to bottom and fix the failed items first.
+5. Read the checks from top to bottom and fix the failed items first.
 
-5. Run `ds doctor` again until all checks are healthy, then run `ds`.
+6. Run `ds doctor` again until all checks are healthy, then run `ds`.
 
 ## What `ds doctor` checks
 
@@ -49,16 +69,57 @@ Run the package install again so the bundled Codex dependency is present:
 npm install -g @researai/deepscientist
 ```
 
+If `codex` is still unavailable afterward, install it explicitly:
+
+```bash
+npm install -g @openai/codex
+```
+
 ### Codex is installed but not logged in
 
 Run:
 
 ```bash
-codex
+codex --login
 ```
 
+If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
+
 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 minimax
+ds --codex-profile minimax
+```
+
+Replace `minimax` with your real profile name such as `m27`, `glm`, `ark`, or `bailian`.
+
+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
+
+### 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:
+
+```text
+~/DeepScientist/config/runners.yaml
+```
+
+The default is `gpt-5.4`. If your Codex account or CLI config cannot access that model, DeepScientist now retries with the current Codex default model and persists `model: inherit` for future runs. If you still want a specific model, edit the runner config manually and rerun:
+
+```bash
+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: