first commit
This commit is contained in:
mm644706215
306
README.md
Normal file
306
README.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# 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`](./.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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```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:/path/to/mcp-zotero start
|
||||
```
|
||||
|
||||
### 4.3 `docling`
|
||||
|
||||
Recommended approach: clone locally and run with `uv`.
|
||||
|
||||
Example:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
codex mcp add qmd -- node C:/path/to/qmd/dist/qmd.js mcp
|
||||
```
|
||||
|
||||
### 4.5 `chrome-devtools`
|
||||
|
||||
Windows example:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
multi_agent = true
|
||||
```
|
||||
|
||||
Recommended additions:
|
||||
|
||||
```toml
|
||||
[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`](./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`](./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:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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`
|
||||
Reference in New Issue
Block a user