overleaf-comments-export 0.2.0__tar.gz → 0.3.0__tar.gz

{overleaf_comments_export-0.2.0 → overleaf_comments_export-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overleaf-comments-export
-Version: 0.2.0
+Version: 0.3.0
 Summary: Export comment threads and tracked changes from an Overleaf project to Markdown + JSON, optimized for AI-agent consumption.
 Author: Shivang
 License: MIT
@@ -137,10 +137,30 @@ by browser on macOS:
 | Chrome / Edge / Brave | Cookies are AES-encrypted with a Keychain-stored key; **you'll get a Keychain password prompt every run.** Hidden behind an opt-in in the GUI. |
 
 On Windows, Chrome 127+ uses App-Bound Encryption that `browser-cookie3`
-doesn't fully decrypt yet — prefer Firefox or Edge on Windows.
+can't decrypt. On Linux, snap-packaged browsers sandbox their cookie stores.
 
-On Linux, snap-packaged browsers sandbox their cookies — install browsers as
-native packages if you can.
+**If reading the cookie from your browser fails, paste it instead** — this
+works on every OS and browser:
+
+```bash
+overleaf-comments-export --project-url <url> --out ./out --cookie "PASTE_HERE"
+```
+
+Or set it once: `export OVERLEAF_SESSION="PASTE_HERE"`. In the GUI, choose
+**"Paste the cookie myself"** and click **How?** for step-by-step instructions.
+
+To find it: open Overleaf, press F12, go to Application (or Storage) →
+Cookies → `https://www.overleaf.com`, and copy the Value of `overleaf_session2`.
+Treat it like a password; it stops working when you sign out.
+
+## Troubleshooting
+
+| What you see | What it means |
+|---|---|
+| "Could not look up www.overleaf.com" | This computer is offline, or a VPN/DNS problem. Not an Overleaf issue. |
+| "Overleaf refused the request (not signed in)" | Your session expired. Sign in again in the browser, then re-run. |
+| "Could not read Overleaf cookies from chrome" | Use the paste-the-cookie method above. |
+| "Overleaf could not find that project" | Wrong link, or this account has no access. |
 
 ## Status & maintenance
 

{overleaf_comments_export-0.2.0 → overleaf_comments_export-0.3.0}/README.md

@@ -101,10 +101,30 @@ by browser on macOS:
 | Chrome / Edge / Brave | Cookies are AES-encrypted with a Keychain-stored key; **you'll get a Keychain password prompt every run.** Hidden behind an opt-in in the GUI. |
 
 On Windows, Chrome 127+ uses App-Bound Encryption that `browser-cookie3`
-doesn't fully decrypt yet — prefer Firefox or Edge on Windows.
+can't decrypt. On Linux, snap-packaged browsers sandbox their cookie stores.
 
-On Linux, snap-packaged browsers sandbox their cookies — install browsers as
-native packages if you can.
+**If reading the cookie from your browser fails, paste it instead** — this
+works on every OS and browser:
+
+```bash
+overleaf-comments-export --project-url <url> --out ./out --cookie "PASTE_HERE"
+```
+
+Or set it once: `export OVERLEAF_SESSION="PASTE_HERE"`. In the GUI, choose
+**"Paste the cookie myself"** and click **How?** for step-by-step instructions.
+
+To find it: open Overleaf, press F12, go to Application (or Storage) →
+Cookies → `https://www.overleaf.com`, and copy the Value of `overleaf_session2`.
+Treat it like a password; it stops working when you sign out.
+
+## Troubleshooting
+
+| What you see | What it means |
+|---|---|
+| "Could not look up www.overleaf.com" | This computer is offline, or a VPN/DNS problem. Not an Overleaf issue. |
+| "Overleaf refused the request (not signed in)" | Your session expired. Sign in again in the browser, then re-run. |
+| "Could not read Overleaf cookies from chrome" | Use the paste-the-cookie method above. |
+| "Overleaf could not find that project" | Wrong link, or this account has no access. |
 
 ## Status & maintenance
 

overleaf_comments_export-0.3.0/overleaf_comments_export/__init__.py

@@ -0,0 +1,8 @@
+"""Export Overleaf comment threads and tracked changes."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("overleaf-comments-export")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0-dev"

{overleaf_comments_export-0.2.0 → overleaf_comments_export-0.3.0}/overleaf_comments_export/__main__.py

@@ -2,10 +2,12 @@ from __future__ import annotations
 
 import argparse
 import logging
+import os
 import sys
 from pathlib import Path
 
-from .client import OverleafClient
+from . import __version__
+from .client import OverleafClient, UserFacingError
 from .export import ExportResult, run_export
 
 
@@ -39,6 +41,15 @@ def main(argv: list[str] | None = None) -> int:
         choices=list(OverleafClient.SUPPORTED_BROWSERS),
         help="Which browser to read cookies from. Default: auto-detect.",
     )
+    parser.add_argument(
+        "--cookie",
+        default=None,
+        metavar="VALUE",
+        help="Overleaf session cookie, pasted from your browser (DevTools → "
+        "Application → Cookies → overleaf_session2). Use this when reading "
+        "cookies from the browser fails. Also read from the OVERLEAF_SESSION "
+        "environment variable.",
+    )
     parser.add_argument(
         "--base-url",
         default="https://www.overleaf.com",
@@ -47,6 +58,9 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "-v", "--verbose", action="store_true", help="More logging."
     )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
     parser.add_argument(
         "--render-mode",
         choices=["compact", "detailed"],
@@ -118,23 +132,31 @@ def main(argv: list[str] | None = None) -> int:
         stream=sys.stderr,
     )
 
-    result: ExportResult = run_export(
-        project_url=args.project_url,
-        out_dir=args.out,
-        project_title=args.project_title,
-        base_url=args.base_url,
-        browser=args.browser,
-        verbose=args.verbose,
-        include_raw=args.include_raw,
-        include_open=args.include_open,
-        include_resolved=args.include_resolved,
-        include_changes=args.include_changes,
-        reviewer_filter=args.reviewer,
-        render_mode=args.render_mode,
-        write_jsonl=args.write_jsonl,
-        per_reviewer_reports=args.per_reviewer,
-        progress=lambda msg: print(msg, file=sys.stderr),
-    )
+    cookie_value = args.cookie or os.environ.get("OVERLEAF_SESSION") or None
+
+    try:
+        result: ExportResult = run_export(
+            project_url=args.project_url,
+            out_dir=args.out,
+            project_title=args.project_title,
+            base_url=args.base_url,
+            browser=args.browser,
+            cookie_value=cookie_value,
+            verbose=args.verbose,
+            include_raw=args.include_raw,
+            include_open=args.include_open,
+            include_resolved=args.include_resolved,
+            include_changes=args.include_changes,
+            reviewer_filter=args.reviewer,
+            render_mode=args.render_mode,
+            write_jsonl=args.write_jsonl,
+            per_reviewer_reports=args.per_reviewer,
+            progress=lambda msg: print(msg, file=sys.stderr),
+        )
+    except UserFacingError as e:
+        # Expected, explainable failures: no traceback, just what to do next.
+        print(f"\n{e}", file=sys.stderr)
+        return 1
     print(f"\nDone. Open: {result.markdown_path}")
     return 0
 

{overleaf_comments_export-0.2.0 → overleaf_comments_export-0.3.0}/overleaf_comments_export/client.py

@@ -4,6 +4,7 @@ import html
 import json
 import logging
 import re
+import time
 from typing import Any, Optional
 from urllib.parse import unquote, urlparse
 
@@ -15,6 +16,52 @@ OVERLEAF_BASE = "https://www.overleaf.com"
 
 PROJECT_URL_RE = re.compile(r"/project/(?P<id>[0-9a-fA-F]{24})")
 
+RETRY_STATUSES = (429, 500, 502, 503, 504)
+
+
+class UserFacingError(RuntimeError):
+    """An error with a message written for a non-technical user.
+
+    The GUI/CLI print these verbatim without a traceback; anything else is
+    treated as an unexpected bug and shown with full detail.
+    """
+
+
+def _network_hint(exc: Exception) -> str:
+    """Plain-English explanation for a requests connection failure."""
+    text = str(exc)
+    if (
+        "NameResolution" in text
+        or "Failed to resolve" in text
+        or "nodename nor servname" in text
+        or "Name or service not known" in text
+        or "getaddrinfo" in text
+    ):
+        return (
+            "Could not look up www.overleaf.com.\n\n"
+            "This is a network problem on this computer, not a problem with your "
+            "Overleaf project. Check that you are online, then try again. If you "
+            "are on a VPN or a work/university network, try turning the VPN off "
+            "or switching networks."
+        )
+    if isinstance(exc, requests.exceptions.SSLError):
+        return (
+            "The secure connection to Overleaf could not be verified.\n\n"
+            "This usually means a VPN, antivirus, or corporate proxy is "
+            "intercepting traffic. Try again on a different network."
+        )
+    if isinstance(exc, requests.exceptions.Timeout):
+        return (
+            "Overleaf did not respond in time.\n\n"
+            "The connection may be slow or Overleaf may be busy. Wait a moment "
+            "and try again."
+        )
+    return (
+        "Could not reach Overleaf.\n\n"
+        "Check that you are online and that https://www.overleaf.com opens in "
+        "your browser, then try again."
+    )
+
 
 def parse_project_id(project_url: str) -> str:
     parsed = urlparse(project_url)
@@ -36,16 +83,20 @@ class OverleafClient:
         self._api = None
         self._session: Optional[requests.Session] = None
 
-    SUPPORTED_BROWSERS = ("safari", "firefox", "auto", "chrome", "chromium", "edge", "brave")
+    SUPPORTED_BROWSERS = (
+        "safari", "firefox", "auto", "chrome", "chromium", "edge", "brave", "manual",
+    )
     # Browsers that don't trigger macOS Keychain or password prompts:
     PRIVACY_FRIENDLY_BROWSERS = ("safari", "firefox")
 
-    def connect(self, browser: str = "auto") -> None:
-        """Authenticate via the user's browser cookie.
+    def connect(self, browser: str = "auto", cookie_value: str | None = None) -> None:
+        """Authenticate as the user.
 
-        If browser is "auto", we let pyoverleaf auto-detect.
-        Otherwise we read the overleaf.com cookies for the named browser
-        directly via browser-cookie3 and build our own session.
+        `cookie_value` (or browser="manual") uses a session cookie pasted by the
+        user — this works identically on every OS and browser, and is the
+        fallback when a browser's cookie store can't be read (Chrome 127+ on
+        Windows, snap-packaged browsers on Linux, locked-down macOS).
+        Otherwise cookies are read from the named browser, or auto-detected.
         """
         browser = (browser or "auto").lower()
         if browser not in self.SUPPORTED_BROWSERS:
@@ -54,19 +105,58 @@ class OverleafClient:
                 + ", ".join(self.SUPPORTED_BROWSERS)
             )
 
