docrev 0.6.7 → 0.7.6

package/lib/wordcomments.js

@@ -2,9 +2,9 @@
  * Word comment injection with reply threading
  *
  * Flow:
- * 1. prepareMarkdownWithMarkers() - Parse comments, detect Guy→Gilles reply pairs
- *    - Guy comments get markers: ⟦CMS:n⟧anchor⟦CME:n⟧
- *    - Gilles replies: no markers (they attach to parent comment)
+ * 1. prepareMarkdownWithMarkers() - Parse comments, detect reply relationships
+ *    - First comment in a cluster = parent (gets markers: ⟦CMS:n⟧anchor⟦CME:n⟧)
+ *    - Subsequent adjacent comments = replies (no markers, attach to parent)
  * 2. Pandoc converts to DOCX
  * 3. injectCommentsAtMarkers() - Insert comment ranges for parents only
  *    - Replies go in comments.xml with parent reference in commentsExtended.xml
@@ -71,50 +71,41 @@ export function prepareMarkdownWithMarkers(markdown) {
     return { markedMarkdown: markdown, comments: [] };
   }
 
-  // Detect reply relationships: Gilles immediately following Guy = reply
-  // Comments are "adjacent" if there's only whitespace between them (< 50 chars)
-  const ADJACENT_THRESHOLD = 50;
+  // Detect reply relationships based on adjacency
+  // First comment in a cluster = parent, all subsequent = replies to that parent
+  // Comments are "adjacent" if there's minimal text between them (< 10 chars)
+  const ADJACENT_THRESHOLD = 10;
   const comments = [];
