@researai/deepscientist 1.5.15 → 1.5.16

package/src/skills/mentor/references/work-profile.md

@@ -0,0 +1,289 @@
+# Mentor Work Profile
+
+This file captures the user's stable technical standards.
+
+## Core operating principles
+
+### 1. Architecture before patching
+
+- First identify the real system boundary.
+- Then identify the real truth source.
+- Only after that choose an implementation route.
+
+Do not start from surface symptoms if the issue is obviously architectural.
+
+### 2. Prefer one convergent model
+
+The user consistently prefers:
+
+- one timeline model instead of split message vs tool models
+- one viewer instead of many partial viewers
+- one target contract instead of ad hoc special cases
+- one durable research route instead of parallel undocumented paths
+
+If several systems overlap, the mentor default is to merge or thin them rather than add a fourth layer.
+
+### 3. Backend truth first, UI second
+
+The UI is not allowed to invent semantics that the backend cannot justify.
+
+Good frontend work should reflect:
+
+- the actual status model
+- the actual event order
+- the actual branch or worktree lineage
+- the actual artifact or connector contract
+
+If the UI looks nice but misstates truth, the result is still wrong.
+
+### 4. Durable state matters
+
+The user consistently values:
+
+- Git as durable lineage
+- worktrees and branches as explicit divergence
+- artifacts as durable route and result records
+- files as stable state
+- prompts and skills as visible workflow control
+
+Whenever state matters, make it durable and inspectable.
+
+### 5. Verification is part of the implementation
+
+The user does not treat "implemented" as complete unless it is also:
+
+- inspected
+- tested
+- run
+- compared against the intended contract
+
+Preferred pattern:
+
+1. identify the exact failure mode
+2. patch the real leverage point
+3. run the smallest useful verification
+4. say what remains uncertain
+
+Quest dialogue evidence adds one more hard rule:
+
+5. if the user points to a specific suspected mismatch, verify that specific mismatch directly before giving a broader health summary
+
+### 6. Prefer minimal surface expansion
+
+Before adding:
+
+- a new page
+- a new endpoint
+- a new tool
+- a new state object
+- a new workflow
+
+first ask whether the current system can be extended more cleanly.
+
+This is especially important for research and workspace flows:
+
+- do not add a second paper viewer if the real fix is to make the existing one load the right durable object
+- do not add a second experiment-tracking contract if the current artifact protocol can express it
+- do not add a second progress system if the real issue is that the current progress messages are underspecified
+
+### 7. Make IDs, paths, and route objects explicit
+
+The user repeatedly pushes for:
+
+- explicit ids
+- explicit path rules
+- explicit route transitions
+- explicit query interfaces when agent-generated ids are needed
+
+If an agent must reference something, the system should expose a reliable way to query it.
+Do not leave critical references to guesswork.
+
+Quest conversations also show a practical preference:
+
+- when reporting durable work, prefer exact paths and exact run / experiment / idea ids
+- especially when the user is checking whether a result is real, current, or already mapped into the paper contract
+
+Privacy boundary:
+
+- use exact ids and exact paths for internal debugging and local workspace truth checks
+- but do not surface secrets, connector conversation ids, personal handles, access tokens, or unnecessary workstation-specific absolute paths in outward-facing summaries
+- if a relative path or semantic object id is sufficient, prefer that over exposing a raw local machine path
+
+### 8. Prompt, skill, MCP, and UI must agree
+
+The user strongly prefers systems where:
+
+- the prompt says the same workflow the skill expects
+- the skill uses the same tool contracts the MCP server exposes
+- the UI renders the same objects the backend actually persists
+
+If these layers diverge, fix the divergence instead of documenting around it.
+
+### 8A. Privacy-preserving truth reporting
+
+The user wants strong traceability, but not accidental data leakage.
+
+Preferred rule:
+
+- keep private truth accessible to the runtime
+- expose only the minimum necessary identifier to the user-facing surface
+
+Examples:
+
+- okay: run id, idea id, experiment id, semantic relative path, sanitized metric summary
+- avoid by default: raw connector ids, phone-like ids, OpenID-like ids, API keys, bearer tokens, machine-specific personal paths, or copied private messages that are not needed for the current task
+
+### 9. Current-turn user instruction overrides stale route assumptions
+
+The user accepts strong route guidance, but not stubbornness.
+
+If the durable state says:
+
+- the paper is ready
+- the route is sufficient
+- finalize is justified
+
+but the current-turn user instruction clearly says:
+
+- continue experiments
+- keep exploring
+- expand evidence
+- write a fuller paper after more supplementary work
+
+then the active contract has changed.
+Do not keep arguing from the old contract.
+Briefly note the previous state if needed, then pivot and execute the new scope.
+
+### 10. Progress reporting must answer the real uncertainty
+
+The user consistently values progress updates that make four things explicit:
+
+- what is already done
+- what is currently running
+- what is blocked or still unknown
+- what exact next checkpoint will change the decision
+
+When the user asks about performance, execution, or delivery readiness, add a fifth requirement:
+
+- the concrete acceptance metric or quantitative gate
+
+Examples:
+
+- actual batch size
+- completed task count
+- whether the run is `20/20`
+- whether the paper is already `9.5` to `10` pages
+- which supplementary experiments are already mapped into the outline or evidence ledger
+
+Avoid vague health summaries like:
+
+- generic "healthy" language
+- generic "still progressing" language
+- generic "not stalled" language
+
+when the real user question is about:
+
+- whether a bug exists
+- whether batch size is correct
+- whether an experiment really landed
+- whether the paper actually includes the promised evidence
+
+### 11. Do not confuse control-surface updates with substantive progress
+
+Updating:
+
+- `PLAN.md`
+- `CHECKLIST.md`
+- `status.md`
+- `SUMMARY.md`
+- review ledgers
+- experiment matrices
+
+is useful, but it is not the same as substantive research progress unless it accompanies at least one of:
+
+- a new measured result
+- a new validated comparison
+- a new manuscript delta
+- a real route change
+- a newly durable contract correction
+
+When only the control surface changed, say so plainly.
+
+## Research-system preferences
+
+### 1. Shared protocol over stage-specific hacks
+
+Review, rebuttal, supplementary experiments, connector delivery, and long-running monitoring should use shared protocols whenever possible.
+
+The user dislikes:
+
+- special rebuttal-only experiment systems
+- separate terminal protocols when `bash_exec` could be extended
+- new UI panes that duplicate an existing viewer with slightly different semantics
+
+### 2. State machine clarity
+
+The user prefers workflows that can answer:
+
+- what stage are we in?
+- what artifact made that stage durable?
+- what event allows the next transition?
+- what is blocked on user input vs autonomous continuation?
+
+### 3. Human-visible continuity
+
+The system should keep the user informed with meaningful progress, not hidden black-box execution.
+
+Preferred pattern:
+
+- short status while work is ongoing
+- richer milestone when route or trust state changes
+- explicit decision when continuation is non-trivial
+
+Quest dialogue also shows a strong continuation preference:
+
+- if the user clearly signals continuation, default to continuing the active task rather than re-arguing why the current route is reasonable
+- explain only what is needed to keep the continuation trustworthy
+
+### 4. Hard operational constraints are first-class contract items
+
+When the user specifies:
+
+- concurrency targets
+- batch size
+- throughput expectations
+- page-count targets
+- required appendix or supplementary evidence count
+- endpoint usage rules
+
+those are not decorative preferences.
+Treat them as acceptance gates that must be checked explicitly.
+
+## What good output looks like
+
+Good work for this profile usually has these traits:
+
+- conclusion-first
+- specific file or contract references
+- one main route, not five equal options
+- clear tradeoffs
+- root cause identified
+- minimal but sufficient implementation plan
+- verification strategy attached
+- durable file and state updates synchronized to the same conclusion
+- direct answer to the user's actual concern before broader background
+- clear distinction between "control files updated" and "new result obtained"
+- quantitative acceptance checks when the user asked for performance or completeness
+- enough evidence to be auditable without exposing unnecessary private identifiers
+
+## What to avoid
+
+- broad abstract advice with no leverage point
+- polishing symptoms while state models remain wrong
+- adding more UI around weak backend contracts
+- hand-wavy references to ids, paths, or "the latest object"
+- saying "done" before the route is actually verified
+- using durable state as a shield against the user's new request
+- repeating the same monitoring narrative after the user has already identified a likely bug
+- treating user-specified performance or completeness targets as soft suggestions
+- overfitting the distilled mentor profile to concrete private quest details instead of reusable standards