-        if browser == "auto":
+        if cookie_value:
+            session = self._connect_via_cookie_value(cookie_value)
+        elif browser == "manual":
+            raise UserFacingError(
+                "No session cookie was provided.\n\n"
+                "Paste the value of your Overleaf 'overleaf_session2' cookie, or "
+                "choose a browser to read it from automatically."
+            )
+        elif browser == "auto":
             session = self._connect_via_pyoverleaf()
         else:
             session = self._connect_via_browser_cookie3(browser)
 
-        session.headers.setdefault(
-            "User-Agent",
-            "overleaf-comments-export/0.1 (Mozilla/5.0 compatible)",
+        # Assign, don't setdefault: requests.Session pre-fills User-Agent with
+        # "python-requests/x.y", which setdefault would leave in place.
+        session.headers["User-Agent"] = (
+            f"overleaf-comments-export/{_tool_version()} (Mozilla/5.0 compatible)"
         )
         session.headers.setdefault("Accept", "application/json, text/plain, */*")
         session.headers.setdefault("Referer", f"{self.base_url}/")
         self._session = session
 
+    def _connect_via_cookie_value(self, pasted: str) -> requests.Session:
+        """Build a session from a cookie the user pasted.
+
+        Accepts a bare value, `overleaf_session2=<value>`, or a whole
+        `document.cookie` dump — whatever the user actually managed to copy.
+        """
+        pairs = _parse_cookie_string(pasted)
+        if not pairs:
+            raise UserFacingError(
+                "That does not look like an Overleaf session cookie.\n\n"
+                "In your browser open Overleaf, press F12, go to "
+                "Application → Cookies → https://www.overleaf.com, and copy the "
+                "Value of the row named 'overleaf_session2'."
+            )
+        if not any(k in ("overleaf_session2", "overleaf.sid") for k in pairs):
+            raise UserFacingError(
+                "The pasted cookie does not contain 'overleaf_session2'.\n\n"
+                "Copy the Value of the cookie named exactly 'overleaf_session2' "
+                "(Application → Cookies → https://www.overleaf.com)."
+            )
+
+        session = requests.Session()
+        domain = urlparse(self.base_url).hostname or "www.overleaf.com"
+        # Set on the registrable domain so it is sent to www. and api. hosts.
+        cookie_domain = ".overleaf.com" if domain.endswith("overleaf.com") else domain
+        for name, value in pairs.items():
+            session.cookies.set(name, value, domain=cookie_domain, path="/")
+        self._api = None  # no pyoverleaf; file tree comes from the HTML scrape
+        return session
+
     def _connect_via_pyoverleaf(self) -> requests.Session:
         try:
             import pyoverleaf  # type: ignore
@@ -169,23 +259,64 @@ class OverleafClient:
             raise RuntimeError("call connect() before using the client")
         return self._session
 
+    def _request(self, url: str, *, attempts: int = 3, **kwargs: Any) -> requests.Response:
+        """GET with retry on transient failures, and plain-English errors.
+
+        Retries connection errors, timeouts, and 429/5xx (honouring Retry-After).
+        Never retries 4xx other than 429 — those won't fix themselves.
+        """
+        last_exc: Exception | None = None
+        for attempt in range(attempts):
+            try:
+                r = self.session.get(url, timeout=30, **kwargs)
+            except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
+                last_exc = e
+                if attempt == attempts - 1:
+                    raise UserFacingError(_network_hint(e)) from e
+                time.sleep(2**attempt)
+                continue
+            if r.status_code in RETRY_STATUSES and attempt < attempts - 1:
+                wait = r.headers.get("Retry-After")
+                try:
+                    delay = min(float(wait), 30.0) if wait else 2**attempt
+                except ValueError:
+                    delay = 2**attempt
+                logger.warning(
+                    "%s returned %s — retrying in %.0fs", url, r.status_code, delay
+                )
+                time.sleep(delay)
+                continue
+            return r
+        raise UserFacingError(_network_hint(last_exc or Exception()))  # pragma: no cover
+
     def _get(self, path: str, expect_json: bool = True) -> Any:
         url = f"{self.base_url}{path}"
-        r = self.session.get(url, timeout=30)
+        r = self._request(url)
         if r.status_code in (401, 403):
-            raise RuntimeError(
-                f"Overleaf returned {r.status_code} for {path}. Your session may have "
-                "expired or you may not have access to this project. Refresh the "
-                "Overleaf tab in your browser and re-run."
+            raise UserFacingError(
+                "Overleaf refused the request (not signed in).\n\n"
+                "Your saved session has expired. Open https://www.overleaf.com in "
+                "your browser, make sure you are signed in and can see this "
+                "project, then run the export again."
+            )
+        if r.status_code == 404:
+            raise UserFacingError(
+                "Overleaf could not find that project.\n\n"
+                "Check the project link is correct and that this account has "
+                "access to it. Open the project in your browser and copy the "
+                "address from the address bar."
             )
         r.raise_for_status()
         if not expect_json:
             return r.text
         ctype = r.headers.get("Content-Type", "")
         if "application/json" not in ctype:
-            raise RuntimeError(
-                f"Expected JSON from {path} but got Content-Type={ctype!r}. "
-                "This usually means the endpoint moved or you got redirected to login."
+            raise UserFacingError(
+                "Overleaf returned a web page instead of data.\n\n"
+                "This usually means you were signed out. Open Overleaf in your "
+                "browser, sign in, and try again. If you are already signed in, "
+                "Overleaf may have changed its internal API — please report this "
+                "at https://github.com/Mangluu/overleaf-comments-export/issues"
             )
         return r.json()
 
@@ -213,6 +344,8 @@ class OverleafClient:
         Returns None if the endpoint isn't accessible (e.g. 404 on older deployments)."""
         try:
             return self._get(f"/project/{project_id}/ranges")
+        except UserFacingError:
+            raise  # auth/network problems are fatal, not "no ranges"
         except requests.HTTPError as e:
             if e.response is not None and e.response.status_code == 404:
                 logger.warning(
@@ -285,7 +418,7 @@ class OverleafClient:
         """
         path = f"/project/{project_id}"
         url = f"{self.base_url}{path}"
-        r = self.session.get(url, timeout=30, allow_redirects=False)
+        r = self._request(url, allow_redirects=False)
         if r.status_code in (301, 302, 303, 307, 308):
             loc = r.headers.get("Location", "")
             if "login" in loc.lower():
@@ -415,6 +548,33 @@ class OverleafClient:
         return out
 
 
+def _tool_version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+def _parse_cookie_string(pasted: str) -> dict[str, str]:
+    """Parse whatever the user pasted into {cookie_name: value}.
+
+    Handles a bare cookie value, `name=value`, and a full `document.cookie`
+    dump. Falls back to treating the whole string as the session value.
+    """
+    s = (pasted or "").strip().strip('"').strip("'")
+    if not s:
+        return {}
+    out: dict[str, str] = {}
+    for part in s.split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        name, _, value = part.partition("=")
+        name, value = name.strip(), value.strip().strip('"')
+        if name and value:
+            out[name] = value
+    return out or {"overleaf_session2": s}
+
+
 def _decode_meta_content(raw: str) -> Any:
     """Best-effort decode of a <meta content="..."> value.
 

{overleaf_comments_export-0.2.0 → overleaf_comments_export-0.3.0}/overleaf_comments_export/export.py

@@ -8,8 +8,9 @@ from datetime import date, datetime, timezone
 from pathlib import Path
 from typing import Any, Callable
 
+from . import __version__
 from .anchors import build_line_starts, resolve_anchor
-from .client import OverleafClient, parse_project_id
+from .client import OverleafClient, UserFacingError, parse_project_id
 from .model import (
     AnchoredComment,
     DocText,
@@ -216,6 +217,24 @@ def _extract_context(
     )
 
 
+def _deletion_context(doc: DocText, offset: int, deleted: str, line_no: int) -> SourceContext:
+    """Context for a tracked deletion.
+
+    The deleted text is no longer in the document, so it can't be located by
+    offset — it *is* the anchor, sitting between the surrounding live text.
+    """
+    text = doc.text
+    offset = max(0, min(offset, len(text)))
+    return SourceContext(
+        before=_normalize_ws(text[max(0, offset - CONTEXT_CHARS_BEFORE) : offset]),
+        anchor=_normalize_ws(deleted),
+        after=_normalize_ws(text[offset : offset + CONTEXT_CHARS_AFTER]),
+        truncated_before=offset > CONTEXT_CHARS_BEFORE,
+        truncated_after=offset + CONTEXT_CHARS_AFTER < len(text),
+        line_no=line_no,
+    )
+
+
 def _thread_matches_reviewer(thread: Thread | None, reviewer_filter: list[str]) -> bool:
     """True if the thread has at least one message from any reviewer in the
     filter list. `reviewer_filter` is a list of case-insensitive substrings
@@ -261,7 +280,9 @@ def _slug_reviewer(name: str) -> str:
 
 
 def _comment_to_jsonl_record(
-    c: AnchoredComment, thread: Thread | None
+    c: AnchoredComment,
+    thread: Thread | None,
+    user_map: dict[str, dict[str, str]] | None = None,
 ) -> dict[str, Any]:
     """Self-contained JSONL record per comment (with embedded thread, since
     JSONL records are read independently)."""
@@ -275,8 +296,9 @@ def _comment_to_jsonl_record(
         "nearest_heading": c.nearest_heading,
         "anchored_text": c.anchored_text,
         "stale": c.stale,
+        "reply_count": max(0, len(thread.messages) - 1) if thread else 0,
         "context": _serialize_context(c.context),
-        "thread": _serialize_thread(thread) if thread is not None else None,
+        "thread": _serialize_thread(thread, user_map) if thread is not None else None,
     }
 
 
@@ -308,6 +330,7 @@ def run_export(
     project_title: str | None = None,
     base_url: str = "https://www.overleaf.com",
     browser: str = "auto",
+    cookie_value: str | None = None,
     verbose: bool = False,
     include_raw: bool = False,
     include_open: bool = True,
@@ -342,8 +365,11 @@ def run_export(
     logger.info("Project id: %s", project_id)
 
     client = OverleafClient(base_url=base_url)
-    progress(f"Authenticating via {browser} browser cookie…")
-    client.connect(browser=browser)
+    if cookie_value:
+        progress("Authenticating with the pasted session cookie…")
+    else:
+        progress(f"Authenticating via {browser} browser cookie…")
+    client.connect(browser=browser, cookie_value=cookie_value)
 
     progress("Fetching threads…")
     threads_raw = client.get_threads(project_id)
@@ -444,9 +470,10 @@ def run_export(
                 heading = nearest_heading(doc.headings, line)
                 uid = str(meta.get("user_id") or "") or None
                 user = user_map.get(uid or "", {}) if uid else {}
-                context = _extract_context(
-                    doc, ro, content if kind == "insertion" else "", line
-                )
+                if kind == "insertion":
+                    context = _extract_context(doc, ro, content, line)
+                else:
+                    context = _deletion_context(doc, ro, content, line)
                 changes.append(
                     TrackedChange(
                         id=str(ch.get("id") or ch.get("_id") or ""),
@@ -574,6 +601,7 @@ def run_export(
         threads_raw=threads_raw,
         ranges_payload=ranges_payload,
         include_raw=include_raw,
+        user_map=user_map,
     )
     json_payload["filters_applied"] = {
         "include_open": include_open,
@@ -591,7 +619,7 @@ def run_export(
         jsonl_path = out_dir / "comments.jsonl"
         with jsonl_path.open("w", encoding="utf-8") as f:
             for c in anchored:
-                rec = _comment_to_jsonl_record(c, threads.get(c.thread_id))
+                rec = _comment_to_jsonl_record(c, threads.get(c.thread_id), user_map)
                 f.write(json.dumps(rec, default=str))
                 f.write("\n")
         progress(f"Wrote {jsonl_path.name} ({len(anchored)} record(s))")
@@ -682,15 +710,31 @@ def _serialize_context(ctx: SourceContext | None) -> dict[str, Any] | None:
     }
 
 
-def _serialize_thread(thread: Thread) -> dict[str, Any]:
+def _serialize_thread(
+    thread: Thread, user_map: dict[str, dict[str, str]] | None = None
+) -> dict[str, Any]:
+    """Serialize a thread, tagging the first message as the comment itself and
+    the rest as replies (Overleaf threads are flat, ordered by time)."""
+    ordered = sorted(thread.messages, key=lambda x: x.timestamp_ms)
+    resolver = user_map or {}
+    resolved_by = resolver.get(thread.resolved_by_user_id or "", {})
     return {
         "id": thread.id,
         "resolved": thread.resolved,
         "resolved_at": _iso(thread.resolved_at_ms),
-        "resolved_by_user_id": thread.resolved_by_user_id,
+        "resolved_by": {
+            "id": thread.resolved_by_user_id,
+            "name": resolved_by.get("name"),
+            "email": resolved_by.get("email"),
+        }
+        if thread.resolved_by_user_id
+        else None,
+        "reply_count": max(0, len(ordered) - 1),
         "messages": [
             {
                 "id": m.id,
+                "role": "comment" if i == 0 else "reply",
+                "reply_index": None if i == 0 else i - 1,
                 "user": {
                     "id": m.user_id,
                     "name": m.user_name,
@@ -700,7 +744,7 @@ def _serialize_thread(thread: Thread) -> dict[str, Any]:
                 "timestamp": _iso(m.timestamp_ms),
                 "edited_at": _iso(m.edited_at_ms),
             }
-            for m in sorted(thread.messages, key=lambda x: x.timestamp_ms)
+            for i, m in enumerate(ordered)
         ],
     }
 
@@ -720,6 +764,7 @@ def _build_structured_json(
     threads_raw: dict[str, Any],
     ranges_payload: Any,
     include_raw: bool = False,
+    user_map: dict[str, dict[str, str]] | None = None,
 ) -> dict[str, Any]:
     """Produce a clean, AI-ingestion-friendly JSON document.
 
@@ -750,6 +795,7 @@ def _build_structured_json(
 
     payload: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
+        "tool_version": __version__,
         "project": {
             "id": project_id,
             "title": project_title,
@@ -774,7 +820,9 @@ def _build_structured_json(
         # Threads are stored ONCE at the top level keyed by thread_id;
         # comments reference them via `thread_id`. This avoids duplicating
         # potentially long discussions inside every comment.
-        "threads": {tid: _serialize_thread(t) for tid, t in threads.items()},
+        "threads": {
+            tid: _serialize_thread(t, user_map) for tid, t in threads.items()
+        },
         "files": files,
         "comments": [
             {
@@ -788,6 +836,9 @@ def _build_structured_json(
                 "nearest_heading": c.nearest_heading,
                 "anchored_text": c.anchored_text,
                 "stale": c.stale,
+                "reply_count": max(
+                    0, len(threads[c.thread_id].messages) - 1
+                ) if c.thread_id in threads else 0,
                 "context": _serialize_context(c.context),
             }
             for c in anchored
@@ -872,6 +923,11 @@ rendered output where truncation is true.
 ## How to address comments
 
 - Refer to comments by `short_id` (e.g., "C014"), not by `thread_id`.
+- Each thread's FIRST message (`role: "comment"`) is the reviewer's actual
+  ask. Later messages (`role: "reply"`, shown indented with `↳` in the
+  Markdown) are follow-up discussion, often between co-authors. Answer the
+  ask, taking the discussion into account; do not re-litigate sub-points the
+  replies already settled.
 - For each open comment, propose an edit to the .tex source. If the comment
   is a question, answer it; if it's a request, attempt the change.
 - Stale comments (`stale: true`) may not point to the current location in the