# 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: ```text 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: ```powershell 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: ```powershell git clone C:\Users\\Documents\project\word-mcp ``` Codex example: ```powershell codex mcp add word-mcp -- pixi run --manifest-path C:/Users//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: ```powershell git clone C:\Users\\Documents\project\mcp-zotero ``` Codex example: ```powershell 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//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: ```powershell git clone https://github.com/docling-project/docling-mcp.git C:\Users\\Documents\project\docling-mcp cd C:\Users\\Documents\project\docling-mcp uv sync ``` Codex example: ```powershell codex mcp add docling -- uv run --directory C:/Users//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: ```powershell git clone https://github.com/tobi/qmd C:\Users\\Documents\project\qmd cd C:\Users\\Documents\project\qmd npm install npm run build ``` Codex example: ```powershell codex mcp add qmd -- node C:/Users//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: ```powershell 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\\.codex\skills` - macOS: - `/Users//.codex/skills` - Linux: - `/home//.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: ```toml [features] multi_agent = true ``` Recommended: ```toml [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: ```powershell 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