# docrev Command Reference

## Project Creation

### rev new
Create a new document project.
```bash
rev new my-document          # Creates my-document/ with section files
rev new my-document --template apa
```

## Document Import/Export

### rev import
Import a Word document with track changes and comments.
```bash
rev import manuscript.docx
rev import manuscript.docx --output ./project
```

### rev sync
Sync feedback from a reviewed Word document into existing markdown sections.
```bash
rev sync reviewed.docx          # Updates markdown with track changes/comments
rev sync                        # Auto-detect most recent .docx
rev sync reviewed.docx methods  # Sync only methods section
rev sync reviewed.docx --comments-only  # Insert comments only; never modify prose
```

`--comments-only` skips the Word→Markdown diff entirely. Use it when the
markdown has been revised between sending the docx out for review and
receiving it back: applying track changes from a stale draft would clobber
newer edits, but comments still need to land. Comments are placed at
fuzzy-matched anchors against the current prose. Pair with
`rev verify-anchors` to see which ones won't fit before you run sync.

### rev verify-anchors
Report drift between Word comment anchors and the current markdown.
```bash
rev verify-anchors reviewed.docx       # Print per-comment match quality
rev verify-anchors reviewed.docx --json  # Machine-readable report
```

Each comment is classified by how well its anchor still matches the current
section prose:

- `clean` – exact or whitespace-normalized hit
- `drift` – anchor only matches via stripped-CriticMarkup or partial-prefix fallbacks
- `context-only` – anchor text is gone, only surrounding context survives
- `ambiguous` – multiple candidate positions; needs context to disambiguate
- `unmatched` – nothing maps; user must place the comment manually

Useful before `rev sync --comments-only` to plan which comments will land
automatically and which need manual placement.

### rev build
Build output documents from markdown sections.
```bash
rev build                    # Build PDF and DOCX
rev build pdf                # PDF only
rev build docx               # DOCX only
rev build --toc              # Include table of contents
rev build docx --dual        # Clean + annotated versions
rev build docx --show-changes  # DOCX with visible track changes (audit)
rev build docx --pandoc-arg=--lua-filter=tofill.lua   # Pass extra args to pandoc
rev build -o Final_Report     # Override output filename (extension auto-added)
rev build pdf --verbose      # Echo the pandoc invocation (useful for filter debugging)
```

By default, outputs land in `output/` next to `rev.yaml`. Override or
disable via the `outputDir` field in rev.yaml (see below).

#### Choosing output filenames

By default, the output basename is derived from `title:` (slugified — e.g.
"My Paper" → `my-paper.docx`). Long titles are truncated at word boundaries
(at the last `-` at-or-before 80 chars), so `communities` stays whole instead
of becoming `communitie`.

To pick your own filename, set per-format names in `rev.yaml`:

```yaml
output:
  docx: ADAPT_proposal_draft.docx
  pdf: ADAPT_proposal_draft.pdf
```

Extensions are optional — `ADAPT_proposal_draft` is fine, the right extension
is added per format. Relative paths resolve under `outputDir`; absolute paths
bypass `outputDir`.

Or override on the command line with `-o, --output <path>`:

```bash
rev build docx -o Final_Report           # → output/Final_Report.docx
rev build pdf docx -o Final_Report       # Applies to both formats
rev build -o /tmp/draft.docx docx        # Absolute path bypasses outputDir
```

CLI `-o` wins over `output:` in `rev.yaml`. When `--dual` is on, the
`_comments` variant piggybacks on the chosen name (e.g.
`Final_Report_comments.docx`). When `--show-changes` is on, the audit DOCX
uses the chosen name with a `-changes` suffix
(e.g. `Final_Report-changes.docx`).

#### Passing custom pandoc args

For pandoc flags rev doesn't surface directly (Lua/JSON filters, custom
templates, variables, etc.), use the repeatable `--pandoc-arg` flag or the
`pandoc-args` field in `rev.yaml`:

```yaml
# rev.yaml — applies to every format
pandoc-args:
  - --lua-filter=tofill.lua
  - --shift-heading-level-by=1

# Format-specific (concatenated after the top-level list)
docx:
  pandoc-args:
    - --lua-filter=docx_only.lua
pdf:
  pandoc-args:
    - --variable=papersize:a4
```

```bash
# CLI overrides — appended last, so pandoc's last-wins rule lets CLI flags
# beat repeated config flags
rev build docx --pandoc-arg=--lua-filter=cli.lua --pandoc-arg=--metadata=draft:true
```

Run with `--verbose` to print the full pandoc command line (one per format).
Copy-paste it into a terminal to reproduce a build manually.

The `--dual` flag produces:
- `output/<title>.docx` — clean, for submission
- `output/<title>_comments.docx` — includes comment threads as Word comments

The `--show-changes` flag (DOCX only) produces a single audit document
where every accepted/rejected revision and substitution is exported as a
visible Word track change, attributed to the configured user. Useful when
a co-author wants to see what changed since the last shared version.