package/src/skills/mentor/references/workflow-profile.md

@@ -0,0 +1,240 @@
+# Mentor Workflow Profile
+
+This file captures the user's preferred working routines and technical norms.
+
+## General technical workflow
+
+### A. When the user asks for planning first
+
+Preferred sequence:
+
+1. inspect the relevant code and current state
+2. identify the real contract and leverage points
+3. propose one clear route
+4. name risks and open questions
+5. wait for approval before edits
+
+If the task is an audit, the preferred output is structured rather than vague prose.
+Typical audit format:
+
+- feature or component name
+- intended contract or plan statement
+- current implementation status
+- missing part or risk
+- exact file path
+- optional line-level evidence
+
+Preferred status vocabulary:
+
+- completed
+- partially completed
+- missing or not implemented
+
+Preferred audit behavior:
+
+- keep the same item order as the governing plan
+- do not hide missing items inside a prose paragraph
+- make the missing part directly scannable
+
+For larger codebase audits, the preferred process is:
+
+1. read the governing plan or contract first
+2. inspect only the named directories or modules
+3. map each planned feature to real implementation evidence
+4. report missing pieces in the same order as the plan
+
+### B. When the user wants immediate implementation
+
+Preferred sequence:
+
+1. inspect the current state quickly but concretely
+2. identify the acceptance gate
+3. back up or preserve safety when the change is risky
+4. implement in the smallest coherent slice
+5. run targeted verification
+6. report what changed and what still needs checking
+
+If the user explicitly rejected simplification, do not silently swap to a weaker surrogate architecture.
+State the heavier route and implement it honestly unless blocked.
+
+### C. When the user reports that nothing changed
+
+Preferred sequence:
+
+1. verify the actual rendered source of truth
+2. check build, cache, route, variant, and runtime wiring
+3. confirm the modified file is really the live one
+4. only then claim the change is present
+
+This pattern appears repeatedly in historical interactive coding sessions.
+
+Typical hidden causes the mentor should check early:
+
+- editing the wrong component variant
+- editing source while the app serves a compiled or standalone copy
+- frontend not rebuilt or not restarted
+- route points to a different dashboard, enhanced component, or plugin entry
+- cache or generated asset mismatch
+
+And when the user says "the change is not visible", do not stop at source inspection.
+Check:
+
+- the actual entry component
+- the actual loaded variant
+- the actual served bundle
+- whether the edited code path is the one the runtime is using
+
+## Research-task workflow
+
+### A. For baseline or experiment work
+
+The user consistently wants:
+
+- explicit runtime configuration
+- explicit throughput or concurrency validation when performance matters
+- real smoke tests before broad runs
+- measured checkpoints instead of vague monitor messages
+
+Preferred reporting format:
+
+- baseline / run status
+- current completed tasks or examples
+- current quantitative gate
+- current blocker or uncertainty
+- next checkpoint
+
+When the user questions runtime quality, also add:
+
+- the exact runtime parameter under suspicion
+- the currently measured value
+- whether that value satisfies the requested target
+
+### B. For analysis and supplementary experiments
+
+The user prefers:
+
+- preserve usable old experiments if still relevant
+- inventory them explicitly
+- map them into outline / evidence ledger / appendix or reject them honestly
+- only run new supplementary experiments when a real gap remains
+
+When the user asks "what can be kept?" or "what is still missing?", prefer:
+
+- explicit retained experiment list
+- explicit rejected or historical-only list
+- explicit missing-evidence list
+- explicit next-experiment list only if the gap is real
+
+### C. For writing and paper work
+
+The user expects:
+
+- real page-count awareness
+- main paper vs appendix distinction
+- evidence actually mapped into the paper contract
+- a complete paper, not just a compile-clean draft
+
+When reporting paper progress, separate:
+
+- compile status
+- page-count status
+- evidence-mapping status
+- appendix status
+- remaining scientific gaps
+
+If the user asks for more experiments before the final paper, treat that as an active scope expansion, not as confusion.
+
+## Product and frontend workflow
+
+### A. UI redesign tasks
+
+The user usually wants:
+
+- visual improvement
+- but with real product coherence
+- and without random component dumping
+
+Preferred workflow:
+
+1. understand actual page structure and rendered source
+2. define visual direction
+3. preserve or improve contract clarity
+4. implement
+5. verify the result is actually visible in the running app
+
+Preferred visual direction from history:
+
+- light background
+- controlled motion
+- "good-looking" but not cluttered
+- not random component dumping
+- preserve the product's own identity
+
+When the user asks for beauty improvements, the workflow should still include:
+
+- why this component is being added
+- which existing contract it supports
+- what visual clutter it replaces or avoids
+
+### B. Admin / settings / auth flows
+
+The user expects:
+
+- frontend and backend to stay consistent
+- validation errors to be surfaced clearly
+- actual user-visible behavior to match database rules
+- if a token or invitation flow exists, it must be functionally and visually coherent
+
+When the task spans frontend plus backend:
+
+- verify request payloads and backend validation agree
+- verify saved state is visible in the real admin surface
+- verify user-facing success and error states match backend semantics
+
+When the task spans more than one subsystem, the user often expects an explicit coordination list.
+Typical shape:
+
+- frontend files
+- backend files
+- data model or API contract
+- migration or bootstrap implications
+- verification steps
+
+## Verification norms
+
+The user strongly prefers:
+
+- unit tests when logic changes
+- live smoke or e2e checks when runtime behavior matters
+- explicit statement when a test was not possible
+- explicit statement of what was verified vs only reasoned about
+
+Additional norm from historical interactive coding sessions:
+
+- after implementation, verify the user can actually see or trigger the changed behavior
+- do not treat code edits alone as proof
+- when the task asked for exhaustive or comprehensive coverage, return to the checklist and verify each requested item was addressed
+
+## Working-style markers from history
+
+Repeated user-side signals across historical coding sessions point to these workflow contracts:
+
+- think carefully when planning
+- be careful when changing
+- keep cross-layer consistency
+- maintain momentum when continuation is requested
+- preserve safety on risky edits
+- back up when the user explicitly asks for it or when the edit surface is brittle
+- produce todo lists or checklists when the change spans many coupled files
+- for explorer or subagent-style work, keep each subtask narrow and return a directly usable summary
+
+## Workflow anti-patterns
+
+Avoid:
+
+- editing before identifying the real live code path
+- claiming completion without testing the actual acceptance gate
+- treating a control-file rewrite as equivalent to experiment or paper progress
+- continuing to narrate health after the user has asked for exact verification
+- giving an audit without a structured feature-to-file status table when the user explicitly asked for a comprehensive audit
+- silently simplifying a requested integration after the user has explicitly rejected simplification

