Embed comments in document record (ATProto)

Comments are now stored as an array inside the com.diffdown.document
ATProto record on the owner's PDS, making documents fully self-contained
and portable.

Changes:
- Add EmbeddedComment type and Comments field to Document model
- Remove old com.diffdown.comment per-record approach
- CommentCreate/CommentList do read-modify-write on owner's document
- Comment sidebar shown for owners and collaborators
- Paragraph click in rich editor shows a comment button
- ownerDID threaded through comment API calls for collaborator access
- Clicking a comment scrolls to and highlights the target paragraph
(Web Animations API, yellow outline pulse)

Co-Authored-By: Claude Sonnet 4.6 <[e-mail]>

docs/plans/2026-03-18-embedded-comments.md

···
+# Embedded Comments Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the broken per-commenter ATProto record approach with comments embedded directly in the `com.diffdown.document` record on the owner's PDS. Comments become a portable part of the document.
+
+**Architecture:** `Document.Comments []EmbeddedComment` is stored inside the ATProto record. `CommentCreate` does read-modify-write on the owner's document via the owner's XRPC client (same pattern as `AutoSave`). `CommentList` reads the document and returns the embedded array. The collaborator passes `ownerDID` in the request so the handler knows whose PDS to talk to.
+
+**Tech Stack:** Go 1.22, ATProto XRPC, html/template, ProseMirror (Milkdown) click events
+
+---
+
+### Task 1: Update the Document model
+
+**Files:**
+- Modify: `internal/model/models.go`
+
+**Step 1: Add `EmbeddedComment` struct and `Comments` field to `Document`**
+
+Add after the `MarkdownText` struct:
+
+```go
+type EmbeddedComment struct {
+    ID           string `json:"id"`           // random 8-char hex for dedup
+    ParagraphID  string `json:"paragraphId"`  // "p-0", "p-1", ... or "general"
+    Text         string `json:"text"`
+    Author       string `json:"author"`       // DID
+    AuthorHandle string `json:"authorHandle"` // resolved handle, may be empty
+    CreatedAt    string `json:"createdAt"`    // RFC3339
+}
+```
+
+Add `Comments []EmbeddedComment` to the `Document` struct, after `Collaborators`:
+
+```go
+Comments []EmbeddedComment `json:"comments,omitempty"`
+```
+
+Keep the existing `Comment` struct for now — it will be removed in Task 2.
+
+**Step 2: Build**
+
+```bash
+go build ./...
+```
+
+Expected: PASS.
+
+**Step 3: Commit**
+
+```bash
+git add internal/model/models.go
+git commit -m "Add EmbeddedComment type and Comments field to Document"
+```
+
+---
+
+### Task 2: Remove old XRPC comment methods and stale types
+
+**Files:**
+- Modify: `internal/atproto/xrpc/client.go`
+- Modify: `internal/model/models.go`
+- Modify: `internal/handler/handler.go`
+
+**Step 1: Delete from `internal/atproto/xrpc/client.go`**
+
+Remove the `collectionComment` const (line 317) and the `CreateComment` and `ListComments` functions (lines 319-357).
+
+Check whether `strings` import is still needed elsewhere before removing it:
+
+```bash
+grep -n 'strings\.' internal/atproto/xrpc/client.go
+```
+
+Remove unused import if needed.
+
+**Step 2: Delete `collectionComment` const from `internal/handler/handler.go`**
+
+Line 27: `const collectionComment = "com.diffdown.comment"` — delete it.
+
+**Step 3: Remove the old `Comment` struct from `internal/model/models.go`**
+
+Delete the `Comment` struct block.
+
+**Step 4: Build — expect errors**
+
+```bash
+go build ./...
+```
+
+Expected: compile errors about `CommentCreate` and `ListComments` called in handler. These are fixed in Task 3 — do not commit yet.
+
+---
+
+### Task 3: Rewrite `CommentCreate` and `CommentList` handlers
+
+**Files:**
+- Modify: `internal/handler/handler.go`
+
+**Step 1: Add `crypto/rand` and `encoding/hex` imports**
+
+In the `import` block, add both if not already present.
+
+**Step 2: Add `randomID` helper near the top of handler.go (after imports)**
+
+```go
+func randomID() string {
+    b := make([]byte, 4)
+    rand.Read(b)
+    return hex.EncodeToString(b)
+}
+```
+
+**Step 3: Rewrite `CommentCreate`**
+
+Replace the entire function with:
+
+```go
+func (h *Handler) CommentCreate(w http.ResponseWriter, r *http.Request) {
+    user, _ := h.currentUser(r)
+    if user == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+
+    rKey := r.PathValue("rkey")
+    if rKey == "" {
+        http.Error(w, "Invalid document", http.StatusBadRequest)
+        return
+    }
+
+    var req struct {
+        OwnerDID    string `json:"ownerDID"`
+        ParagraphID string `json:"paragraphId"`
+        Text        string `json:"text"`
+    }
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        http.Error(w, "Invalid request", http.StatusBadRequest)
+        return
+    }
+    if req.Text == "" {
+        http.Error(w, "Comment text required", http.StatusBadRequest)
+        return
+    }
+
+    session, err := h.DB.GetATProtoSession(user.ID)
+    if err != nil || session == nil {
+        http.Error(w, "Not authenticated with ATProto", http.StatusUnauthorized)
+        return
+    }
+
+    ownerUserID := user.ID
+    ownerDID := session.DID
+    if req.OwnerDID != "" && req.OwnerDID != session.DID {
+        ownerUser, err := h.DB.GetUserByDID(req.OwnerDID)
+        if err != nil {
+            http.Error(w, "Owner not found", http.StatusBadRequest)
+            return
+        }
+        ownerUserID = ownerUser.ID
+        ownerDID = req.OwnerDID
+    }
+
+    ownerClient, err := h.xrpcClient(ownerUserID)
+    if err != nil {
+        http.Error(w, "Failed to connect to owner PDS", http.StatusInternalServerError)
+        return
+    }
+
+    value, _, err := ownerClient.GetRecord(ownerDID, collectionDocument, rKey)
+    if err != nil {
+        log.Printf("CommentCreate: GetRecord: %v", err)
+        http.Error(w, "Document not found", http.StatusNotFound)
+        return
+    }
+    var doc model.Document
+    if err := json.Unmarshal(value, &doc); err != nil {
+        http.Error(w, "Failed to parse document", http.StatusInternalServerError)
+        return
+    }
+
+    authorHandle, _ := atproto.ResolveHandleFromDID(session.DID)
+
+    paragraphID := req.ParagraphID
+    if paragraphID == "" {
+        paragraphID = "general"
+    }
+
+    comment := model.EmbeddedComment{
+        ID:           randomID(),
+        ParagraphID:  paragraphID,
+        Text:         req.Text,
+        Author:       session.DID,
+        AuthorHandle: authorHandle,
+        CreatedAt:    time.Now().UTC().Format(time.RFC3339),
+    }
+    doc.Comments = append(doc.Comments, comment)
+
+    if _, _, err := ownerClient.PutDocument(rKey, &doc); err != nil {
+        log.Printf("CommentCreate: PutDocument: %v", err)
+        http.Error(w, "Failed to save comment", http.StatusInternalServerError)
+        return
+    }
+
+    h.jsonResponse(w, comment, http.StatusCreated)
+}
+```
+
+**Step 4: Rewrite `CommentList`**
+
+Replace the entire function with:
+
+```go
+func (h *Handler) CommentList(w http.ResponseWriter, r *http.Request) {
+    rKey := r.PathValue("rkey")
+    if rKey == "" {
+        http.Error(w, "Invalid document", http.StatusBadRequest)
+        return
+    }
+
+    user, _ := h.currentUser(r)
+    if user == nil {
+        http.Error(w, "Unauthorized", http.StatusUnauthorized)
+        return
+    }
+
+    session, err := h.DB.GetATProtoSession(user.ID)
+    if err != nil || session == nil {
+        http.Error(w, "Not authenticated with ATProto", http.StatusUnauthorized)
+        return
+    }
+
+    ownerUserID := user.ID
+    ownerDID := session.DID
+    if qOwner := r.URL.Query().Get("ownerDID"); qOwner != "" && qOwner != session.DID {
+        ownerUser, err := h.DB.GetUserByDID(qOwner)
+        if err != nil {
+            http.Error(w, "Owner not found", http.StatusBadRequest)
+            return
+        }
+        ownerUserID = ownerUser.ID
+        ownerDID = qOwner
+    }
+
+    ownerClient, err := h.xrpcClient(ownerUserID)
+    if err != nil {
+        http.Error(w, "Failed to connect to owner PDS", http.StatusInternalServerError)
+        return
+    }
+
+    value, _, err := ownerClient.GetRecord(ownerDID, collectionDocument, rKey)
+    if err != nil {
+        log.Printf("CommentList: GetRecord: %v", err)
+        http.Error(w, "Document not found", http.StatusNotFound)
+        return
+    }
+    var doc model.Document
+    if err := json.Unmarshal(value, &doc); err != nil {
+        http.Error(w, "Failed to parse document", http.StatusInternalServerError)
+        return
+    }
+
+    comments := doc.Comments
+    if comments == nil {
+        comments = []model.EmbeddedComment{}
+    }
+    h.jsonResponse(w, comments, http.StatusOK)
+}
+```
+
+**Step 5: Build**
+
+```bash
+go build ./...
+```
+
+Expected: PASS.
+
+**Step 6: Run tests**
+
+```bash
+go test ./...
+```
+
+Expected: all pass.
+
+**Step 7: Commit**
+
+```bash
+git add internal/handler/handler.go internal/model/models.go internal/atproto/xrpc/client.go
+git commit -m "Embed comments in document record; rewrite CommentCreate/CommentList"
+```
+
+---
+
+### Task 4: Fix comment sidebar visibility (show for owners too)
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+**Step 1: Change the sidebar guard from `IsCollaborator` to `or .IsCollaborator .IsOwner`**
+
+Find line ~85:
+```
+{{if .IsCollaborator}}
+```
+above the `comment-sidebar` div. Change to:
+```
+{{if or .IsCollaborator .IsOwner}}
+```
+
+**Step 2: Build**
+
+```bash
+go build ./...
+```
+
+**Step 3: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "Show comment sidebar for document owners, not just collaborators"
+```
+
+---
+
+### Task 5: Wire up paragraph click + update API calls
+
+**Files:**
+- Modify: `templates/document_edit.html`
+- Modify: `static/css/editor.css`
+
+**Step 1: Update `submitComment` to include `ownerDID` in POST body**
+
+The template already has `const ownerDID = '{{.Content.OwnerDID}}'`.
+
+In `submitComment` (around line 791), the fetch body currently sends:
+```js
+{ paragraphId: activeCommentParagraphId, text }
+```
+
+Change it to build an object, add `ownerDID` if non-empty, then send:
+```js
+const body = { paragraphId: activeCommentParagraphId, text };
+if (ownerDID) body.ownerDID = ownerDID;
+// then JSON.stringify(body)
+```
+
+**Step 2: Update `loadComments` to pass `ownerDID` query param**
+
+The fetch URL is currently `/api/docs/${rkey}/comments`. Change to append `?ownerDID=...` when `ownerDID` is set:
+```js
+const qs = ownerDID ? '?ownerDID=' + encodeURIComponent(ownerDID) : '';
+// then fetch(`/api/docs/${rkey}/comments${qs}`)
+```
+
+**Step 3: Add paragraph click detection after `loadComments` function**
+
+After the `loadComments` function, add a new function `setupParagraphCommentTrigger` that:
+1. Finds `#editor-rich` (the Milkdown container)
+2. Listens for `click` events
+3. Calls `e.target.closest('.ProseMirror')` to confirm click is inside the editor
+4. Calls `e.target.closest('p, h1, h2, h3, h4, h5, h6, li')` to find the paragraph
+5. Computes index: `Array.from(paraEl.parentElement.children).indexOf(paraEl)` — yields 0-based index
+6. Sets `activeCommentParagraphId = 'p-' + idx`
+7. Positions and shows `commentBtn` to the right of the paragraph using `getBoundingClientRect()` + `window.scrollY`
+
+Call `setupParagraphCommentTrigger()` immediately after defining it.
+
+**Step 4: Add/verify `.comment-btn` CSS in `static/css/editor.css`**
+
+Check whether `.comment-btn` has `position: fixed` or `position: absolute` and `z-index`. If not present, add:
+
+```css
+.comment-btn {
+    position: fixed;
+    z-index: 100;
+}
+```
+
+**Step 5: Build**
+
+```bash
+go build ./...
+```
+
+**Step 6: Commit**
+
+```bash
+git add templates/document_edit.html static/css/editor.css
+git commit -m "Wire paragraph click to comment button; pass ownerDID in comment API calls"
+```
+
+---
+
+### Task 6: Improve comment sidebar rendering
+
+**Files:**
+- Modify: `templates/document_edit.html`
+
+**Step 1: Update `renderCommentThreads` paragraph label**
+
+In the `renderCommentThreads` function, the thread label is currently:
+```
+¶ ${paragraphId}
+```
+
+Change to compute a human-readable label before building the thread HTML:
+```js
+const label = pid === 'general'
+    ? 'General'
+    : 'Paragraph ' + (parseInt(pid.replace('p-', ''), 10) + 1);
+```
+
+Then use `label` in the label div text content (via `escHtml(label)`).
+
+**Step 2: Update author display to prefer `authorHandle`**
+
+The comment item shows `c.authorName || c.author`. Since the new struct uses `authorHandle`, update to `c.authorHandle || c.author`.
+
+**Step 3: Build and run all tests**
+
+```bash
+go build ./... && go test ./...
+```
+
+Expected: PASS — 3 test packages, all green.
+
+**Step 4: Commit**
+
+```bash
+git add templates/document_edit.html
+git commit -m "Improve comment rendering: human-readable paragraph labels, authorHandle"
+```
+
+---
+
+### Task 7: Manual smoke test
+
+**Start the server from the worktree:**
+
+```bash
+go run ./cmd/server
+```
+
+1. **Owner:** Sign in, open a document. Click a paragraph body — the blue "Comment" button should appear to the right. Click it, write a comment, post. The sidebar appears with the comment under "Paragraph N".
+
+2. **Collaborator:** Sign in as the collaborator, navigate to the shared doc via `/docs/{ownerDID}/{rkey}`. Click a paragraph, post a comment. The comment appears in the sidebar with your handle.
+
+3. **Owner sees collaborator's comment:** Sign back in as owner on the same document — comment is visible in the sidebar.
+
+---
+
+## Notes
+
+- **No DB migration needed** — comments live entirely in the ATProto record.
+- **Concurrent comment race:** `CommentCreate` reads then writes; two concurrent comments could overwrite each other (last write wins). Acceptable trade-off; CID-based optimistic locking is a future improvement.
+- **Positional paragraph IDs:** `p-0`, `p-1` are index-based. Document edits may shift which content a comment refers to. Stable UUIDs embedded in ProseMirror schema would require a bigger refactor.
+- **Old `com.diffdown.comment` records:** Orphaned on user PDSes. Cleanup is out of scope.