### rev preview
Build and open document in default app.
```bash
rev preview pdf              # Build and open PDF
rev preview docx             # Build and open Word
```

### rev export
Export project as distributable zip.
```bash
rev export                   # Creates project.zip (no node_modules)
```

### rev backup
Create timestamped project backup.
```bash
rev backup                   # Creates backup-2024-12-29.zip
rev backup --name v1-draft   # Creates v1-draft.zip
```

## Comments & Annotations

### rev comments
List all comments with context.
```bash
rev comments methods.md                    # Show comments
rev comments methods.md --export out.csv   # Export to CSV
```

### rev reply
Reply to a specific comment (non-interactive).
```bash
rev reply methods.md -n 1 -m "Added clarification"
rev reply results.md -n 3 -m "Updated figure"
```

### rev resolve
Mark a comment as resolved.
```bash
rev resolve methods.md -n 1
rev resolve methods.md -n 1,2,3   # Multiple comments
```

### rev status
Show project overview or annotation counts for a file.
```bash
rev status               # Project overview (words, comments, changes)
rev status methods.md    # Specific file annotations
```

### rev next / rev prev
Navigate pending comments.
```bash
rev next                 # Show next pending comment
rev next -n 3            # Show 3rd pending comment
rev prev                 # Show last pending comment
rev first methods        # First comment in methods section
rev last                 # Last comment overall
```

### rev todo
List all pending comments as a checklist.
```bash
rev todo                 # List all pending
rev todo --by-author     # Group by author
```

### rev accept / rev reject
Accept or reject track changes.
```bash
rev accept methods.md         # List all changes
rev accept methods.md -n 1    # Accept change #1
rev accept methods.md -a      # Accept all
rev reject methods.md -n 2    # Reject change #2
```

### rev archive
Archive reviewer .docx files.
```bash
rev archive              # Move all .docx to archive/
rev archive --by Smith   # Specify reviewer name
rev archive --dry-run    # Preview without moving
```

### rev strip
Remove all annotations from markdown.
```bash
rev strip methods.md --output clean.md
rev strip methods.md --accept          # Accept all changes
rev strip methods.md --reject          # Reject all changes
```

## Response Letter

### rev response
Generate point-by-point response letter from comments.
```bash
rev response                 # Generate response letter
```

## Validation & Checks

### rev check
Run all pre-submission checks (lint + grammar + citations).
```bash
rev check                    # Run all checks
rev check --fix              # Auto-fix where possible
```

### rev lint
Check for common issues.
```bash
rev lint                     # Run all checks
rev lint --fix               # Auto-fix where possible
```
Checks: broken cross-references, missing citations, orphaned figures, unresolved comments.

### rev grammar
Check grammar and style.
```bash
rev grammar                  # Check all sections
rev grammar --rules          # List available rules
rev grammar --learn word     # Add to custom dictionary
rev grammar --forget word    # Remove from dictionary
rev grammar --list           # Show custom dictionary
rev grammar -s warning       # Filter by severity
```

### rev spelling
Check spelling in all sections.
```bash
rev spelling                 # Check all sections
rev spelling --british       # Use British English dictionary
rev spelling --learn word    # Add to global dictionary (~/.rev-dictionary)
rev spelling --learn-project word  # Add to project dictionary
rev spelling --forget word   # Remove from global dictionary
rev spelling --list          # Show global dictionary
rev spelling --list-all      # Show global + project dictionaries
```
Built-in scientific vocabulary reduces false positives. Possible author names are shown separately for easy review.

### rev validate
Check against journal requirements.
```bash
rev validate --journal nature
rev validate --list          # List 22 available journals
```

### rev citations
Validate citations against bibliography.
```bash
rev citations
```

## DOI Management

### rev doi check
Validate DOIs in bibliography.
```bash
rev doi check references.bib
rev doi check references.bib --strict   # Fail if articles missing DOIs
```

### rev doi lookup
Find missing DOIs by title/author/year.
```bash
rev doi lookup references.bib
rev doi lookup references.bib --confidence high
```

### rev doi fetch
Get BibTeX from a DOI.
```bash
rev doi fetch 10.1234/example
```

### rev doi add
Add citation to .bib file from DOI.
```bash
rev doi add 10.1234/example
rev doi add 10.1234/example --file references.bib
```

## Content Analysis

### rev word-count
Show word counts per section.
```bash
rev word-count               # Per-section counts
rev word-count --limit 5000  # Warn if over limit
rev word-count -j nature     # Use journal word limit
```

### rev stats
Project dashboard showing overview.
```bash
rev stats                    # Words, figures, citations, comments
```

### rev search
Search across all section files.
```bash
rev search "climate change"
rev search -i "method"       # Case-insensitive
```

### rev figures
List figures with reference counts.
```bash
rev figures methods.md
```

### rev equations
Work with LaTeX equations.
```bash
rev equations list           # List all equations
rev equations from-word manuscript.docx  # Extract from Word
```

## Direct DOCX Editing (Layout Workflow)

### rev annotate
Add comments directly to Word document.
```bash
rev annotate paper.docx -m "Comment" -s "text to find"
```