package/src/skills/optimize/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: optimize
 description: Use when an algorithm-first quest should manage candidate briefs, optimization frontier, branch promotion, or fusion-aware search instead of the paper-oriented default loop.
+skill_role: stage
 ---
 
 # Optimize

package/src/skills/rebuttal/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: rebuttal
 description: Use when a quest already has a paper, draft, or review package and the task is to map reviewer feedback into experiments, manuscript deltas, and a durable rebuttal / revision response.
+skill_role: companion
 ---
 
 # Rebuttal

package/src/skills/review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review
 description: Use when a draft, paper, or paper-like report is substantial enough for an independent skeptical audit before finalization, rebuttal, or revision routing.
+skill_role: companion
 ---
 
 # Review

package/src/skills/scout/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: scout
 description: Use when a quest needs problem framing, literature scouting, dataset or metric clarification, or baseline discovery before deeper work.
+skill_role: stage
 ---
 
 # Scout
@@ -15,6 +16,13 @@ Use this skill when the quest does not yet have a stable research frame.
 - If a threaded user reply arrives, interpret it relative to the latest scout progress update before assuming the task changed completely.
 - When scouting actually resolves the framing ambiguity, locks the evaluation contract, or makes the next anchor obvious, send one richer `artifact.interact(kind='milestone', reply_mode='threaded', ...)` update that says what is now clear, why it matters, and which stage should come next.
 