internal/atproto/xrpc/client.go

···
 	return c.PutRecord(collectionDocument, rkey, doc)
 }
 
-const collectionComment = "com.diffdown.comment"
-
-// CreateComment creates a new comment record.
-func (c *Client) CreateComment(comment *model.Comment) (string, error) {
-	record := map[string]interface{}{
-		"$type":       "com.diffdown.comment",
-		"documentURI": comment.DocumentURI,
-		"paragraphId": comment.ParagraphID,
-		"text":        comment.Text,
-		"author":      comment.Author,
-	}
-	uri, _, err := c.CreateRecord(collectionComment, record)
-	if err != nil {
-		return "", err
-	}
-	return uri, nil
-}
-
-// ListComments fetches all comments for a document.
-func (c *Client) ListComments(documentRKey string) ([]model.Comment, error) {
-	records, _, err := c.ListRecords(c.session.DID, collectionComment, 100, "")
-	if err != nil {
-		return nil, err
-	}
-
-	var comments []model.Comment
-	for _, r := range records {
-		var comment model.Comment
-		if err := json.Unmarshal(r.Value, &comment); err != nil {
-			continue
-		}
-		// Filter by documentRKey: at://{did}/com.diffdown.document/{rkey}
-		expectedSuffix := "/com.diffdown.document/" + documentRKey
-		if documentRKey != "" && !strings.HasSuffix(comment.DocumentURI, expectedSuffix) {
-			continue
-		}
-		comment.URI = r.URI
-		comments = append(comments, comment)
-	}
-	return comments, nil
-}

