docrev 0.11.0 → 0.11.2

package/skill/SKILL.md

@@ -1,295 +1,302 @@
----
-name: docrev
-description: "Document revision workflow tool (CLI: `rev`). Use when working with Word documents containing reviewer comments, importing track changes to markdown, replying to reviewer comments, building PDF/DOCX outputs, generating response letters, validating citations/DOIs, or any document revision task."
----
-
-# docrev - Document Revision Tool
-
-`rev` is a CLI tool for document workflows with Word ↔ Markdown round-trips.
-
-Works for any document that goes through Word-based review: scientific papers, contracts, reports, proposals, manuals.
-
-## Content and Layout, Separated
-
-In Markdown, you focus on content. Write text, add citations with `[@key]`, insert equations with `$...$`, reference figures with `@fig:label`. No fiddling with fonts or styles.
-
-Layout is controlled in `rev.yaml`:
-
-```yaml
-title: "My Document"
-docx:
-  reference: template.docx
-```
-
-Change the template, rebuild, and every document gets the new formatting.
-
-## Core Workflow
-
-### 1. Create or import a project
-
-```bash
-rev new my-document          # Start from scratch
-rev import manuscript.docx   # Start from existing Word doc
-```
-
-### 2. Build and share
-
-```bash
-rev build docx               # Generate Word document
-```
-
-Send to reviewers. They add comments and track changes in Word.
-
-### 3. Import feedback
-
-```bash
-rev sync reviewed.docx              # Updates markdown with annotations
-rev sync                            # Auto-detect most recent .docx
-rev sync reviewed.docx --comments-only  # Insert comments only; never modify prose
-rev verify-anchors reviewed.docx    # Report which anchors still match current prose
-```
-
-Use `--comments-only` when the markdown has been revised between sending the
-docx out and receiving it back. Without the flag, track changes from a stale
-draft would clobber newer edits. With it, only comments are imported, placed
-at fuzzy-matched anchors against the current prose. Run `rev verify-anchors`
-first to see which comments will land cleanly and which need manual placement.
-
-### 4. View and address comments
-
-```bash
-rev status                   # Project overview
-rev todo                     # List all pending comments
-rev next                     # Show next pending comment
-rev comments methods.md      # List all comments with context
-```
-
-### 5. Reply to reviewer comments
-
-**Always use the non-interactive reply mode:**
-
-```bash
-rev reply methods.md -n 1 -m "Added clarification about sampling methodology"
-rev reply results.md -n 3 -m "Updated figure to include 95% CI"
-```
-
-Replies appear as: `{>>Reviewer: Original<<} {>>User: Reply<<}`
-
-### 6. Resolve addressed comments
-
-```bash
-rev resolve methods.md -n 1  # Mark comment #1 as resolved
-```
-
-### 7. Rebuild with comment threads
-
-```bash
-rev build docx --dual            # Produces clean + annotated versions
-rev build docx --show-changes    # Single DOCX with visible track changes
-```
-
-`--dual` produces:
-- `output/<title>.docx` — clean, for submission
-- `output/<title>_comments.docx` — comment threads as Word comments
-
-`--show-changes` produces a single audit DOCX where every accepted/rejected
-revision is rendered as a visible Word track change. Useful when a co-author
-wants to see what changed since the last shared version.
-
-Outputs land in `output/` by default; set `outputDir: null` in `rev.yaml`
-to keep them alongside `paper.md` (legacy layout). The basename is derived
-from `title:` unless overridden — set `output: { docx: foo.docx, pdf: foo.pdf }`
-in `rev.yaml` or pass `-o, --output <path>` on the CLI. See REFERENCE.md →
-"Choosing output filenames".
-
-For pandoc flags rev doesn't surface directly (Lua filters, custom variables,
-templates), use `--pandoc-arg` (repeatable) or `pandoc-args:` in `rev.yaml`
-(both top-level and per-format). Run with `--verbose` to see the exact pandoc
-invocation. See REFERENCE.md → "Passing custom pandoc args" for details.
-
-### 8. Archive reviewer files
-
-```bash
-rev archive                  # Move reviewer files to archive/
-```
-
-### 9. Generate response letter
-
-```bash
-rev response                 # Generate point-by-point response letter
-```
-
-## Annotation Syntax (CriticMarkup)
-
-- `{++inserted text++}` - Additions
-- `{--deleted text--}` - Deletions
-- `{~~old~>new~~}` - Substitutions
-- `{>>Author: comment<<}` - Comments
-- `{>>Author: comment [RESOLVED]<<}` - Resolved comment
-
-## Quick Commands
-
-| Task | Command |
-|------|---------|
-| Create project | `rev new my-project` |
-| Create LaTeX project | `rev new my-project --template latex` |
-| Import Word doc | `rev import manuscript.docx` |
-| Sync Word feedback | `rev sync reviewed.docx` |
-| Sync comments only (prose unchanged) | `rev sync reviewed.docx --comments-only` |
-| Verify anchors against current prose | `rev verify-anchors reviewed.docx` |
-| Sync PDF comments | `rev sync annotated.pdf` |
-| Extract PDF comments | `rev pdf-comments annotated.pdf` |
-| Extract with highlighted text | `rev pdf-comments file.pdf --with-text` |
-| Append PDF comments | `rev pdf-comments annotated.pdf --append methods.md` |
-| Project status | `rev status` |
-| Next pending | `rev next` |
-| List pending | `rev todo` |
-| Filter by author | `rev comments file.md --author "Reviewer 2"` |
-| Reply to all pending | `rev reply file.md --all -m "Addressed"` |
-| Accept all changes | `rev accept file.md -a` |
-| Build Word | `rev build docx` |
-| Build PDF | `rev build pdf` |
-| Build clean + annotated Word | `rev build docx --dual` |
-| Build clean + annotated PDF | `rev build pdf --dual` |
-| Build with visible track changes | `rev build docx --show-changes` |
-| Show contributors | `rev contributors` |
-| Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
-| Archive reviewer files | `rev archive` |
-| Word count per section | `rev word-count` |
-| Project dashboard | `rev stats` |
-| Search all sections | `rev search "query"` |
-| Pre-submission check | `rev check` |
-| Validate citations | `rev citations` |
-| Check grammar/style | `rev grammar` |
-| Check spelling | `rev spelling` |
-| Open PDF preview | `rev preview pdf` |
-| Auto-rebuild on changes | `rev watch` |
-| Check for updates | `rev upgrade --check` |
-
-## DOI Management
-
-```bash
-rev doi check references.bib         # Validate DOIs
-rev doi lookup references.bib        # Find missing DOIs
-rev doi add 10.1234/example          # Add citation from DOI
-```
-
-## Validation
-
-```bash
-rev validate --journal nature        # Check journal requirements
-rev validate --list                  # List 22 available journal profiles
-rev lint                             # Check broken refs, missing citations
-```
-
-## Cross-References
-
-Use in markdown files:
-- `@fig:label` - Figure reference (becomes "Figure 1" in Word)
-- `@tbl:label` - Table reference
-- `@eq:label` - Equation reference
-- `{#fig:label}` - Anchor for figures
-
-Insert a figure with the format-portable syntax (renders in both PDF and Word):
-
-```markdown
-![Caption text.](figures/foo.pdf){#fig:foo width=80%}
-```
-
-Raw `\begin{figure}...\end{figure}` LaTeX blocks are PDF-only. For docx
-builds, `rev` auto-translates the common shape (single `\includegraphics`
-with optional `\caption{...}` and `\label{...}`) to the markdown form above
-so figures still render. Exotic blocks (`\subfloat`, `\rotatebox`, multiple
-`\includegraphics`) are left alone and warned about — convert them by hand
-or supply a custom Lua filter via `--pandoc-arg`. Opt out of auto-translate
-with `docx.translateRawFigures: false` in `rev.yaml`.
-
-## Template Variables
-
-Available in section files (processed during build):
-- `{{date}}` - Current date (YYYY-MM-DD)
-- `{{date:MMMM D, YYYY}}` - Custom format
-- `{{title}}` - Document title
-- `{{author}}` - First author
-- `{{word_count}}` - Total word count
-
-## Project Structure
-
-```
-my-document/
-├── rev.yaml           # Project config
-├── introduction.md    # Section files with annotations
-├── methods.md
-├── results.md
-├── discussion.md
-├── references.bib     # Bibliography
-├── figures/           # Images
-├── paper.md           # Combined sections (auto-generated)
-└── output/            # Built artefacts
-    ├── my-document.docx
-    └── my-document.pdf
-```
-
-Set `outputDir: null` in `rev.yaml` to write outputs alongside `paper.md`
-instead.
-
-## PDF Comment Workflow
-
-For reviewers who annotate PDFs instead of Word documents:
-
-### 1. Extract comments from PDF
-
-```bash
-rev pdf-comments annotated.pdf              # Display all comments
-rev pdf-comments annotated.pdf --by-author  # Group by reviewer
-rev pdf-comments annotated.pdf --json       # Output as JSON
-```
-
-### 2. Import into markdown
-
-```bash
-rev sync annotated.pdf                      # Auto-import to sections
-rev pdf-comments annotated.pdf --append methods.md  # Append to specific file
-```
-
-### 3. Build PDF with margin notes
-
-```bash
-rev build pdf --dual
-```
-
-Produces:
-- `paper.pdf` — clean version for submission
-- `paper_comments.pdf` — comments rendered as LaTeX margin notes
-
-**Supported PDF Annotations:**
-- Sticky notes, text boxes, highlights, underlines, strikethrough, squiggly
-
-## When Helping Users
-
-1. **Setup**: Ensure `rev config user "Name"` is set for replies
-2. **Sync phase**: Run `rev sync` to get feedback (works with both Word and PDF)
-3. **Review phase**: Use `rev todo` and `rev next` to navigate comments, `rev reply` to respond
-4. **Accept phase**: Use `rev accept -a` or `rev review` to handle track changes
-5. **Build phase**: Run `rev build docx --dual` or `rev build pdf --dual` for annotated versions
-6. **Archive phase**: Run `rev archive` to move reviewer files
-7. **Validation phase**: Run `rev check` before submission
-8. **Response letter**: Use `rev response` to generate point-by-point responses
-
-## Critical: Ask Questions When Unsure
-
-When addressing reviewer comments or editing documents:
-
-- **Never guess methods or numbers** - If a comment asks for clarification about methodology, sample sizes, statistical parameters, dates, or any quantitative information, ASK the user rather than inventing values
-- **Placeholders are acceptable** - Use `[???]` or `[TODO: specify X]` when information is missing rather than fabricating data
-- **Search online for references** - When comments request citations, use web search to find appropriate references rather than guessing
-- **Clarify ambiguous requests** - If a reviewer comment could be interpreted multiple ways, ask the user which interpretation they prefer
-- **Verify existing values** - When editing numbers that already exist in the document, confirm changes with the user if there's any doubt
-
-Example scenarios requiring user input:
-- "Add a reference for this claim" → Search online OR ask user for specific citation
-- "Clarify the sample size" → Ask user for the correct number
-- "Specify the statistical test used" → Ask user which test was actually used
-- "Add the date of data collection" → Ask user for the actual date
-
-For complete command reference, see [REFERENCE.md](REFERENCE.md).
+---
+name: docrev
+description: "Document revision workflow tool (CLI: `rev`). Use when working with Word documents containing reviewer comments, importing track changes to markdown, replying to reviewer comments, building PDF/DOCX outputs, generating response letters, validating citations/DOIs, or any document revision task."
+---
+
+# docrev - Document Revision Tool
+
+`rev` is a CLI tool for document workflows with Word ↔ Markdown round-trips.
+
+Works for any document that goes through Word-based review: scientific papers, contracts, reports, proposals, manuals.
+
+## Content and Layout, Separated
+
+In Markdown, you focus on content. Write text, add citations with `[@key]`, insert equations with `$...$`, reference figures with `@fig:label`. No fiddling with fonts or styles.
+
+Layout is controlled in `rev.yaml`:
+
+```yaml
+title: "My Document"
+docx:
+  reference: template.docx
+```
+
+Change the template, rebuild, and every document gets the new formatting.
+
+## Core Workflow
+
+### 1. Create or import a project
+
+```bash
+rev new my-document          # Start from scratch
+rev import manuscript.docx   # Start from existing Word doc
+```
+
+### 2. Build and share
+
+```bash
+rev build docx               # Generate Word document
+```
+
+Send to reviewers. They add comments and track changes in Word.
+
+### 3. Import feedback
+
+```bash
+rev sync reviewed.docx              # Updates markdown with annotations
+rev sync                            # Auto-detect most recent .docx
+rev sync reviewed.docx --comments-only  # Insert comments only; never modify prose
+rev verify-anchors reviewed.docx    # Report which anchors still match current prose
+```
+
+Use `--comments-only` when the markdown has been revised between sending the
+docx out and receiving it back. Without the flag, track changes from a stale
+draft would clobber newer edits. With it, only comments are imported, placed
+at fuzzy-matched anchors against the current prose. Run `rev verify-anchors`
+first to see which comments will land cleanly and which need manual placement.
+
+### 4. View and address comments
+
+```bash
+rev status                   # Project overview
+rev todo                     # List all pending comments
+rev next                     # Show next pending comment
+rev comments methods.md      # List all comments with context
+```
+
+### 5. Reply to reviewer comments
+
+**Always use the non-interactive reply mode:**
+
+```bash
+rev reply methods.md -n 1 -m "Added clarification about sampling methodology"
+rev reply results.md -n 3 -m "Updated figure to include 95% CI"
+```
+
+Replies appear as: `{>>Reviewer: Original<<} {>>User: Reply<<}`
+
+### 6. Resolve addressed comments
+
+```bash
+rev resolve methods.md -n 1  # Mark comment #1 as resolved
+```
+
+### 7. Rebuild with comment threads
+
+```bash
+rev build docx --dual                 # Produces clean + annotated versions
+rev build docx --show-changes         # Single DOCX with visible track changes
+rev build docx --dual --show-changes  # One DOCX: tracked changes + threaded comments
+```
+
+`--dual` produces:
+- `output/<title>.docx` — clean, for submission
+- `output/<title>_comments.docx` — comment threads as Word comments
+
+`--show-changes` produces a single audit DOCX (`<title>-changes.docx`) where
+every accepted/rejected revision is rendered as a visible Word track change.
+Useful when a co-author wants to see what changed since the last shared version.
+
+`--dual --show-changes` combines both into one `<title>-changes.docx`: my
+`{++..++}`/`{--..--}` edits as tracked changes *and* the reviewer's `{>>..<<}`
+comments with my threaded replies. This is the file a supervisor opens,
+reviews next to each other, and hands back. Add `--reference <docx>` to
+realign comment anchors against a reviewer's copy first.
+
+Outputs land in `output/` by default; set `outputDir: null` in `rev.yaml`
+to keep them alongside `paper.md` (legacy layout). The basename is derived
+from `title:` unless overridden — set `output: { docx: foo.docx, pdf: foo.pdf }`
+in `rev.yaml` or pass `-o, --output <path>` on the CLI. See REFERENCE.md →
+"Choosing output filenames".
+
+For pandoc flags rev doesn't surface directly (Lua filters, custom variables,
+templates), use `--pandoc-arg` (repeatable) or `pandoc-args:` in `rev.yaml`
+(both top-level and per-format). Run with `--verbose` to see the exact pandoc
+invocation. See REFERENCE.md → "Passing custom pandoc args" for details.
+
+### 8. Archive reviewer files
+
+```bash
+rev archive                  # Move reviewer files to archive/
+```
+
+### 9. Generate response letter
+
+```bash
+rev response                 # Generate point-by-point response letter
+```
+
+## Annotation Syntax (CriticMarkup)
+
+- `{++inserted text++}` - Additions
+- `{--deleted text--}` - Deletions
+- `{~~old~>new~~}` - Substitutions
+- `{>>Author: comment<<}` - Comments
+- `{>>Author: comment [RESOLVED]<<}` - Resolved comment
+
+## Quick Commands
+
+| Task | Command |
+|------|---------|
+| Create project | `rev new my-project` |
+| Create LaTeX project | `rev new my-project --template latex` |
+| Import Word doc | `rev import manuscript.docx` |
+| Sync Word feedback | `rev sync reviewed.docx` |
+| Sync comments only (prose unchanged) | `rev sync reviewed.docx --comments-only` |
+| Verify anchors against current prose | `rev verify-anchors reviewed.docx` |
+| Sync PDF comments | `rev sync annotated.pdf` |
+| Extract PDF comments | `rev pdf-comments annotated.pdf` |
+| Extract with highlighted text | `rev pdf-comments file.pdf --with-text` |
+| Append PDF comments | `rev pdf-comments annotated.pdf --append methods.md` |
+| Project status | `rev status` |
+| Next pending | `rev next` |
+| List pending | `rev todo` |
+| Filter by author | `rev comments file.md --author "Reviewer 2"` |
+| Reply to all pending | `rev reply file.md --all -m "Addressed"` |
+| Accept all changes | `rev accept file.md -a` |
+| Build Word | `rev build docx` |
+| Build PDF | `rev build pdf` |
+| Build clean + annotated Word | `rev build docx --dual` |
+| Build clean + annotated PDF | `rev build pdf --dual` |
+| Build with visible track changes | `rev build docx --show-changes` |
+| Show contributors | `rev contributors` |
+| Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
+| Archive reviewer files | `rev archive` |
+| Word count per section | `rev word-count` |
+| Project dashboard | `rev stats` |
+| Search all sections | `rev search "query"` |
+| Pre-submission check | `rev check` |
+| Validate citations | `rev citations` |
+| Check grammar/style | `rev grammar` |
+| Check spelling | `rev spelling` |
+| Open PDF preview | `rev preview pdf` |
+| Auto-rebuild on changes | `rev watch` |
+| Check for updates | `rev upgrade --check` |
+
+## DOI Management
+
+```bash
+rev doi check references.bib         # Validate DOIs
+rev doi lookup references.bib        # Find missing DOIs
+rev doi add 10.1234/example          # Add citation from DOI
+```
+
+## Validation
+
+```bash
+rev validate --journal nature        # Check journal requirements
+rev validate --list                  # List 22 available journal profiles
+rev lint                             # Check broken refs, missing citations
+```
+
+## Cross-References
+
+Use in markdown files:
+- `@fig:label` - Figure reference (becomes "Figure 1" in Word)
+- `@tbl:label` - Table reference
+- `@eq:label` - Equation reference
+- `{#fig:label}` - Anchor for figures
+
+Insert a figure with the format-portable syntax (renders in both PDF and Word):
+
+```markdown
+![Caption text.](figures/foo.pdf){#fig:foo width=80%}
+```
+
+Raw `\begin{figure}...\end{figure}` LaTeX blocks are PDF-only. For docx
+builds, `rev` auto-translates the common shape (single `\includegraphics`
+with optional `\caption{...}` and `\label{...}`) to the markdown form above
+so figures still render. Exotic blocks (`\subfloat`, `\rotatebox`, multiple
+`\includegraphics`) are left alone and warned about — convert them by hand
+or supply a custom Lua filter via `--pandoc-arg`. Opt out of auto-translate
+with `docx.translateRawFigures: false` in `rev.yaml`.
+
+## Template Variables
+
+Available in section files (processed during build):
+- `{{date}}` - Current date (YYYY-MM-DD)
+- `{{date:MMMM D, YYYY}}` - Custom format
+- `{{title}}` - Document title
+- `{{author}}` - First author
+- `{{word_count}}` - Total word count
+
+## Project Structure
+
+```
+my-document/
+├── rev.yaml           # Project config
+├── introduction.md    # Section files with annotations
+├── methods.md
+├── results.md
+├── discussion.md
+├── references.bib     # Bibliography
+├── figures/           # Images
+├── paper.md           # Combined sections (auto-generated)
+└── output/            # Built artefacts
+    ├── my-document.docx
+    └── my-document.pdf
+```
+
+Set `outputDir: null` in `rev.yaml` to write outputs alongside `paper.md`
+instead.
+
+## PDF Comment Workflow
+
+For reviewers who annotate PDFs instead of Word documents:
+
+### 1. Extract comments from PDF
+
+```bash
+rev pdf-comments annotated.pdf              # Display all comments
+rev pdf-comments annotated.pdf --by-author  # Group by reviewer
+rev pdf-comments annotated.pdf --json       # Output as JSON
+```
+
+### 2. Import into markdown
+
+```bash
+rev sync annotated.pdf                      # Auto-import to sections
+rev pdf-comments annotated.pdf --append methods.md  # Append to specific file
+```
+
+### 3. Build PDF with margin notes
+
+```bash
+rev build pdf --dual
+```
+
+Produces:
+- `paper.pdf` — clean version for submission
+- `paper_comments.pdf` — comments rendered as LaTeX margin notes
+
+**Supported PDF Annotations:**
+- Sticky notes, text boxes, highlights, underlines, strikethrough, squiggly
+
+## When Helping Users
+
+1. **Setup**: Ensure `rev config user "Name"` is set for replies
+2. **Sync phase**: Run `rev sync` to get feedback (works with both Word and PDF)
+3. **Review phase**: Use `rev todo` and `rev next` to navigate comments, `rev reply` to respond
+4. **Accept phase**: Use `rev accept -a` or `rev review` to handle track changes
+5. **Build phase**: Run `rev build docx --dual` or `rev build pdf --dual` for annotated versions
+6. **Archive phase**: Run `rev archive` to move reviewer files
+7. **Validation phase**: Run `rev check` before submission
+8. **Response letter**: Use `rev response` to generate point-by-point responses
+
+## Critical: Ask Questions When Unsure
+
+When addressing reviewer comments or editing documents:
+
+- **Never guess methods or numbers** - If a comment asks for clarification about methodology, sample sizes, statistical parameters, dates, or any quantitative information, ASK the user rather than inventing values
+- **Placeholders are acceptable** - Use `[???]` or `[TODO: specify X]` when information is missing rather than fabricating data
+- **Search online for references** - When comments request citations, use web search to find appropriate references rather than guessing
+- **Clarify ambiguous requests** - If a reviewer comment could be interpreted multiple ways, ask the user which interpretation they prefer
+- **Verify existing values** - When editing numbers that already exist in the document, confirm changes with the user if there's any doubt
+
+Example scenarios requiring user input:
+- "Add a reference for this claim" → Search online OR ask user for specific citation
+- "Clarify the sample size" → Ask user for the correct number
+- "Specify the statistical test used" → Ask user which test was actually used
+- "Add the date of data collection" → Ask user for the actual date
+
+For complete command reference, see [REFERENCE.md](REFERENCE.md).