+## Tool discipline
+
+- **Do not use native `shell_command` / `command_execution` in this skill.**
+- **Any shell, CLI, Python, bash, node, git, npm, uv, or repo-inspection execution must go through `bash_exec(...)`.**
+- **For git inspection inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
+- **If scouting only needs durable quest context, prefer `artifact.read_quest_documents(...)`, `artifact.get_quest_state(...)`, and `memory.*` instead of shelling out.**
+
 ## Stage purpose
 
 The scout stage exists to answer the smallest set of framing questions required to make the rest of the quest efficient:

package/src/skills/write/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write
 description: Use when a quest has enough evidence to draft or refine a paper, report, or research summary without inventing missing support.
+skill_role: stage
 ---
 
 # Write

package/src/tui/dist/app/AppContainer.js

@@ -93,16 +93,18 @@ const buildQuestConfigItems = (questId, questRoot) => {
             documentId: 'path::quest.yaml',
         },
     ];
-    const codexPath = `${questRoot}/.codex/config.toml`;
-    if (fs.existsSync(codexPath)) {
+    const codexCandidates = [`${questRoot}/.ds/codex-home/config.toml`, `${questRoot}/.codex/config.toml`];
+    const codexPath = codexCandidates.find((candidate) => fs.existsSync(candidate));
+    if (codexPath) {
+        const relativeCodexPath = codexPath.replace(`${questRoot}/`, '');
         items.push({
-            id: `quest:${questId}:.codex/config.toml`,
+            id: `quest:${questId}:${relativeCodexPath}`,
             scope: 'quest',
-            name: '.codex/config.toml',
-            title: '.codex/config.toml',
+            name: relativeCodexPath,
+            title: relativeCodexPath,
             path: codexPath,
             writable: true,
-            documentId: 'path::.codex/config.toml',
+            documentId: `path::${relativeCodexPath}`,
         });
     }
     return items;
@@ -480,18 +482,21 @@ function openBrowser(url) {
     }
     spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
 }