internal/handler/handler.go

···
 package handler
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"html/template"
···
 )
 
 const collectionDocument = "com.diffdown.document"
-const collectionComment = "com.diffdown.comment"
+
+func randomID() string {
+	b := make([]byte, 4)
+	rand.Read(b)
+	return hex.EncodeToString(b)
+}
 
 type Handler struct {
 	DB               *db.DB
···
 	}
 
 	var req struct {
+		OwnerDID    string `json:"ownerDID"`
 		ParagraphID string `json:"paragraphId"`
 		Text        string `json:"text"`
 	}
···
 		http.Error(w, "Invalid request", http.StatusBadRequest)
 		return
 	}
-
 	if req.Text == "" {
 		http.Error(w, "Comment text required", http.StatusBadRequest)
 		return
···
 		return
 	}
 
-	client, err := h.xrpcClient(user.ID)
+	ownerUserID := user.ID
+	ownerDID := session.DID
+	if req.OwnerDID != "" && req.OwnerDID != session.DID {
+		ownerUser, err := h.DB.GetUserByDID(req.OwnerDID)
+		if err != nil {
+			http.Error(w, "Owner not found", http.StatusBadRequest)
+			return
+		}
+		ownerUserID = ownerUser.ID
+		ownerDID = req.OwnerDID
+	}
+
+	ownerClient, err := h.xrpcClient(ownerUserID)
+	if err != nil {
+		http.Error(w, "Failed to connect to owner PDS", http.StatusInternalServerError)
+		return
+	}
+
+	value, _, err := ownerClient.GetRecord(ownerDID, collectionDocument, rKey)
 	if err != nil {
-		http.Error(w, "Failed to connect to ATProto", http.StatusInternalServerError)
+		log.Printf("CommentCreate: GetRecord: %v", err)
+		http.Error(w, "Document not found", http.StatusNotFound)
+		return
+	}
+	var doc model.Document
+	if err := json.Unmarshal(value, &doc); err != nil {
+		http.Error(w, "Failed to parse document", http.StatusInternalServerError)
 		return
 	}
 
