scholarly-writing-workbench/cross-client-setup-and-runbook.md

Cross-Client Setup and Runbook

This document records how to reproduce the current scholarly-writing workflow on:

• Codex
• Claude Code
• other MCP-compatible clients such as OpenClaw

The goal is to make the same review-writing workflow reusable across clients, with the smallest possible amount of client-specific logic.

---

1. Scope

This workflow is designed for:

• Chinese review writing
• Zotero-backed literature management
• PDF parsing with Docling
• local hybrid retrieval with QMD
• Word .docx editing with word-mcp
• browser-assisted manual downloading with chrome-devtools
• multi-agent task decomposition when the client supports it

Current repository:

• scholarly-writing-workbench

Current workbench directory:

• D:\phd\presentation\汇总-文献汇报PPT

Core workflow documents:

• README.md
• multi-agent-review-workflow-template.md
• codex-multi-agent-setup-notes.md
• review-outline.md
• pending-calibration-tasks.md

---

2. Important compatibility rule

Not every client supports the same feature set.

2.1 What is Codex-specific

The following part is currently Codex-specific:

• Deep-Research-skills skill installation and direct skill invocation
• Codex agents/*.toml role definitions
• Codex-native multi-agent configuration in ~/.codex/config.toml

2.2 What is reusable across Codex, Claude Code, and OpenClaw

The following parts are generally reusable across MCP-compatible clients:

• word-mcp
• zotero
• docling
• qmd
• chrome-devtools
• the review workflow template
• the outline file
• the paper-to-GitHub mapping table
• the citation-evidence workflow

2.3 Practical consequence

If you want the same task to work in Claude Code or OpenClaw:

• reuse the MCP servers
• reuse the markdown workflow documents
• reuse the repository layout
• do not assume those clients understand Codex skills directly

Instead, treat the workflow template as the portable “instruction layer”.

---

3. Files and directories to keep stable

To maximize portability, keep these filenames stable:

• README.md
• multi-agent-review-workflow-template.md
• codex-multi-agent-setup-notes.md
• review-outline.md
• pending-calibration-tasks.md
• macrolide-review-draft.docx

Recommended stable analysis artifacts:

• paper_github_repo_map.csv
• citation-evidence/

Recommended stable RAG layout:

zotero-rag/
  pdf/
  parsed-md/
  parsed-json/
  github-sources/
  github-md/
  qmd-workspace/
  scripts/

---

4. Required local software

Install these first:

• Git
• Python 3.10+
• Node.js 22+
• uv
• pixi
• Zotero
• Microsoft Word
• Codex CLI if using Codex
• Claude Code if using Claude Code
• OpenClaw or another MCP-capable client if using that route

Recommended checks:

git --version
python --version
node --version
uv --version
pixi --version

---

5. Required MCP servers

These MCP servers form the portable core of the workflow.

5.1 word-mcp

Purpose:

• edit .docx
• back up files before edits
• support paragraph-level Word revision workflows

Recommended installation:

git clone <YOUR_WORD_MCP_REPO> C:\Users\<user>\Documents\project\word-mcp

Codex example:

codex mcp add word-mcp -- pixi run --manifest-path C:/Users/<user>/Documents/project/word-mcp start

Claude Code example:

Use the equivalent claude mcp add ... command or add the same command/args pair to Claude Code MCP settings.

OpenClaw:

Use the same underlying command if OpenClaw supports stdio MCP servers.

5.2 zotero

Purpose:

• manage Zotero items
• add papers by DOI
• import PDFs
• inspect metadata
• support citation workflows

Required environment variables:

• ZOTERO_API_KEY
• ZOTERO_USER_ID
• UNPAYWALL_EMAIL

Recommended installation:

git clone <YOUR_ZOTERO_MCP_REPO> C:\Users\<user>\Documents\project\mcp-zotero

Codex example:

codex mcp add zotero `
  --env ZOTERO_API_KEY=YOUR_KEY `
  --env ZOTERO_USER_ID=YOUR_USER_ID `
  --env UNPAYWALL_EMAIL=YOUR_EMAIL `
  -- pixi run --manifest-path C:/Users/<user>/Documents/project/mcp-zotero start

Claude Code / OpenClaw:

Reuse the same server command and environment variables through the client's MCP config.

5.3 docling

Purpose:

• parse PDFs into structured markdown and JSON

Recommended installation:

git clone https://github.com/docling-project/docling-mcp.git C:\Users\<user>\Documents\project\docling-mcp
cd C:\Users\<user>\Documents\project\docling-mcp
uv sync

Codex example:

codex mcp add docling -- uv run --directory C:/Users/<user>/Documents/project/docling-mcp docling-mcp-server --transport stdio

Claude Code / OpenClaw:

Reuse the same stdio command.

5.4 qmd

Purpose:

• local hybrid retrieval across parsed papers, GitHub docs, and notes

Requirements:

• Node.js >= 22

Recommended installation:

git clone https://github.com/tobi/qmd C:\Users\<user>\Documents\project\qmd
cd C:\Users\<user>\Documents\project\qmd
npm install
npm run build

Codex example:

codex mcp add qmd -- node C:/Users/<user>/Documents/project/qmd/dist/qmd.js mcp

Claude Code / OpenClaw:

Reuse the same MCP entry if the client supports stdio MCP.

5.5 chrome-devtools

Purpose:

• open paper pages
• open GitHub pages
• support manual downloads

Codex example:

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Windows often needs:

• SystemRoot
• PROGRAMFILES
• startup_timeout_ms

For Claude Code / OpenClaw:

Use the same underlying command, but match the MCP config format required by the client.

---

6. Codex-specific setup

6.1 Install Deep-Research-skills

Codex currently supports local skills under:

• Windows:
  • C:\Users\<user>\.codex\skills
• macOS:
  • /Users/<user>/.codex/skills
• Linux:
  • /home/<user>/.codex/skills

Install at least:

• research
• research-add-fields
• research-add-items
• research-deep
• research-report

6.2 Enable Codex multi-agent

Edit:

• ~/.codex/config.toml

Minimum:

[features]
multi_agent = true

Recommended:

[agents]
max_threads = 6
max_depth = 1

6.3 Add review-specific agent roles

Recommended roles:

• deep_researcher
• zotero_locator
• qmd_retriever
• github_mapper
• writer
• citation_checker
• citation_archivist
• web_researcher

See:

• codex-multi-agent-setup-notes.md

---

7. Claude Code setup

Claude Code does not rely on Codex skills. To reproduce the same workflow:

1. configure the same MCP servers
2. reuse the same repository and markdown instructions
3. treat multi-agent-review-workflow-template.md as the primary portable workflow spec

Recommended sequence:

1. add word-mcp
2. add zotero
3. add docling
4. add qmd
5. add chrome-devtools
6. open the repository
7. explicitly tell Claude Code to follow:
   • README.md
   • multi-agent-review-workflow-template.md
   • review-outline.md
   • pending-calibration-tasks.md

Important limitation:

• Codex skills are not automatically portable to Claude Code as “skills”
• the equivalent behavior should be driven by the workflow template and MCP tools

---

8. OpenClaw setup

The same general rule applies to OpenClaw:

• if OpenClaw supports MCP stdio servers, reuse the same MCP commands
• if OpenClaw supports multi-agent behavior, map the same role structure conceptually
• if OpenClaw does not support Codex-style skills, use the markdown workflow template as the instruction layer

Minimum expectation for OpenClaw:

1. it can call MCP servers
2. it can read local markdown files
3. it can follow a structured review workflow from prompt + docs

If those three conditions hold, the workflow can be reproduced at the process level even without Codex-native skills.

---

9. Recommended repository bootstrapping on a new machine

Clone the repository:

git clone ssh://git@gitea.jmsu.top:2222/lingyuzeng/scholarly-writing-workbench.git
cd scholarly-writing-workbench

Then verify:

• README.md
• multi-agent-review-workflow-template.md
• review-outline.md
• macrolide-review-draft.docx

---

10. Recommended startup procedure for any client

Before starting a real task:

1. open the repository root
2. read:
   • README.md
   • multi-agent-review-workflow-template.md
   • review-outline.md
   • pending-calibration-tasks.md
3. confirm that the MCP servers are available
4. confirm whether QMD has already indexed the parsed corpus
5. confirm whether Zotero has the needed papers and PDFs

Do not start with Word editing.

Start with:

• literature gap discovery
• evidence retrieval
• citation planning

Only then move to:

• Word revision
• citation evidence files
• manual Zotero citation insertion

---

11. Recommended review task sequence

Standard order:

1. identify the chapter and subsection from review-outline.md
2. check Zotero and local files
3. if missing, open pages and download manually
4. parse PDFs with Docling
5. index and query with QMD
6. align paper and GitHub traces
7. revise the Word draft
8. archive citation evidence
9. insert citations manually in Word

---

12. First test plan on a new client

Run a small pilot before trusting the full workflow.

Recommended pilot:

Round 0

• confirm MCP availability
• confirm agent role plan
• do not edit Word

Round 1

• choose one subsection
• collect evidence only
• do not edit Word

Round 2

• edit one or two paragraphs only
• back up before editing

Round 3

• create citation evidence files
• do not insert citations automatically yet

Round 4

• test paper-to-GitHub reasoning for a tool-oriented section

---

13. Current known limitations

The following items still require iterative calibration:

• QMD thresholds and candidate counts
• Docling JSON field whitelist for citation evidence
• depth of GitHub evidence inspection
• whether Zotero auto-insertion should ever be tested on Word copies
• whether Word recovery should be fully scripted

These are tracked in:

• pending-calibration-tasks.md

---

14. Key portability principle

To make this workflow usable across Codex, Claude Code, and OpenClaw:

• keep filenames in English
• keep workflow instructions in stable markdown files
• keep MCP servers client-agnostic where possible
• treat Codex skills as optional acceleration for Codex, not as the only source of workflow logic