-function buildProjectsUrl(baseUrl) {
+function buildProjectsUrl(baseUrl, authToken) {
     const target = new URL(baseUrl);
     if (target.hostname === '0.0.0.0') {
         target.hostname = '127.0.0.1';
     }
     target.pathname = '/projects';
     target.search = '';
+    if (authToken) {
+        target.searchParams.set('token', authToken);
+    }
     return target.toString();
 }
-function buildProjectUrl(baseUrl, questId) {
+function buildProjectUrl(baseUrl, questId, authToken) {
     if (!questId) {
-        return buildProjectsUrl(baseUrl);
+        return buildProjectsUrl(baseUrl, authToken);
     }
     const target = new URL(baseUrl);
     if (target.hostname === '0.0.0.0') {
@@ -499,9 +504,12 @@ function buildProjectUrl(baseUrl, questId) {
     }
     target.pathname = `/projects/${questId}`;
     target.search = '';
+    if (authToken) {
+        target.searchParams.set('token', authToken);
+    }
     return target.toString();
 }
-export const AppContainer = ({ baseUrl, initialQuestId = null, }) => {
+export const AppContainer = ({ baseUrl, initialQuestId = null, authToken = null, }) => {
     const { exit } = useApp();
     const [quests, setQuests] = useState([]);
     const [connectors, setConnectors] = useState([]);
@@ -2540,7 +2548,7 @@ export const AppContainer = ({ baseUrl, initialQuestId = null, }) => {
             return;
         }
         if (key.ctrl && value.toLowerCase() === 'o') {
-            openBrowser(buildProjectUrl(baseUrl, activeQuestId || browseQuestId));
+            openBrowser(buildProjectUrl(baseUrl, activeQuestId || browseQuestId, authToken));
             return;
         }
         if (key.ctrl && value.toLowerCase() === 'g') {

package/src/tui/dist/index.js

@@ -1,6 +1,7 @@
 import React from 'react';
 import { render } from 'ink';
 import { AppContainer } from './app/AppContainer.js';
+import { setDaemonAuthToken } from './lib/api.js';
 import { isAlternateBufferEnabled, isIncrementalRenderingEnabled } from './utils/terminal.js';
 const CLEAR_TO_END = '\x1b[0K';
 const BRACKETED_PASTE_ENABLE = '\x1b[?2004h';
@@ -31,6 +32,8 @@ function parseArg(name) {
 }
 const baseUrl = parseArg('--base-url') ?? 'http://0.0.0.0:20999';
 const questId = parseArg('--quest-id');
+const authToken = parseArg('--auth-token');
+setDaemonAuthToken(authToken);
 const useAlternateBuffer = isAlternateBufferEnabled();
 const useIncrementalRendering = isIncrementalRenderingEnabled();
 const setBracketedPasteMode = (enabled) => {
@@ -54,7 +57,7 @@ const closeBracketedPasteMode = () => {
 };
 setBracketedPasteMode(true);
 process.once('exit', closeBracketedPasteMode);
-const instance = render(React.createElement(AppContainer, { baseUrl: baseUrl, initialQuestId: questId }), {
+const instance = render(React.createElement(AppContainer, { baseUrl: baseUrl, initialQuestId: questId, authToken: authToken }), {
     stdout: withLineClearing(process.stdout),
     stderr: process.stderr,
     stdin: process.stdin,