-	comment := &model.Comment{
-		DocumentURI: fmt.Sprintf("at://%s/com.diffdown.document/%s", session.DID, rKey),
-		ParagraphID: req.ParagraphID,
-		Text:        req.Text,
-		Author:      session.DID,
+	authorHandle, _ := atproto.ResolveHandleFromDID(session.DID)
+
+	paragraphID := req.ParagraphID
+	if paragraphID == "" {
+		paragraphID = "general"
 	}
 
-	uri, err := client.CreateComment(comment)
-	if err != nil {
-		log.Printf("CommentCreate: %v", err)
-		http.Error(w, "Failed to create comment", http.StatusInternalServerError)
+	comment := model.EmbeddedComment{
+		ID:           randomID(),
+		ParagraphID:  paragraphID,
+		Text:         req.Text,
+		Author:       session.DID,
+		AuthorHandle: authorHandle,
+		CreatedAt:    time.Now().UTC().Format(time.RFC3339),
+	}
+	doc.Comments = append(doc.Comments, comment)
+
+	if _, _, err := ownerClient.PutDocument(rKey, &doc); err != nil {
+		log.Printf("CommentCreate: PutDocument: %v", err)
+		http.Error(w, "Failed to save comment", http.StatusInternalServerError)
 		return
 	}
 
-	h.jsonResponse(w, map[string]string{"uri": uri}, http.StatusCreated)
+	h.jsonResponse(w, comment, http.StatusCreated)
 }
 
 func (h *Handler) CommentList(w http.ResponseWriter, r *http.Request) {
···
 		return
 	}
 
-	client, err := h.xrpcClient(user.ID)
+	ownerUserID := user.ID
+	ownerDID := session.DID
+	if qOwner := r.URL.Query().Get("ownerDID"); qOwner != "" && qOwner != session.DID {
+		ownerUser, err := h.DB.GetUserByDID(qOwner)
+		if err != nil {
+			http.Error(w, "Owner not found", http.StatusBadRequest)
+			return
+		}
+		ownerUserID = ownerUser.ID
+		ownerDID = qOwner
+	}
+
+	ownerClient, err := h.xrpcClient(ownerUserID)
 	if err != nil {
-		http.Error(w, "Failed to connect to ATProto", http.StatusInternalServerError)
+		http.Error(w, "Failed to connect to owner PDS", http.StatusInternalServerError)
 		return
 	}
 
-	comments, err := client.ListComments(rKey)
+	value, _, err := ownerClient.GetRecord(ownerDID, collectionDocument, rKey)
 	if err != nil {
-		log.Printf("CommentList: %v", err)
-		http.Error(w, "Failed to list comments", http.StatusInternalServerError)
+		log.Printf("CommentList: GetRecord: %v", err)
+		http.Error(w, "Document not found", http.StatusNotFound)
+		return
+	}
+	var doc model.Document
+	if err := json.Unmarshal(value, &doc); err != nil {
+		http.Error(w, "Failed to parse document", http.StatusInternalServerError)
 		return
 	}
 
+	comments := doc.Comments
+	if comments == nil {
+		comments = []model.EmbeddedComment{}
+	}
 	h.jsonResponse(w, comments, http.StatusOK)
 }
 

