feat(mail): open recognized HWPX text from email attachments

AGENTS.md

@@ -446,6 +446,12 @@ in this repo.
   topic components, or label evidence by a bare document, model, topic, rank,
   label, or display value.
 - When reviews find public/private identifier leaks, stale API fixture shapes, or recurring bug patterns, update tests, frontend mocks, E2E mocks, README examples, architecture docs, and explicitly record the anti-pattern in `AGENTS.md` so the same bug pattern does not reappear in copied examples.
+- Mail attachment surfaces must list the current email's files with opaque
+  `asset_key` values and open the signed
+  `/api/data/repository-assets/{asset_key}/preview` contract. Do not expose
+  sequential attachment ids, render missing preview text as empty document
+  content, or send buyers only to the Data repository list as a substitute for
+  opening the HWPX file on the selected mail.
 - Memoized id-to-record Maps must be first-wins (`if (!map.has(key)) map.set(...)`).
   `new Map(items.map((item) => [String(item.id), item]))` is last-wins and
   desynchronizes first-wins label maps from the selected node or edge when

backend/api/emails.py

@@ -3,8 +3,10 @@
 from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import func, or_, select
+from sqlalchemy.orm import selectinload
 from db.session import get_db
 from db.models import Email
+from api.data import _opaque_asset_key
 from pydantic import BaseModel, EmailStr, Field, field_validator
 import datetime
 import time
@@ -165,6 +167,22 @@ def _email_list_item(
     )
 
 
+def _mail_attachment_refs(email: Email) -> list["EmailAttachmentRef"]:
+    """Return opaque, display-safe attachment refs for one scoped email."""
+
+    refs: list[EmailAttachmentRef] = []
+    for attachment in getattr(email, "attachments", None) or []:
+        file_name = _safe_email_display_text(getattr(attachment, "filename", None))
+        refs.append(
+            EmailAttachmentRef(
+                asset_key=_opaque_asset_key(email, attachment),
+                file_name=file_name or "email attachment",
+                parser_family=str(getattr(attachment, "parser_key", "") or "") or None,
+            )
+        )
+    return refs
+
+
 def _email_detail_response(email: Email) -> "EmailDetailResponse":
     return EmailDetailResponse(
         id=email.id,
@@ -178,6 +196,7 @@ def _email_detail_response(email: Email) -> "EmailDetailResponse":
         thread_id=canonical_thread_key(email),
         in_reply_to=email.in_reply_to,
         references=email.references,
+        attachments=_mail_attachment_refs(email),
     )
 
 
@@ -197,6 +216,14 @@ class EmailListItem(BaseModel):
     schedule_conflict: bool = False
 
 
+class EmailAttachmentRef(BaseModel):
+    """Opaque mail-attachment handle that opens the read-only preview contract."""
+
+    asset_key: str
+    file_name: str
+    parser_family: str | None = None
+
+
 class EmailDetailResponse(BaseModel):
     id: int
     message_id: str
@@ -211,6 +238,7 @@ class EmailDetailResponse(BaseModel):
     references: str | None = None
     requires_reply: bool = False
     schedule_conflict: bool = False
+    attachments: list[EmailAttachmentRef] = Field(default_factory=list)
 
 
 class UniqueThreadCandidateRequest(BaseModel):
@@ -645,7 +673,9 @@ async def get_email(
 ):
     # Ensure auth context validates the request payload and scopes access
     result = await db.execute(
-        select(Email).where(
+        select(Email)
+        .options(selectinload(Email.attachments))
+        .where(
             Email.id == email_id,
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
         )
@@ -668,6 +698,7 @@ async def get_email_thread(
     lookup_values = thread_lookup_values(thread_id)
     result = await db.execute(
         select(Email)
+        .options(selectinload(Email.attachments))
         .where(
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
             or_(