docrev 0.6.2 → 0.6.4

package/README.md

@@ -1,423 +1,291 @@
 # docrev
 
 [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
-[![CI](https://github.com/gcol33/docrev/actions/workflows/ci.yml/badge.svg)](https://github.com/gcol33/docrev/actions/workflows/ci.yml)
-[![Node.js](https://img.shields.io/node/v/docrev)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-CLI tool for Word ↔ Markdown round-trips. Handle reviewer feedback on academic papers: import track changes, review interactively, manage comments, validate DOIs, and build to PDF/DOCX/LaTeX.
+**Write your papers in plain text. Generate Word documents when you need them.**
 
-## Install
+## The Problem
 
-```bash
-npm install -g docrev
-```
+You're writing a scientific paper. Your supervisor reviews it in Word, adding comments and track changes. You address the feedback, send it back. Another round of reviews. Then journal submission. Then reviewer comments. More Word documents flying back and forth.
 
-The `rev` command is now available globally.
+Sound familiar?
 
-### Prerequisites
+- Word files get corrupted
+- "Which version is the latest?" confusion
+- Track changes become unreadable after multiple rounds
+- Equations break when copy-pasting
+- Figures get embedded at wrong resolutions
+- Collaborating means emailing files back and forth
 
-- **Node.js 18+** - [Download](https://nodejs.org/)
-- **Pandoc** - For building PDF/DOCX ([pandoc.org](https://pandoc.org/installing.html))
-- **pandoc-crossref** - For figure/table refs (optional, [install](https://github.com/lierdakil/pandoc-crossref/releases))
+## The Solution
 
-```bash
-# macOS
-brew install pandoc pandoc-crossref
+**docrev** lets you write in plain text (Markdown) and generate Word/PDF whenever you need to share. Your collaborators keep using Word — they don't need to change anything. You get:
 
-# Ubuntu/Debian
-sudo apt install pandoc
+- **Version control** — See exactly what changed, when, and why
+- **No corruption** — Plain text files never break
+- **Equations that work** — Write LaTeX, get perfect equations in Word
+- **Figures stay separate** — Reference images, don't embed them
+- **Automated formatting** — Citations, cross-references, all handled
 
-# Windows
-winget install JohnMacFarlane.Pandoc
-```
+## How It Works
 
-Verify installation:
-```bash
-rev --version
-rev install    # Check for missing dependencies
 ```
-
-### Shell Completions (Optional)
-
-Enable tab completion for `rev` commands:
-
-```bash
-# Bash - add to ~/.bashrc
-eval "$(rev completions bash)"
-
-# Zsh - add to ~/.zshrc
-eval "$(rev completions zsh)"
+Your text files  ───►  docrev  ───►  Word/PDF for collaborators
+      │                                      │
+      │                                      ▼
+      │                              They add comments
+      │                                      │
+      │                                      ▼
+      └──────────────  docrev  ◄────  They send it back
+                    (imports their feedback)
 ```
 
-## Features
+You always work in plain text. Word is just the delivery format.
 
-- **Integrated build system** - Combine sections → paper.md → PDF, DOCX, or LaTeX
-- **Import from Word** - Diff Word docs against your Markdown, generating CriticMarkup annotations
-- **Section-aware import** - Import directly to modular section files (intro.md, methods.md, etc.)
-- **Interactive review** - Accept/reject track changes with a TUI
-- **Comment management** - List, filter, resolve, and reply to reviewer comments
-- **Response letter generation** - Auto-generate point-by-point response from comments
-- **DOI validation** - Check and find DOIs via Crossref/DataCite APIs
-- **Cross-reference conversion** - Auto-convert "Figures 1-3" to `@fig:label` syntax (handles complex patterns)
-- **Equation extraction** - Extract LaTeX equations from Word documents (OMML → LaTeX)
-- **Citation validation** - Check citations against bibliography
+---
 
 ## Quick Start
 
-### Start from Word Document
+### Install
 
 ```bash
-# Import existing Word doc → creates section files + rev.yaml
-rev import manuscript.docx
-
-# Import to specific directory
-rev import manuscript.docx -o my-paper/
-
-# Preview without creating files
-rev import manuscript.docx --dry-run
+npm install -g docrev
+brew install pandoc    # Required for Word/PDF generation
 ```
 
-### New Project from Template
+### Start a New Paper
 
 ```bash
-# Create a new paper project
 rev new my-paper
+cd my-paper
+```
 
-# or with a specific template
-rev new my-thesis --template thesis
-
-# List available templates
-rev new --list
+This creates:
+```
+my-paper/
+├── introduction.md    ← Write your intro here
+├── methods.md         ← Your methods
+├── results.md         ← Your results
+├── discussion.md      ← Your discussion
+├── references.bib     ← Your citations
+└── rev.yaml           ← Paper title, authors
 ```
 
-### Build Workflow
+### Or Import from Existing Word Document
 
 ```bash
-cd my-paper
+rev import my-manuscript.docx
+```
 
-# Edit your sections
-# introduction.md, methods.md, results.md, discussion.md
+docrev extracts:
+- Text → Markdown files
+- Comments → Preserved with author names
+- Equations → Converted to LaTeX
+- Images → Saved to figures/
 
-# Build PDF and Word
-rev build
+---
 
-# Build specific format
-rev build pdf
-rev build docx
-rev build tex
-rev build all    # PDF + DOCX + TEX
-```
+## Writing in Markdown
 
-### Review Workflow
+Markdown is just text with simple formatting. If you can write an email, you can write Markdown.
 
-```bash
-# Import reviewer's Word doc to section files
-rev sections reviewed.docx
+### Basic Formatting
 
-# Review track changes interactively
-rev review methods.md
+```markdown
+# This is a Heading
 
-# See remaining comments
-rev comments methods.md
+This is a paragraph. **Bold text** and *italic text*.
 
-# Rebuild
-rev build docx
+- Bullet point
+- Another bullet
+
+1. Numbered list
+2. Second item
 ```
 
-## Commands
-
-### Build & Create
-
-| Command | Description |
-|---------|-------------|
-| `rev build [formats...]` | Build PDF/DOCX/TEX from sections |
-| `rev build --toc` | Build with table of contents |
-| `rev build --show-changes` | Export DOCX with visible track changes |
-| `rev new <name>` | Create new project from template |
-| `rev new --list` | List available templates |
-| `rev install` | Check/install dependencies (pandoc-crossref) |
-
-### Import & Export
-
-| Command | Description |
-|---------|-------------|
-| `rev import <docx>` | Bootstrap project from Word (creates sections + rev.yaml) |
-| `rev import <docx> <md>` | Import changes by diffing Word against your MD |
-| `rev sections <docx>` | Import Word doc to existing section files |
-| `rev extract <docx>` | Extract plain text from Word |
-
-### Review & Edit
-
-| Command | Description |
-|---------|-------------|
-| `rev review <file>` | Interactive accept/reject TUI for track changes |
-| `rev status <file>` | Show annotation counts |
-| `rev comments <file>` | List all comments with context |
-| `rev comments <file> --export comments.csv` | Export comments to CSV |
-| `rev resolve <file> -n 1` | Mark comment #1 as resolved |
-| `rev strip <file>` | Output clean Markdown (annotations applied) |
-
-### Cross-References
-
-| Command | Description |
-|---------|-------------|
-| `rev refs [file]` | Show figure/table registry and reference status |
-| `rev migrate <file>` | Convert hardcoded refs (Fig. 1) to dynamic (@fig:label) |
-
-### Comments & Replies
-
-| Command | Description |
-|---------|-------------|
-| `rev config user "Name"` | Set your name for replies |
-| `rev reply <file>` | Interactive reply to reviewer comments |
-| `rev reply <file> -n 1 -m "text"` | Reply to specific comment (non-interactive) |
-
-### Bibliography & DOIs
-
-| Command | Description |
-|---------|-------------|
-| `rev doi check [file.bib]` | Validate DOIs in bibliography (Crossref + DataCite) |
-| `rev doi lookup [file.bib]` | Search for missing DOIs by title/author/year |
-| `rev doi fetch <doi>` | Fetch BibTeX entry from DOI |
-| `rev doi add <doi>` | Fetch and add DOI entry to bibliography |
-
-### Validation & Analysis
-
-| Command | Description |
-|---------|-------------|
-| `rev citations [file.bib]` | Validate citations against bibliography |
-| `rev figures [file]` | List figures/tables with reference counts |
-| `rev equations list` | List all equations in section files |
-| `rev equations from-word <docx>` | Extract equations from Word to LaTeX |
-| `rev response [files]` | Generate response letter from comments |
-| `rev anonymize <file>` | Prepare document for blind review |
-| `rev validate --journal <name>` | Check manuscript against journal requirements |
-| `rev validate --list` | List available journal profiles |
-
-### Multi-Reviewer & Git
-
-| Command | Description |
-|---------|-------------|
-| `rev merge <md> <docx...>` | Merge feedback from multiple Word documents |
-| `rev diff [ref]` | Compare sections against git history |
-| `rev history [file]` | Show revision history for sections |
-
-### Configuration
-
-| Command | Description |
-|---------|-------------|
-| `rev init` | Generate sections.yaml from existing .md files |
-| `rev split <file>` | Split annotated paper.md back to section files |
-| `rev help [topic]` | Show help (topics: workflow, syntax, commands) |
-
-### Convenience Commands
-
-| Command | Description |
-|---------|-------------|
-| `rev word-count` | Show word counts per section |
-| `rev word-count -j <journal>` | Warn if over journal word limit |
-| `rev stats` | Project dashboard (words, figures, citations) |
-| `rev search <query>` | Search across all section files |
-| `rev backup` | Create timestamped backup zip |
-| `rev export` | Export project as distributable zip |
-| `rev preview <format>` | Build and open document |
-| `rev watch [format]` | Auto-rebuild on file changes |
-| `rev lint` | Check for broken refs, missing citations |
-
-### Grammar & Style
-
-| Command | Description |
-|---------|-------------|
-| `rev grammar` | Check grammar/style issues |
-| `rev grammar --rules` | List available grammar rules |
-| `rev grammar --learn <word>` | Add word to custom dictionary |
-| `rev grammar --list` | Show custom dictionary |
-
-### Spelling
-
-| Command | Description |
-|---------|-------------|
-| `rev spelling` | Check spelling in all sections |
-| `rev spelling --british` | Use British English dictionary |
-| `rev spelling --learn <word>` | Add word to global dictionary |
-| `rev spelling --learn-project <word>` | Add word to project dictionary |
-| `rev spelling --list` | Show global dictionary |
-| `rev spelling --list-all` | Show global + project dictionaries |
-
-### Direct DOCX Editing
-
-| Command | Description |
-|---------|-------------|
-| `rev annotate <docx>` | Add comments to Word document |
-| `rev apply <md> <docx>` | Apply annotations as track changes |
-| `rev comment <docx>` | Interactive comment mode |
-
-## Project Structure
-
-A typical rev project:
+### Citations
 
+In your `.bib` file:
+```bibtex
+@article{Smith2020,
+  author = {Smith, Jane},
+  title = {My Paper Title},
+  journal = {Nature},
+  year = {2020}
+}
 ```
-my-paper/
-├── rev.yaml           # Project config (title, authors, build settings)
-├── introduction.md    # Section files
-├── methods.md
-├── results.md
-├── discussion.md
-├── references.bib     # Bibliography
-├── figures/           # Images
-├── paper.md           # Combined output (generated)
-├── my-paper.pdf       # PDF output (generated)
-└── my-paper.docx      # Word output (generated)
+
+In your text:
+```markdown
+Previous studies have shown this effect [@Smith2020].
+Multiple citations work too [@Smith2020; @Jones2021].
 ```
 
-## Configuration (rev.yaml)
-
-```yaml
-title: "Your Paper Title"
-authors:
-  - name: First Author
-    affiliation: Institution
-    email: author@example.com
-
-sections:
-  - introduction.md
-  - methods.md
-  - results.md
-  - discussion.md
-
-bibliography: references.bib
-csl: nature.csl           # Optional citation style
-
-crossref:
-  figureTitle: Figure
-  tableTitle: Table
-  figPrefix: [Fig., Figs.]
-  tblPrefix: [Table, Tables]
-
-pdf:
-  documentclass: article
-  fontsize: 12pt
-  geometry: margin=1in
-  linestretch: 1.5
-  toc: false                 # Table of contents
-
-docx:
-  reference: template.docx   # Optional reference doc
-  keepComments: true
-  toc: false                 # Table of contents
+→ Becomes: "Previous studies have shown this effect (Smith 2020)."
+
+### Equations
+
+Inline: `$E = mc^2$` → E = mc²
+
+Display equation:
+```markdown
+$$
+\hat{p} = \frac{\sum_d w_d p_d}{\sum_d w_d}
+$$
 ```
 
-## Annotation Syntax (CriticMarkup)
+### Figures
 
 ```markdown
-{++inserted text++}      # Insertions
-{--deleted text--}       # Deletions
-{~~old~>new~~}           # Substitutions
-{>>Author: comment<<}    # Comments
+![Map of study sites across Europe](figures/map.png){#fig:map}
+
+As shown in @fig:map, our study sites span 12 countries.
 ```
 
-## Template Variables
+→ In Word: "As shown in Figure 1, our study sites..."
 
-Use template variables in section files (processed during build):
+The figure number updates automatically if you reorder figures.
 
-```markdown
-Last updated: {{date}}
-Version: {{version}}
-Word count: {{word_count}}
+---
+
+## Build Your Document
+
+```bash
+rev build docx    # Generate Word document
+rev build pdf     # Generate PDF
+rev build --dual  # Both clean + with-comments versions
+```
+
+### Preview While Writing
+
+```bash
+rev watch docx    # Auto-rebuilds when you save
 ```
 
-| Variable | Description |
-|----------|-------------|
-| `{{date}}` | Current date (YYYY-MM-DD) |
-| `{{date:MMMM D, YYYY}}` | Custom format (December 29, 2025) |
-| `{{year}}` | Current year |
-| `{{version}}` | Version from rev.yaml |
-| `{{title}}` | Document title |
-| `{{author}}` | First author name |
-| `{{authors}}` | All authors (comma-separated) |
-| `{{word_count}}` | Total word count |
+---
 
-## Comment Replies
+## Handle Reviewer Feedback
 
-Reply to reviewer comments with your name:
+### 1. Receive Reviewed Document
+
+Your supervisor sends back `manuscript_reviewed.docx` with comments and track changes.
 
 ```bash
-# Set your name (once)
-rev config user "Gilles Colling"
+rev sections manuscript_reviewed.docx
+```
 
-# Interactive: go through each comment
-rev reply methods.md
+This imports their changes into your Markdown files.
 
-# Non-interactive: reply to specific comment
-rev reply methods.md -n 1 -m "Done, added clarification"
+### 2. See Their Comments
+
+```bash
+rev comments methods.md
 ```
 
-Creates a conversation thread:
-```markdown
-{>>Reviewer: Please clarify this<<} {>>Gilles Colling: Added in next paragraph<<}
+Output:
 ```
+#1 [Dr. Smith] line 45
+   "Please clarify the sampling methodology"
 
-Claude can also reply programmatically using the non-interactive mode.
+#2 [Dr. Smith] line 78
+   "Add a citation here"
+```
 
-## Cross-Reference System
+### 3. Reply to Comments
 
-Use dynamic references in your source:
+```bash
+rev config user "Your Name"    # Set your name (once)
+rev reply methods.md -n 1 -m "Added detail about random sampling in paragraph 2"
+```
 
-```markdown
-![Caption](figures/img.png){#fig:heatmap}
+### 4. Rebuild and Send Back
 
-See @fig:heatmap for the results.
+```bash
+rev build --dual
 ```
 
-When importing from Word, hardcoded refs are auto-converted:
-- `Figure 1` → `@fig:heatmap`
-- `Fig. 2a` → `@fig:model`
-- `Figs. 1-3` → `@fig:heatmap; @fig:model; @fig:hierarchy`
-- `Figures 1, 2, and 3` → `@fig:one; @fig:two; @fig:three`
-- `Fig. 1a-c` → `@fig:one` (expands letter suffixes)
-- `Figs. 1a-3b` → all panels from 1a to 3b
+Creates:
+- `paper.docx` — Clean version
+- `paper_comments.docx` — With threaded comment conversations
 
-## Build Outputs
+Your reply appears under their comment, just like a conversation in Word.
 
-| Format | Annotations | Cross-refs |
-|--------|-------------|------------|
-| PDF | Stripped (clean) | `@fig:label` → "Figure 1" |
-| DOCX | Comments kept | `@fig:label` → "Figure 1" |
-| TEX | Stripped (clean) | LaTeX labels |
+---
 
-## DOI Management
+## Why Separate Files?
 
-Check and find DOIs for your bibliography:
+Instead of one giant document, docrev uses separate files for each section:
 
-```bash
-# Validate all DOIs in references.bib
-rev doi check references.bib
+| File | Content |
+|------|---------|
+| `introduction.md` | Background, aims, hypotheses |
+| `methods.md` | Study design, analysis |
+| `results.md` | Findings |
+| `discussion.md` | Interpretation |
+
+**Benefits:**
+- Easier to navigate
+- Work on one section without scrolling
+- Git shows changes per section
+- Collaborators can review specific parts
+
+---
+
+## Commands Reference
+
+| What you want to do | Command |
+|---------------------|---------|
+| Create new paper | `rev new my-paper` |
+| Import from Word | `rev import manuscript.docx` |
+| Build Word doc | `rev build docx` |
+| Build PDF | `rev build pdf` |
+| Import reviewer feedback | `rev sections reviewed.docx` |
+| See all comments | `rev comments methods.md` |
+| Reply to comment #1 | `rev reply methods.md -n 1 -m "Fixed"` |
+| Check word count | `rev word-count` |
+| Validate DOIs | `rev doi check` |
+| Check before submission | `rev check` |
 
-# Look up missing DOIs automatically
-rev doi lookup references.bib --confidence medium
+See [full documentation](docs/commands.md) for all commands.
 
-# Fetch BibTeX from a DOI
-rev doi fetch 10.1038/nature12373
+---
+
+## Requirements
+
+- **Node.js 18+** — [Download](https://nodejs.org/)
+- **Pandoc** — Converts Markdown to Word/PDF
+
+```bash
+# macOS
+brew install pandoc
 
-# Add a citation by DOI
-rev doi add 10.1038/nature12373
+# Windows
+winget install JohnMacFarlane.Pandoc
+
+# Linux
+sudo apt install pandoc
 ```
 
-**Features:**
-- Validates DOIs via Crossref API (+ DataCite for Zenodo/Figshare)
-- Smart lookup using title, author, year, and journal matching
-- Filters out supplement/figure DOIs and F1000 reviews
-- Confidence levels: `high`, `medium`, `low` (use `--confidence low` to see all matches)
-- Skip entries with `nodoi = {true}` or `% no-doi` comment
+---
+
+## FAQ
+
+**Q: Do my collaborators need to install docrev?**
+No. They keep using Word normally. You handle the conversion.
+
+**Q: Can I use my existing Word document?**
+Yes. `rev import manuscript.docx` converts it to Markdown.
+
+**Q: What about my bibliography?**
+Use a `.bib` file (export from Zotero/Mendeley/EndNote). Citations are handled automatically.
+
+**Q: Will equations look right in Word?**
+Yes. LaTeX equations are converted to native Word equations.
 
-## Dependencies
+**Q: What if I make a mistake?**
+Plain text + Git means you can always go back. Run `rev backup` before big changes.
 
-- Node.js 18+
-- [Pandoc](https://pandoc.org/) - Document conversion
-- [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) - Cross-references (optional but recommended)
-- [mammoth](https://github.com/mwilliamson/mammoth.js) - Word document parsing
-- [diff](https://github.com/kpdecker/jsdiff) - Text diffing
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docrev",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",