internal/model/models.go

···
 	Title         string           `json:"title"`
 	Content       *MarkdownContent `json:"content,omitempty"`
 	TextContent   string           `json:"textContent,omitempty"`
-	Collaborators []string         `json:"collaborators,omitempty"`
-	CreatedAt     string           `json:"createdAt"`
+	Collaborators []string          `json:"collaborators,omitempty"`
+	Comments      []EmbeddedComment `json:"comments,omitempty"`
+	CreatedAt     string            `json:"createdAt"`
 	UpdatedAt     string           `json:"updatedAt,omitempty"`
 }
 
···
 	RawMarkdown string `json:"rawMarkdown"`
 }
 
+type EmbeddedComment struct {
+	ID           string `json:"id"`           // random 8-char hex for dedup
+	ParagraphID  string `json:"paragraphId"`  // "p-0", "p-1", ... or "general"
+	Text         string `json:"text"`
+	Author       string `json:"author"`       // DID
+	AuthorHandle string `json:"authorHandle"` // resolved handle, may be empty
+	CreatedAt    string `json:"createdAt"`    // RFC3339
+}
+
 type Invite struct {
 	ID           string    `json:"id"`
 	DocumentRKey string    `json:"document_rkey"`
···
 	CreatedBy    string    `json:"created_by"`
 	CreatedAt    time.Time `json:"created_at"`
 	ExpiresAt    time.Time `json:"expires_at"`
-}
-
-type Comment struct {
-	URI         string    `json:"uri"`
-	DocumentURI string    `json:"documentURI"`
-	ParagraphID string    `json:"paragraphId"`
-	Text        string    `json:"text"`
-	Author      string    `json:"author"`
-	AuthorName  string    `json:"authorName"`
-	CreatedAt   time.Time `json:"createdAt"`
 }
 
 // RKeyFromURI extracts the rkey (last path segment) from an at:// URI.

