scholarly-writing-workbench/README.md

scholarly-writing-workbench

This directory is intended to be a reusable workbench for paper writing and literature review workflows.

The goal is not to store every raw reference asset in Git. The goal is to version:

• reusable prompt templates
• Codex multi-agent setup notes
• the working Word draft
• small workflow documents, checklists, and mapping tables

Large local reference corpora should stay outside normal Git tracking by default, including:

• paper/
• the localized reference folder
• root/

Those directories are already ignored in .gitignore. If you later decide to version part of them, prefer a small curated subset or Git LFS instead of pushing a full local corpus.

---

1. What this repository should contain

Recommended for version control:

• 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
• small task lists, mapping tables, and workflow notes

Not recommended for normal Git tracking:

• full PDF corpora
• full Zotero storage/
• large GitHub source snapshots
• large Docling parse outputs
• large QMD index databases

---

2. Required skills

This workflow depends on these Deep-Research-skills skills:

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

Useful supporting skills:

• skill-installer
• skill-creator

On a fresh machine, confirm they are installed under:

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

---

3. Required MCP servers

Core MCP servers:

• word-mcp
  • edits .docx
• zotero
  • manages items, PDFs, and citations
• docling
  • parses PDFs
• qmd
  • performs local hybrid retrieval

Strongly recommended:

• chrome-devtools
  • opens paper pages and GitHub pages for manual downloading

---

4. MCP installation notes

4.1 word-mcp

Recommended approach: clone locally and run with pixi.

Example:

codex mcp add word-mcp -- pixi run --manifest-path C:/path/to/word-mcp start

4.2 zotero

Recommended approach: clone locally, run with pixi, and configure:

• ZOTERO_API_KEY
• ZOTERO_USER_ID
• UNPAYWALL_EMAIL

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:/path/to/mcp-zotero start

4.3 docling

Recommended approach: clone locally and run with uv.

Example:

codex mcp add docling -- uv run --directory C:/path/to/docling-mcp docling-mcp-server --transport stdio

4.4 qmd

Recommended requirements:

• Node.js >= 22
• either a stable local build or a verified global installation

Example:

codex mcp add qmd -- node C:/path/to/qmd/dist/qmd.js mcp

4.5 chrome-devtools

Windows example:

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

On Windows 11, you may also need SystemRoot, PROGRAMFILES, and a larger startup_timeout_ms in ~/.codex/config.toml.

macOS and Linux usually do not need the Windows-specific environment block.

---

5. Codex multi-agent requirements

At minimum, ~/.codex/config.toml should contain:

[features]
multi_agent = true

Recommended additions:

[agents]
max_threads = 6
max_depth = 1

Recommended agents for this workflow:

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

See:

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

---

6. Recommended dynamic variables

To keep this workflow portable across Windows, macOS, and Linux, maintain key paths as variables instead of hard-coding them everywhere.

Recommended variables:

• REVIEW_TITLE
• WORK_ROOT
• WORD_TARGET_DOC
• REVIEW_OUTLINE_FILE
• ANALYSIS_DIR
• ZOTERO_ROOT
• ZOTERO_STORAGE_DIR
• PAPER_GITHUB_MAP_CSV
• RAG_ROOT
• RAG_PARSED_MD_DIR
• GITHUB_SOURCE_DIR
• GITHUB_MD_DIR
• CITATION_EVIDENCE_DIR

See:

• multi-agent-review-workflow-template.md

---

7. Core workflow

Recommended execution order:

1. Deep-Research-skills
   • identify missing papers, missing GitHub projects, and missing evidence
2. zotero
   • check whether items and PDFs already exist
3. chrome-devtools
   • open download pages so the user can manually download PDFs, supplements, or GitHub assets
4. docling
   • convert PDFs into structured text
5. qmd
   • perform hybrid retrieval over parsed papers, GitHub docs, and notes
6. word-mcp
   • revise the Word draft only after evidence is ready
7. zotero
   • support citation insertion and citation review

---

8. Paper-to-GitHub mapping

Maintain both:

• Zotero source traces
• a local structured mapping table

Recommended mapping table:

• paper_github_repo_map.csv

Rules:

• one paper to multiple repositories: one row per mapping
• one repository to multiple papers: one row per mapping
• QMD is the primary retrieval layer
• Zotero is the source-trace layer

---

9. Minimal checklist for a fresh machine

1. Install Codex CLI
2. Install and verify Deep-Research-skills
3. Install and verify:
   • word-mcp
   • zotero
   • docling
   • qmd
   • chrome-devtools
4. Confirm ~/.codex/config.toml enables:
   • multi_agent = true
5. Confirm ~/.codex/agents/ contains the required agent configs
6. Confirm Zotero local data or Zotero Web API access is available
7. Confirm QMD collections, Docling output directories, and mapping files are configured
8. Confirm the Word draft and outline file paths are updated

---

10. Git initialization and push

Initialize locally:

git init -b main
git add README.md .gitignore *.md *.docx
git commit -m "Initialize scholarly writing workbench"

After creating the remote repository in Gitea:

git remote add origin <YOUR_GITEA_REPO_URL>
git push -u origin main

---

11. Recommended repository name

Preferred:

• scholarly-writing-workbench

Alternatives:

• paper-review-agent-workbench
• scholarly-writing-agent-kit
• literature-review-agent-kit