docrev 0.11.0 → 0.11.2

package/skill/REFERENCE.md

@@ -1,539 +1,550 @@
-# 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
-```
+# 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 --dual --show-changes  # One DOCX: tracked changes + threaded comments
+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
+(`output/<title>-changes.docx`) where every insertion/deletion/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. The revisions are emitted by pandoc as native run-level `w:ins`/`w:del`
+elements through the full filter chain (crossref, citeproc, reference-doc,
+macros) — not post-processed markers.
+
+Combine `--dual --show-changes` to get one `output/<title>-changes.docx` with
+tracked changes AND threaded comments: your `{++..++}`/`{--..--}` edits as
+track changes alongside the reviewer's `{>>..<<}` comments and your threaded
+replies. This is the standard "return to senior author" artifact. Add
+`--reference <docx>` to realign comment anchors against a reviewer's copy
+before injecting.
+
+### 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
+```