static/css/editor.css

···
     border: 1px solid var(--border);
     border-radius: var(--radius);
     overflow: hidden;
+    cursor: pointer;
 }
+
+.comment-thread:hover {
+    border-color: var(--primary);
+}
+
 
 .comment-thread-label {
     font-size: 0.75rem;

templates/document_edit.html

···
 {{end}}
 
 <!-- Comment sidebar -->
-{{if .IsCollaborator}}
+{{if or .IsCollaborator .IsOwner}}
 <div id="comment-sidebar" class="comment-sidebar">
     <div class="comment-sidebar-header">Comments</div>
     <div id="comment-threads" class="comment-threads"></div>
···
         if (!text) return;
 
         try {
+            const body = { paragraphId: activeCommentParagraphId, text };
+            if (ownerDID) body.ownerDID = ownerDID;
             const resp = await fetch(`/api/docs/${rkey}/comments`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ paragraphId: activeCommentParagraphId, text }),
+                body: JSON.stringify(body),
             });
             if (!resp.ok) throw new Error(await resp.text());
             closeCommentForm();
···
         }
     });
 
+    (function attachThreadClickHandler() {
+        const container = document.getElementById('comment-threads');
+        if (!container) return;
+        container.addEventListener('click', e => {
+            const thread = e.target.closest('.comment-thread');
+            if (!thread) return;
+            jumpToParagraph(thread.dataset.paragraph || '');
+        });
+    })();
+
     function renderCommentThreads(comments) {
         const container = document.getElementById('comment-threads');
         if (!container) return;
···
             byParagraph[pid].push(c);
         }
 