### rev apply
Apply MD annotations as Word track changes.
```bash
rev apply paper.md output.docx
```

### rev comment
Interactive comment mode for Word documents.
```bash
rev comment paper.docx
```

## Project Management

### rev clean
Remove generated files.
```bash
rev clean                    # Remove paper.md, PDFs, DOCXs
rev clean --dry-run          # Show what would be deleted
rev clean --all              # Also remove backups and exports
```

### rev open
Open project folder or file.
```bash
rev open                     # Open project folder
rev open paper.pdf           # Open specific file
```

### rev watch
Auto-rebuild on file changes.
```bash
rev watch                    # Watch and rebuild
rev watch pdf                # Only rebuild PDF
rev watch --no-open          # Don't open after build
```

## Configuration

### rev config
Configure user settings.
```bash
rev config user "Your Name"  # Set author name for replies
rev config                   # Show current config
```

## rev.yaml Settings

### Output Directory

By default, built artefacts land in `output/` next to `rev.yaml`. Both the
clean output and `--dual` companion (`*_comments.docx` / `*_comments.pdf`)
follow the configured location. Override or disable:

```yaml
outputDir: output       # default — outputs land in ./output/
outputDir: dist         # custom subdirectory
outputDir: null         # legacy layout — outputs alongside paper.md
```

Explicit caller-supplied output paths (e.g. internal temp files in the
dual flow) bypass `outputDir`.

### PDF Engine and Fonts

The default PDF engine is `pdflatex`. Switch to xelatex/lualatex when the
manuscript needs native UTF-8 rendering of Latin-Extended diacritics
(Czech/Polish/Croatian/Spanish author names, species epithets):

```yaml
pdf:
  engine: xelatex          # or lualatex, tectonic, etc.
  mainfont: "TeX Gyre Termes"   # serif (xelatex/lualatex only — uses fontspec)
  sansfont: "TeX Gyre Heros"    # sans (optional)
  monofont: "TeX Gyre Cursor"   # monospace (optional)
```

`mainfont`/`sansfont`/`monofont` are forwarded as pandoc `-V` flags and
require an engine that loads `fontspec` (xelatex or lualatex). They are
ignored under `pdflatex`.

### Tables

Configure table formatting for PDF output:

```yaml
tables:
  nowrap:
    - Prior           # Column headers to keep on one line
    - "$\\widehat{R}$"
```

In `nowrap` columns, distribution notation is auto-converted to LaTeX math:
- `Normal(0, 0.5)` → `$\mathcal{N}(0, 0.5)$`
- `Student-t(3, 0, 1)` → `$t_3(0, 1)$`
- `Gamma(2, 0.5)` → `$\text{Gamma}(2, 0.5)$`
- `Half-Normal(0, 1)` → `$\text{Half-Normal}(0, 1)$`
- `Exponential(1)` → `$\text{Exp}(1)$`

**Tip:** For complex tables, use simple tables (space-aligned with dashes) instead of pipe tables to avoid column width issues:

```markdown
  Parameter    Prior                       Description
  ----------   -------------------------   ------------------
  alpha        $\mathcal{N}(0, 0.5)$       Intercept prior
  beta         $t_3(0, 2.5)$               Slope prior
```

### Postprocess Scripts

Run custom scripts after output generation:

```yaml
postprocess:
  pdf: ./scripts/fix-pdf.py      # Runs after PDF
  docx: ./scripts/add-meta.js    # Runs after DOCX
  tex: ./scripts/tweak-latex.sh  # Runs after TEX
  pptx: ./scripts/fix-slides.ps1 # Runs after PPTX
  all: ./scripts/notify.js       # Runs after ANY format
```

**Environment variables** available to scripts:

| Variable | Description |
|----------|-------------|
| `OUTPUT_FILE` | Full path to generated file |
| `OUTPUT_FORMAT` | Format: `pdf`, `docx`, `tex`, `pptx`, `beamer` |
| `PROJECT_DIR` | Directory containing rev.yaml |
| `CONFIG_PATH` | Full path to rev.yaml |

**Supported script types:** `.js`, `.mjs` (Node), `.py` (Python), `.ps1` (PowerShell), `.sh` (Bash)

**Example Python script** (add DOCX metadata):
```python
import os
from docx import Document
doc = Document(os.environ['OUTPUT_FILE'])
doc.core_properties.author = "Research Team"
doc.save(os.environ['OUTPUT_FILE'])
```

Use `--verbose` flag to see script output:
```bash
rev build pdf --verbose
```

## Shell Completions

### rev completions
Output shell completions.
```bash
eval "$(rev completions bash)"  # Bash
eval "$(rev completions zsh)"   # Zsh
```

## AI Skill Installation

### rev install-cli-skill
Install the docrev skill for AI coding assistants.
```bash
rev install-cli-skill        # Install to ~/.claude/skills/docrev
```

### rev uninstall-cli-skill
Remove the installed skill.
```bash
rev uninstall-cli-skill
```