-  let lastGuyIdx = -1;
+  let clusterParentIdx = -1;  // Index of first comment in current cluster
   let lastCommentEnd = -1;
 
   for (let i = 0; i < rawMatches.length; i++) {
     const m = rawMatches[i];
-    const isGuy = m.author === 'Guy Colling';
-    const isGilles = m.author === 'Gilles Colling';
 
     // Check if this comment is adjacent to the previous one
     const gap = lastCommentEnd >= 0 ? m.start - lastCommentEnd : Infinity;
     const isAdjacent = gap < ADJACENT_THRESHOLD;
 
-    // Reset lastGuyIdx if there's a gap (comments not in same cluster)
+    // Reset cluster if there's a gap (comments not in same cluster)
     if (!isAdjacent) {
-      lastGuyIdx = -1;
+      clusterParentIdx = -1;
     }
 
-    if (isGuy) {
+    if (clusterParentIdx === -1) {
+      // First comment in cluster = parent (regardless of author)
       comments.push({
         ...m,
         isReply: false,
         parentIdx: null,
         commentIdx: comments.length
       });
-      lastGuyIdx = comments.length - 1;
-    } else if (isGilles && lastGuyIdx >= 0 && isAdjacent) {
-      // Gilles immediately following Guy (same cluster) = reply
-      comments.push({
-        ...m,
-        isReply: true,
-        parentIdx: lastGuyIdx,
-        commentIdx: comments.length
-      });
-      // Don't reset lastGuyIdx - multiple replies could follow
+      clusterParentIdx = comments.length - 1;
     } else {
-      // Standalone comment (not a reply)
+      // Subsequent comment in cluster = reply to first comment
       comments.push({
         ...m,
-        isReply: false,
-        parentIdx: null,
+        isReply: true,
+        parentIdx: clusterParentIdx,
         commentIdx: comments.length
       });
     }
@@ -122,6 +113,21 @@ export function prepareMarkdownWithMarkers(markdown) {
     lastCommentEnd = m.end;
   }
 
+  // Propagate anchors from replies to parents
+  // If a reply has an anchor but its parent doesn't, move the anchor to the parent
+  // Track flags for special handling during marker generation
+  for (const c of comments) {
+    if (c.isReply && c.anchor && c.parentIdx !== null) {
+      const parent = comments[c.parentIdx];
+      if (!parent.anchor) {
+        parent.anchor = c.anchor;
+        parent.anchorFromReply = true;  // Parent's anchor came from a reply (markers placed by reply)
+        c.placesParentMarkers = true;   // This reply should place the parent's markers
+        c.anchor = null;
+      }
+    }
+  }
+
   // Build marked markdown - only parent comments get markers
   // Process from end to start to preserve positions
   let markedMarkdown = markdown;
@@ -131,12 +137,43 @@ export function prepareMarkdownWithMarkers(markdown) {
 
     if (c.isReply) {
       // Reply: remove from document entirely (will be in comments.xml only)
-      markedMarkdown = markedMarkdown.slice(0, c.start) + markedMarkdown.slice(c.end);
+      // Also consume leading whitespace to avoid double spaces
+      let removeStart = c.start;
+      while (removeStart > 0 && /\s/.test(markedMarkdown[removeStart - 1])) {
+        removeStart--;
+      }
+
+      // If this reply places parent's markers (anchor was propagated)
+      if (c.placesParentMarkers && c.parentIdx !== null) {
+        // Extract anchor text from the original match
+        const anchorMatch = c.fullMatch.match(/\[([^\]]+)\]\{\.mark\}$/);
+        if (anchorMatch) {
+          const anchorText = anchorMatch[1];
+          // Output markers with PARENT's index around the anchor text
+          const parentIdx = c.parentIdx;
+          const replacement = `${MARKER_START_PREFIX}${parentIdx}${MARKER_SUFFIX}${anchorText}${MARKER_END_PREFIX}${parentIdx}${MARKER_SUFFIX}`;
+          markedMarkdown = markedMarkdown.slice(0, removeStart) + replacement + markedMarkdown.slice(c.end);
+        } else {
+          markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+        }
+      } else {
+        markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+      }
     } else {
-      // Parent comment: replace with markers
-      const anchor = c.anchor || '';
-      const replacement = `${MARKER_START_PREFIX}${i}${MARKER_SUFFIX}${anchor}${MARKER_END_PREFIX}${i}${MARKER_SUFFIX}`;
-      markedMarkdown = markedMarkdown.slice(0, c.start) + replacement + markedMarkdown.slice(c.end);
+      // Parent comment
+      if (c.anchorFromReply) {
+        // Anchor markers are placed by the reply, just remove this comment
+        let removeStart = c.start;
+        while (removeStart > 0 && /\s/.test(markedMarkdown[removeStart - 1])) {
+          removeStart--;
+        }
+        markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+      } else {
+        // Normal case: replace with markers
+        const anchor = c.anchor || '';
+        const replacement = `${MARKER_START_PREFIX}${i}${MARKER_SUFFIX}${anchor}${MARKER_END_PREFIX}${i}${MARKER_SUFFIX}`;
+        markedMarkdown = markedMarkdown.slice(0, c.start) + replacement + markedMarkdown.slice(c.end);
+      }
     }
   }
 
@@ -239,11 +276,7 @@ function createCommentsExtensibleXml(comments) {
   return xml;
 }
 
-// Known Windows Live user IDs for authors (from manual_comments.docx)
-const AUTHOR_USER_IDS = {
-  'Guy Colling': '9ff4d97962428673',
-  'Gilles Colling': '46e930a4c4b85dfd',
-};
+// Generate deterministic user IDs for authors (no hardcoded personal data)
 
 function createPeopleXml(comments) {
   // Extract unique authors
@@ -265,7 +298,7 @@ function createPeopleXml(comments) {
   xml += 'mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh">';
 
   for (const author of authors) {
-    const userId = AUTHOR_USER_IDS[author] || generateUserId(author);
+    const userId = generateUserId(author);
     xml += `<w15:person w15:author="${escapeXml(author)}">`;
     xml += `<w15:presenceInfo w15:providerId="Windows Live" w15:userId="${userId}"/>`;
     xml += `</w15:person>`;
@@ -366,9 +399,23 @@ export async function injectCommentsAtMarkers(docxPath, comments, outputPath) {
       const endInText = fullText.indexOf(endMarker);
       if (startInText === -1 || endInText === -1) continue;
 
-      const textBefore = fullText.slice(0, startInText);
-      const anchorText = fullText.slice(startInText + startMarker.length, endInText);
-      const textAfter = fullText.slice(endInText + endMarker.length);
+      let textBefore = fullText.slice(0, startInText);
+      let anchorText = fullText.slice(startInText + startMarker.length, endInText);
+      let textAfter = fullText.slice(endInText + endMarker.length);
+
+      // When anchor is empty, use the first word from textAfter as fallback
+      if (!anchorText && textAfter) {
+        const wordMatch = textAfter.match(/^\s*(\S+)/);
+        if (wordMatch) {
+          anchorText = wordMatch[1];
+          textAfter = textAfter.slice(wordMatch[0].length);
+        }
+      }
+
+      // When anchor is still empty, normalize double spaces to single space
+      if (!anchorText && textBefore.endsWith(' ') && textAfter.startsWith(' ')) {
+        textAfter = textAfter.slice(1); // Remove leading space from textAfter
+      }
 
       // Build replacement
       let replacement = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docrev",
-  "version": "0.6.7",
+  "version": "0.7.6",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",
@@ -114,11 +114,13 @@
     "dictionary-en": "^4.0.0",
     "dictionary-en-gb": "^3.0.0",
     "diff": "^8.0.2",
-    "js-yaml": "^4.1.1",
     "mammoth": "^1.6.0",
     "mathml-to-latex": "^1.5.0",
     "nspell": "^2.1.5",
-    "xml2js": "^0.6.2"
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^5.4.530",
+    "xml2js": "^0.6.2",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "c8": "^10.1.2"

package/skill/REFERENCE.md

@@ -1,12 +1,29 @@
 # 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 --file manuscript.docx
-rev import -f manuscript.docx --output ./project
+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 build
@@ -16,8 +33,13 @@ 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
 ```
 
+The `--dual` flag produces:
+- `paper.docx` — clean, for submission
+- `paper_comments.docx` — includes comment threads as Word comments
+
 ### rev preview
 Build and open document in default app.
 ```bash
@@ -62,9 +84,44 @@ rev resolve methods.md -n 1,2,3   # Multiple comments
 ```
 
 ### rev status
-Show annotation counts for a file.
+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 status methods.md
+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
@@ -202,7 +259,7 @@ rev equations list           # List all equations
 rev equations from-word manuscript.docx  # Extract from Word
 ```
 
-## Direct DOCX Editing
+## Direct DOCX Editing (Layout Workflow)
 
 ### rev annotate
 Add comments directly to Word document.
@@ -224,19 +281,6 @@ rev comment paper.docx
 
 ## Project Management
 
-### rev init
-Initialize a new paper project.
-```bash
-rev init my-paper
-rev init my-paper --template apa
-```
-
-### rev sections
-List and manage section files.
-```bash
-rev sections                 # List all sections
-```
-
 ### rev clean
 Remove generated files.
 ```bash
@@ -277,3 +321,17 @@ Output shell completions.
 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
+```

package/skill/SKILL.md

@@ -1,30 +1,63 @@
 ---
 name: docrev
-description: "Academic paper 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 academic paper revision task."
+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 - Academic Paper Revision Tool
+# docrev - Document Revision Tool
 
-`rev` is a CLI tool for academic paper workflows with Word ↔ Markdown round-trips.
+`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"
+output:
+  docx:
+    reference-doc: template.docx
+```
+
+Change the template, rebuild, and every document gets the new formatting.
 
 ## Core Workflow
 
-### 1. Import reviewed Word document
+### 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 import --file manuscript-reviewed.docx
+rev build docx               # Generate Word document
 ```
 
-This extracts track changes and comments as CriticMarkup annotations in markdown files.
+Send to reviewers. They add comments and track changes in Word.
 
-### 2. View and address comments
+### 3. Import feedback
 
 ```bash
-rev comments methods.md              # List all comments with context
-rev status methods.md                # Show annotation counts
+rev sync reviewed.docx       # Updates markdown with annotations
+rev sync                     # Auto-detect most recent .docx
 ```
 
-### 3. Reply to reviewer comments
+### 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:**
 
@@ -35,25 +68,31 @@ rev reply results.md -n 3 -m "Updated figure to include 95% CI"
 
 Replies appear as: `{>>Reviewer: Original<<} {>>User: Reply<<}`
 
-### 4. Resolve addressed comments
+### 6. Resolve addressed comments
+
+```bash
+rev resolve methods.md -n 1  # Mark comment #1 as resolved
+```
+
+### 7. Rebuild with comment threads
 
 ```bash
-rev resolve methods.md -n 1          # Mark comment #1 as resolved
+rev build docx --dual        # Produces clean + annotated versions
 ```
 
-### 5. Build output documents
+- `paper.docx` — clean, for submission
+- `paper_comments.docx` — includes comment threads as Word comments
+
+### 8. Archive reviewer files
 
 ```bash
-rev build                            # Build both PDF and DOCX
-rev build docx                       # Word only
-rev build pdf                        # PDF only
-rev build --toc                      # Include table of contents
+rev archive                  # Move reviewer files to archive/
 ```
 
-### 6. Generate response letter
+### 9. Generate response letter
 
 ```bash
-rev response                         # Generate point-by-point response letter
+rev response                 # Generate point-by-point response letter
 ```
 
 ## Annotation Syntax (CriticMarkup)
@@ -68,8 +107,28 @@ rev response                         # Generate point-by-point response letter
 
 | 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 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` |
+| Show contributors | `rev contributors` |
+| Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
+| Archive reviewer files | `rev archive` |
 | Word count per section | `rev word-count` |
-| Word count with limit | `rev word-count --limit 5000` |
 | Project dashboard | `rev stats` |
 | Search all sections | `rev search "query"` |
 | Pre-submission check | `rev check` |
@@ -78,6 +137,7 @@ rev response                         # Generate point-by-point response letter
 | Check spelling | `rev spelling` |
 | Open PDF preview | `rev preview pdf` |
 | Auto-rebuild on changes | `rev watch` |
+| Check for updates | `rev upgrade --check` |
 
 ## DOI Management
 
@@ -115,7 +175,7 @@ Available in section files (processed during build):
 ## Project Structure
 
 ```
-my-paper/
+my-document/
 ├── rev.yaml           # Project config
 ├── introduction.md    # Section files with annotations
 ├── methods.md
@@ -126,17 +186,52 @@ my-paper/
 └── paper.docx         # Built output
 ```
 
+## 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. **Import phase**: Run `rev import` to get track changes as markdown
-2. **Review phase**: Use `rev comments` to see all comments, then `rev reply` to respond
-3. **Build phase**: Run `rev build docx` to generate the updated Word document
-4. **Validation phase**: Run `rev check` before submission (lint + grammar + citations)
-5. **Response letter**: Use `rev response` to generate point-by-point responses
+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 scientific papers:
+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

package/.rev-dictionary

@@ -1,4 +0,0 @@
-# Custom dictionary for docrev
-# Add one word per line
-# Lines starting with # are comments
-