-        container.innerHTML = Object.entries(byParagraph).map(([pid, thread]) => `
+        container.innerHTML = Object.entries(byParagraph).map(([pid, thread]) => {
+            const label = pid === 'general' ? 'General' : 'Paragraph ' + (parseInt(pid.replace('p-', ''), 10) + 1);
+            return `
             <div class="comment-thread" data-paragraph="${escHtml(pid)}">
-                <div class="comment-thread-label">¶ ${escHtml(pid)}</div>
+                <div class="comment-thread-label">¶ ${escHtml(label)}</div>
                 ${thread.map(c => `
                     <div class="comment-item">
-                        <div class="comment-author">${escHtml(c.authorName || c.author)}</div>
+                        <div class="comment-author">${escHtml(c.authorHandle || c.author)}</div>
                         <div class="comment-text">${escHtml(c.text)}</div>
                         <div class="comment-time">${formatTime(c.createdAt)}</div>
                     </div>
                 `).join('')}
             </div>
-        `).join('');
+        `;
+        }).join('');
     }
 
     function formatTime(ts) {
···
     async function loadComments() {
         if (!accessToken) return;
         try {
-            const resp = await fetch(`/api/docs/${rkey}/comments`);
+            const qs = ownerDID ? '?ownerDID=' + encodeURIComponent(ownerDID) : '';
+            const resp = await fetch(`/api/docs/${rkey}/comments${qs}`);
             if (!resp.ok) return;
             const comments = await resp.json();
             renderCommentThreads(comments);
···
             console.error('Load comments failed:', e);
         }
     }
+
+    function jumpToParagraph(pid) {
+        if (pid === 'general') return;
+        const idx = parseInt(pid.replace('p-', ''), 10);
+        if (isNaN(idx)) return;
+        if (!milkdownEditor) return;
+        const pmView = milkdownEditor.action(ctx => ctx.get(editorViewCtx));
+        if (!pmView) return;
+        const pmEl = pmView.dom;
+        const blocks = Array.from(pmEl.children);
+        const target = blocks[idx];
+        if (!target) return;
+        target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        target.animate(
+            [{ outline: '3px solid rgba(234,179,8,0.9)', outlineOffset: '2px' },
+             { outline: '3px solid rgba(234,179,8,0)',   outlineOffset: '2px' }],
+            { duration: 1400, easing: 'ease-out' }
+        );
+    }
+
+    function setupParagraphCommentTrigger() {
+        const editorEl = document.getElementById('editor-rich');
+        if (!editorEl) return;
+        editorEl.addEventListener('click', e => {
+            const pmEl = e.target.closest('.ProseMirror');
+            if (!pmEl) return;
+            const paraEl = e.target.closest('p, h1, h2, h3, h4, h5, h6, li');
+            if (!paraEl) return;
+            const siblings = Array.from(paraEl.parentElement.children);
+            const idx = siblings.indexOf(paraEl);
+            const pid = 'p-' + idx;
+            activeCommentParagraphId = pid;
+            if (commentBtn) {
+                const rect = paraEl.getBoundingClientRect();
+                commentBtn.style.top = (rect.top + window.scrollY + rect.height / 2 - 12) + 'px';
+                commentBtn.style.left = (rect.right + window.scrollX + 8) + 'px';
+                commentBtn.style.display = 'block';
+            }
+        });
+    }
+    setupParagraphCommentTrigger();
 
     // ── Init ──────────────────────────────────────────────────────────────────