From 2f23e4f1cafd8edbdb7f85f66cb5c5c44a8ad24d Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sun, 7 Jun 2026 01:55:08 +0000
Subject: [PATCH] Add issue Documents tab + Open-in-Documents ergonomics
 (PAP-10569)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UX spec PAP-10520 §6. Inline IssueDocumentsSection plan editing/revision is
unchanged; it gains an "Open in Documents" (ExternalLink) button routing to
/documents/<id>?from=issue:<key> and a 💬N · ✎M feedback summary per doc.

New issue "Documents" tab (next to Chat/Activity/Related work) surfaces every
company document linked to the issue, reusing the library DocumentRow, pinning
the plan to the top, with scoped search and an Add document control (link
existing via picker / create new in Chat). Tab label shows the linked-doc count
plus an open-feedback dot.

Cross-issue document mention chip renders internal /<co>/documents/<id> links
in markdown using the chip-match-document-* tokens, with a hover summary of the
document title, status, and feedback counts.

Feedback counts come from one issue-scoped company-documents query shared by the
inline card and the tab (useIssueLinkedDocuments). Storybook stories added for
UX sign-off.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/IssueDocumentsSection.tsx   |  27 +-
 ui/src/components/IssueDocumentsTab.tsx       | 221 +++++++++++++++
 ui/src/components/MarkdownBody.tsx            |  65 ++++-
 .../documents/DocumentFeedbackCounts.tsx      |  54 ++++
 ui/src/hooks/useIssueLinkedDocuments.ts       |  42 +++
 ui/src/pages/IssueDetail.tsx                  |  38 +++
 .../issue-documents-integration.stories.tsx   | 251 ++++++++++++++++++
 7 files changed, 694 insertions(+), 4 deletions(-)
 create mode 100644 ui/src/components/IssueDocumentsTab.tsx
 create mode 100644 ui/src/components/documents/DocumentFeedbackCounts.tsx
 create mode 100644 ui/src/hooks/useIssueLinkedDocuments.ts
 create mode 100644 ui/storybook/stories/issue-documents-integration.stories.tsx

diff --git a/ui/src/components/IssueDocumentsSection.tsx b/ui/src/components/IssueDocumentsSection.tsx
index 4b329cfeab1..5946190ec16 100644
--- a/ui/src/components/IssueDocumentsSection.tsx
+++ b/ui/src/components/IssueDocumentsSection.tsx
@@ -9,11 +9,13 @@ import type {
   Issue,
   IssueDocument,
 } from "@paperclipai/shared";
-import { isSystemIssueDocumentKey } from "@paperclipai/shared";
-import { useLocation } from "@/lib/router";
+import { buildDocumentReferenceHref, isSystemIssueDocumentKey } from "@paperclipai/shared";
+import { Link, useLocation } from "@/lib/router";
 import { ApiError } from "../api/client";
 import { issuesApi } from "../api/issues";
 import { useAutosaveIndicator } from "../hooks/useAutosaveIndicator";
+import { useIssueLinkedDocuments } from "../hooks/useIssueLinkedDocuments";
+import { DocumentFeedbackCounts } from "./documents/DocumentFeedbackCounts";
 import { deriveDocumentRevisionState } from "../lib/document-revisions";
 import type { CompanyUserProfile } from "../lib/company-members";
 import { queryKeys } from "../lib/queryKeys";
@@ -35,7 +37,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { Check, ChevronDown, ChevronRight, Copy, Diff, Download, FilePenLine, FileText, Lock, MoreHorizontal, Plus, Trash2, Unlock, X } from "lucide-react";
+import { Check, ChevronDown, ChevronRight, Copy, Diff, Download, ExternalLink, FilePenLine, FileText, Lock, MoreHorizontal, Plus, Trash2, Unlock, X } from "lucide-react";
 import { DocumentDiffModal } from "./DocumentDiffModal";
 import { SourceTrustBadge } from "./SourceTrustBadge";
 
@@ -219,6 +221,10 @@ export function IssueDocumentsSection({
     queryFn: () => issuesApi.listDocuments(issue.id),
   });
 
+  // Company-document summaries for this issue carry feedback counts (open comments
+  // / pending suggestions) keyed by the same id as the inline issue document.
+  const { byId: linkedDocumentById } = useIssueLinkedDocuments(issue.companyId, issue.id);
+
   const { data: activeDocumentRevisions, isFetching: isFetchingDocumentRevisions } = useQuery({
     queryKey: revisionMenuOpenKey
       ? queryKeys.issues.documentRevisions(issue.id, revisionMenuOpenKey)
@@ -1000,10 +1006,25 @@ export function IssueDocumentsSection({
                         onToggle={() => toggleAnnotationPanel(doc.key)}
                       />
                     ) : null}
+                    <DocumentFeedbackCounts counts={linkedDocumentById.get(doc.id)?.feedbackCounts} />
                   </div>
                   {showTitle && <p className="mt-2 text-sm font-medium">{displayedTitle}</p>}
                 </div>
                 <div className="flex items-center gap-1 shrink-0">
+                  <Button
+                    asChild
+                    variant="ghost"
+                    size="icon-xs"
+                    className="text-muted-foreground transition-colors"
+                    title="Open in Documents"
+                  >
+                    <Link
+                      to={buildDocumentReferenceHref(doc.id, doc.key)}
+                      aria-label={`Open ${doc.key} in Documents`}
+                    >
+                      <ExternalLink className="h-3.5 w-3.5" />
+                    </Link>
+                  </Button>
                   {canManageDocumentLocks ? (
                     <Button
                       variant="ghost"
diff --git a/ui/src/components/IssueDocumentsTab.tsx b/ui/src/components/IssueDocumentsTab.tsx
new file mode 100644
index 00000000000..e6e40a04bff
--- /dev/null
+++ b/ui/src/components/IssueDocumentsTab.tsx
@@ -0,0 +1,221 @@
+import { useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { FileText, Plus, Search, X } from "lucide-react";
+import type { Agent, CompanyDocumentSummary } from "@paperclipai/shared";
+import { buildDocumentReferenceHref } from "@paperclipai/shared";
+import { documentsApi } from "../api/documents";
+import { queryKeys } from "../lib/queryKeys";
+import { useIssueLinkedDocuments } from "../hooks/useIssueLinkedDocuments";
+import { DocumentRow, type DocumentOwner } from "./documents/DocumentRow";
+import { hasOpenDocumentFeedback } from "./documents/DocumentFeedbackCounts";
+import { EmptyState } from "./EmptyState";
+import { PageSkeleton } from "./PageSkeleton";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+
+/** Find the inline issue-document key for a company document linked to this issue. */
+function issueDocumentKeyFor(doc: CompanyDocumentSummary, issueId: string): string | null {
+  const link = doc.backlinks.find(
+    (backlink) => backlink.targetType === "issue" && backlink.targetId === issueId,
+  );
+  return link?.issueDocumentKey ?? null;
+}
+
+function isPlanDocument(doc: CompanyDocumentSummary, issueId: string): boolean {
+  return issueDocumentKeyFor(doc, issueId) === "plan";
+}
+
+export interface IssueDocumentsTabProps {
+  issueId: string;
+  companyId: string;
+  issueIdentifier: string | null;
+  agentMap?: ReadonlyMap<string, Pick<Agent, "id" | "name">>;
+}
+
+/**
+ * "Documents" tab on the issue detail. Surfaces every company document linked to the
+ * issue (its inline issue documents plus cross-linked company docs), reusing the
+ * library `DocumentRow`. The plan document is pinned to the top; the header has a
+ * search scoped to this issue and an "Add document" control (link existing / create new).
+ */
+export function IssueDocumentsTab({ issueId, companyId, issueIdentifier, agentMap }: IssueDocumentsTabProps) {
+  const queryClient = useQueryClient();
+  const [search, setSearch] = useState("");
+  const [linkPickerOpen, setLinkPickerOpen] = useState(false);
+
+  const { documents, isLoading } = useIssueLinkedDocuments(companyId, issueId, { search });
+
+  const ownerById = useMemo(() => {
+    const map = new Map<string, DocumentOwner>();
+    if (agentMap) {
+      for (const agent of agentMap.values()) map.set(agent.id, { name: agent.name });
+    }
+    return map;
+  }, [agentMap]);
+
+  const sortedDocuments = useMemo(() => {
+    return [...documents].sort((a, b) => {
+      const aPlan = isPlanDocument(a, issueId);
+      const bPlan = isPlanDocument(b, issueId);
+      if (aPlan && !bPlan) return -1;
+      if (!aPlan && bPlan) return 1;
+      return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+    });
+  }, [documents, issueId]);
+
+  const linkExisting = useMutation({
+    mutationFn: (documentId: string) =>
+      documentsApi.createLink(companyId, documentId, { targetType: "issue", targetId: issueId }),
+    onSuccess: () => {
+      setLinkPickerOpen(false);
+      queryClient.invalidateQueries({ queryKey: ["documents"] });
+    },
+  });
+
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <div className="relative w-full sm:max-w-xs">
+          <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            value={search}
+            onChange={(event) => setSearch(event.currentTarget.value)}
+            placeholder="Search this issue's documents..."
+            aria-label="Search issue documents"
+            className="h-9 pl-9 pr-9 text-sm"
+          />
+          {search.length > 0 ? (
+            <button
+              type="button"
+              onClick={() => setSearch("")}
+              aria-label="Clear document search"
+              className="absolute right-2 top-1/2 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground"
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
+          ) : null}
+        </div>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="outline" size="sm" className="h-9 shrink-0">
+              <Plus className="mr-1.5 h-3.5 w-3.5" />
+              Add document
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-56">
+            <DropdownMenuItem onSelect={() => setLinkPickerOpen(true)}>
+              Link existing document…
+            </DropdownMenuItem>
+            <DropdownMenuItem asChild>
+              <a href="#document-new">Create new document in Chat</a>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+
+      {isLoading ? (
+        <PageSkeleton variant="list" />
+      ) : sortedDocuments.length === 0 ? (
+        search.length > 0 ? (
+          <EmptyState icon={FileText} message="No linked documents match this search." />
+        ) : (
+          <EmptyState
+            icon={FileText}
+            message="Only the plan document is linked. Add a spec, brief, or report to keep more context here."
+          />
+        )
+      ) : (
+        <div className="overflow-hidden rounded-md border border-border">
+          {sortedDocuments.map((doc) => {
+            const key = issueDocumentKeyFor(doc, issueId);
+            return (
+              <DocumentRow
+                key={doc.id}
+                document={doc}
+                to={buildDocumentReferenceHref(doc.id, key ?? issueIdentifier)}
+                identifier={key ?? undefined}
+                owner={doc.ownerAgentId ? ownerById.get(doc.ownerAgentId) ?? null : null}
+              />
+            );
+          })}
+        </div>
+      )}
+
+      <LinkExistingDocumentPicker
+        open={linkPickerOpen}
+        onOpenChange={setLinkPickerOpen}
+        companyId={companyId}
+        linkedIds={new Set(documents.map((doc) => doc.id))}
+        onSelect={(documentId) => linkExisting.mutate(documentId)}
+        pending={linkExisting.isPending}
+      />
+    </div>
+  );
+}
+
+function LinkExistingDocumentPicker({
+  open,
+  onOpenChange,
+  companyId,
+  linkedIds,
+  onSelect,
+  pending,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  companyId: string;
+  linkedIds: Set<string>;
+  onSelect: (documentId: string) => void;
+  pending: boolean;
+}) {
+  const { data: allDocuments } = useQuery({
+    queryKey: queryKeys.documents.list(companyId, { picker: true }),
+    queryFn: () => documentsApi.list(companyId, { limit: 100 }),
+    enabled: open && Boolean(companyId),
+  });
+
+  const candidates = useMemo(
+    () => (allDocuments ?? []).filter((doc) => !linkedIds.has(doc.id)),
+    [allDocuments, linkedIds],
+  );
+
+  return (
+    <CommandDialog open={open} onOpenChange={onOpenChange}>
+      <CommandInput placeholder="Search company documents to link..." />
+      <CommandList>
+        <CommandEmpty>No documents found.</CommandEmpty>
+        <CommandGroup heading="Documents">
+          {candidates.map((doc) => (
+            <CommandItem
+              key={doc.id}
+              value={`${doc.title ?? "Untitled document"} ${doc.id}`}
+              disabled={pending}
+              onSelect={() => onSelect(doc.id)}
+            >
+              <FileText className="mr-2 h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
+              <span className="truncate">{doc.title ?? "Untitled document"}</span>
+              {hasOpenDocumentFeedback(doc.feedbackCounts) ? (
+                <span className="ml-auto h-1.5 w-1.5 rounded-full bg-amber-500" aria-hidden="true" />
+              ) : null}
+            </CommandItem>
+          ))}
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  );
+}
diff --git a/ui/src/components/MarkdownBody.tsx b/ui/src/components/MarkdownBody.tsx
index 4d4cb8e7bf7..107ae8413ba 100644
--- a/ui/src/components/MarkdownBody.tsx
+++ b/ui/src/components/MarkdownBody.tsx
@@ -1,6 +1,7 @@
 import { isValidElement, useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
 import { useQuery } from "@tanstack/react-query";
-import { Check, Copy, ExternalLink, Github, WrapText } from "lucide-react";
+import { Check, Copy, ExternalLink, FileText, Github, WrapText } from "lucide-react";
+import { parseDocumentReferenceHref } from "@paperclipai/shared";
 import Markdown, { defaultUrlTransform, type Components, type Options } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { cn } from "../lib/utils";
@@ -9,6 +10,7 @@ import { useTheme } from "../context/ThemeContext";
 import { useOptionalCompany } from "../context/CompanyContext";
 import { mentionChipInlineStyle, parseMentionChipHref } from "../lib/mention-chips";
 import { issuesApi } from "../api/issues";
+import { documentsApi } from "../api/documents";
 import { queryKeys } from "../lib/queryKeys";
 import { parseIssueReferenceFromHref, remarkLinkIssueReferences } from "../lib/issue-reference";
 import { remarkSoftBreaks } from "../lib/remark-soft-breaks";
@@ -68,6 +70,56 @@ function MarkdownIssueLink({
   );
 }
 
+/**
+ * Cross-issue document mention chip. Renders a reference to `/<co>/documents/<id>`
+ * using the `chip-match-document-*` token family. Hovering surfaces the document
+ * title, status, and feedback counts via a composed tooltip.
+ */
+function MarkdownDocumentLink({
+  href,
+  documentId,
+  children,
+}: {
+  href: string;
+  documentId: string;
+  children: ReactNode;
+}) {
+  const company = useOptionalCompany();
+  const companyId = company?.selectedCompanyId ?? null;
+  const { data } = useQuery({
+    queryKey: queryKeys.documents.detail(companyId ?? "", documentId),
+    queryFn: () => documentsApi.get(companyId!, documentId),
+    enabled: Boolean(companyId),
+    staleTime: 60_000,
+  });
+
+  const title = data?.title ?? null;
+  const status = data?.status ?? null;
+  const counts = data?.feedbackCounts ?? null;
+  const openComments = counts ? counts.openComments + counts.openReviewThreads : 0;
+  const pendingSuggestions = counts?.pendingSuggestions ?? 0;
+  const tooltip = [
+    title ?? "Document",
+    status ? `· ${status.replace(/_/g, " ")}` : null,
+    openComments > 0 ? `· 💬 ${openComments}` : null,
+    pendingSuggestions > 0 ? `· ✎ ${pendingSuggestions}` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <Link
+      to={href}
+      data-mention-kind="document"
+      title={tooltip}
+      className="inline-flex items-center gap-1 rounded-full border px-2 py-px align-[-0.125em] text-[0.85em] font-medium leading-none no-underline bg-[var(--chip-match-document-bg)] text-[var(--chip-match-document-fg)] border-[var(--chip-match-document-border)]"
+    >
+      <FileText className="h-3 w-3" aria-hidden="true" />
+      {children}
+    </Link>
+  );
+}
+
 function loadMermaid() {
   if (!mermaidLoaderPromise) {
     mermaidLoaderPromise = import("mermaid").then((module) => module.default);
@@ -658,6 +710,17 @@ export function MarkdownBody({
         );
       }
 
+      // Only internal references (e.g. `/PAP/documents/<id>`) become document chips;
+      // external links that happen to contain `/documents/` are left as plain links.
+      const documentRef = href && href.startsWith("/") ? parseDocumentReferenceHref(href) : null;
+      if (documentRef && href) {
+        return (
+          <MarkdownDocumentLink href={href} documentId={documentRef.documentId}>
+            {linkChildren}
+          </MarkdownDocumentLink>
+        );
+      }
+
       const parsed = href ? parseMentionChipHref(href) : null;
       if (parsed) {
         const targetHref = parsed.kind === "project"
diff --git a/ui/src/components/documents/DocumentFeedbackCounts.tsx b/ui/src/components/documents/DocumentFeedbackCounts.tsx
new file mode 100644
index 00000000000..08ed85fdd22
--- /dev/null
+++ b/ui/src/components/documents/DocumentFeedbackCounts.tsx
@@ -0,0 +1,54 @@
+import { MessageSquare, PencilLine } from "lucide-react";
+import type { DocumentFeedbackCounts as DocumentFeedbackCountsData } from "@paperclipai/shared";
+import { cn } from "@/lib/utils";
+
+export function openCommentCount(counts: DocumentFeedbackCountsData): number {
+  return counts.openComments + counts.openReviewThreads;
+}
+
+export function pendingSuggestionCount(counts: DocumentFeedbackCountsData): number {
+  return counts.pendingSuggestions;
+}
+
+export function hasOpenDocumentFeedback(counts: DocumentFeedbackCountsData | null | undefined): boolean {
+  if (!counts) return false;
+  return openCommentCount(counts) > 0 || pendingSuggestionCount(counts) > 0;
+}
+
+/**
+ * Compact `💬 N · ✎ M` feedback summary for a document — open comments and pending
+ * suggestions. Shared between the inline issue document card and the Documents tab so
+ * the same counts read identically everywhere. Renders nothing when there is no feedback.
+ */
+export function DocumentFeedbackCounts({
+  counts,
+  className,
+}: {
+  counts: DocumentFeedbackCountsData | null | undefined;
+  className?: string;
+}) {
+  if (!counts) return null;
+  const comments = openCommentCount(counts);
+  const suggestions = pendingSuggestionCount(counts);
+  if (comments === 0 && suggestions === 0) return null;
+
+  return (
+    <span
+      className={cn("inline-flex items-center gap-2 text-[11px] text-muted-foreground", className)}
+      data-testid="document-feedback-counts"
+    >
+      {comments > 0 ? (
+        <span className="inline-flex items-center gap-0.5" title={`${comments} open comment(s)`}>
+          <MessageSquare className="h-3 w-3" aria-hidden="true" />
+          <span className="tabular-nums">{comments}</span>
+        </span>
+      ) : null}
+      {suggestions > 0 ? (
+        <span className="inline-flex items-center gap-0.5" title={`${suggestions} pending suggestion(s)`}>
+          <PencilLine className="h-3 w-3" aria-hidden="true" />
+          <span className="tabular-nums">{suggestions}</span>
+        </span>
+      ) : null}
+    </span>
+  );
+}
diff --git a/ui/src/hooks/useIssueLinkedDocuments.ts b/ui/src/hooks/useIssueLinkedDocuments.ts
new file mode 100644
index 00000000000..c1a96996e41
--- /dev/null
+++ b/ui/src/hooks/useIssueLinkedDocuments.ts
@@ -0,0 +1,42 @@
+import { useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import type { CompanyDocumentSummary } from "@paperclipai/shared";
+import { documentsApi, type CompanyDocumentListFilters } from "../api/documents";
+import { queryKeys } from "../lib/queryKeys";
+
+/**
+ * Company documents linked to an issue (its inline issue documents plus any
+ * cross-linked company docs). Backs both the inline issue document card feedback
+ * counts and the issue "Documents" tab, so they stay in sync from one query.
+ */
+export function useIssueLinkedDocuments(
+  companyId: string | null | undefined,
+  issueId: string,
+  options: { search?: string; enabled?: boolean } = {},
+) {
+  const filters: CompanyDocumentListFilters = useMemo(
+    () => ({
+      targetType: "issue",
+      targetId: issueId,
+      q: options.search?.trim() || undefined,
+      includeArchived: true,
+      limit: 200,
+    }),
+    [issueId, options.search],
+  );
+
+  const query = useQuery({
+    queryKey: queryKeys.documents.list(companyId ?? "", filters as Record<string, unknown>),
+    queryFn: () => documentsApi.list(companyId!, filters),
+    enabled: Boolean(companyId) && (options.enabled ?? true),
+    placeholderData: (previous) => previous,
+  });
+
+  const byId = useMemo(() => {
+    const map = new Map<string, CompanyDocumentSummary>();
+    for (const doc of query.data ?? []) map.set(doc.id, doc);
+    return map;
+  }, [query.data]);
+
+  return { ...query, documents: query.data ?? [], byId };
+}
diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsx
index d622bd81e33..b8090a63e51 100644
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -67,6 +67,9 @@ import { IssueChatThread, type IssueChatComposerHandle } from "../components/Iss
 import { IssueContinuationHandoff } from "../components/IssueContinuationHandoff";
 import { IssueAttachmentsSection } from "../components/IssueAttachmentsSection";
 import { IssueDocumentsSection } from "../components/IssueDocumentsSection";
+import { IssueDocumentsTab } from "../components/IssueDocumentsTab";
+import { useIssueLinkedDocuments } from "../hooks/useIssueLinkedDocuments";
+import { hasOpenDocumentFeedback } from "../components/documents/DocumentFeedbackCounts";
 import { IssuePlanDecompositionsSection } from "../components/IssuePlanDecompositionsSection";
 import { IssueOutputSection } from "../components/issue-output/IssueOutputSection";
 import { isImageAttachment } from "../lib/issue-attachments";
@@ -127,6 +130,7 @@ import {
   Copy,
   Eye,
   EyeOff,
+  FileText,
   Flag,
   Hexagon,
   ListTree,
@@ -1543,6 +1547,14 @@ export function IssueDetail() {
     for (const a of agents ?? []) map.set(a.id, a);
     return map;
   }, [agents]);
+  const { documents: linkedDocuments } = useIssueLinkedDocuments(issue?.companyId, issue?.id ?? "", {
+    enabled: Boolean(issue?.id),
+  });
+  const linkedDocumentCount = linkedDocuments.length;
+  const hasOpenLinkedDocFeedback = useMemo(
+    () => linkedDocuments.some((doc) => hasOpenDocumentFeedback(doc.feedbackCounts)),
+    [linkedDocuments],
+  );
   const userProfileMap = useMemo(
     () => buildCompanyUserProfileMap(companyMembers?.users),
     [companyMembers?.users],
@@ -3918,6 +3930,21 @@ export function IssueDetail() {
             <ActivityIcon className="h-3.5 w-3.5" />
             Activity
           </TabsTrigger>
+          <TabsTrigger value="documents" className="gap-1.5">
+            <FileText className="h-3.5 w-3.5" />
+            Documents
+            {linkedDocumentCount > 0 ? (
+              <span className="ml-0.5 rounded-full bg-muted px-1.5 text-[10px] tabular-nums leading-4 text-muted-foreground">
+                {linkedDocumentCount}
+              </span>
+            ) : null}
+            {hasOpenLinkedDocFeedback ? (
+              <span
+                className="h-1.5 w-1.5 rounded-full bg-amber-500"
+                aria-label="Open feedback on linked documents"
+              />
+            ) : null}
+          </TabsTrigger>
           <TabsTrigger value="related-work" className="gap-1.5">
             <ListTree className="h-3.5 w-3.5" />
             Related work
@@ -4031,6 +4058,17 @@ export function IssueDetail() {
           ) : null}
         </TabsContent>
 
+        <TabsContent value="documents">
+          {detailTab === "documents" ? (
+            <IssueDocumentsTab
+              issueId={issue.id}
+              companyId={issue.companyId}
+              issueIdentifier={issue.identifier}
+              agentMap={agentMap}
+            />
+          ) : null}
+        </TabsContent>
+
         <TabsContent value="related-work">
           <IssueRelatedWorkPanel relatedWork={issue.relatedWork} />
         </TabsContent>
diff --git a/ui/storybook/stories/issue-documents-integration.stories.tsx b/ui/storybook/stories/issue-documents-integration.stories.tsx
new file mode 100644
index 00000000000..4f8240dd2bd
--- /dev/null
+++ b/ui/storybook/stories/issue-documents-integration.stories.tsx
@@ -0,0 +1,251 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ChevronDown, Copy, ExternalLink, FileText, MoreHorizontal, Plus, Search } from "lucide-react";
+import type { CompanyDocumentSummary, DocumentFeedbackCounts as Counts } from "@paperclipai/shared";
+import { DocumentRow } from "@/components/documents/DocumentRow";
+import { DocumentFeedbackCounts } from "@/components/documents/DocumentFeedbackCounts";
+import { EmptyState } from "@/components/EmptyState";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+
+/**
+ * Storybook coverage for the issue ↔ documents integration (PAP-10569, UX spec §6).
+ *
+ * Renders the real presentational pieces — `DocumentRow`, `DocumentFeedbackCounts`,
+ * and the `chip-match-document-*` mention chip — inside static shells so UX/QA can
+ * capture sign-off screenshots without a live backend. Interactive behaviour
+ * (autosave, linking, navigation) is covered by unit tests.
+ */
+
+function emptyCounts(): Counts {
+  return {
+    openComments: 0,
+    resolvedComments: 0,
+    openReviewThreads: 0,
+    resolvedReviewThreads: 0,
+    pendingSuggestions: 0,
+    acceptedSuggestions: 0,
+    rejectedSuggestions: 0,
+    staleAnchors: 0,
+    orphanedAnchors: 0,
+  };
+}
+
+const HOUR = 1000 * 60 * 60;
+const now = new Date("2026-06-07T12:00:00Z").getTime();
+
+function makeDocument(overrides: Partial<CompanyDocumentSummary>): CompanyDocumentSummary {
+  return {
+    id: "doc",
+    companyId: "company-storybook",
+    title: "Untitled document",
+    format: "markdown",
+    status: "in_review",
+    documentType: "spec",
+    summary: null,
+    ownerAgentId: "agent-1",
+    ownerUserId: null,
+    latestRevisionId: "rev-1",
+    latestRevisionNumber: 1,
+    createdByAgentId: "agent-1",
+    createdByUserId: null,
+    updatedByAgentId: "agent-1",
+    updatedByUserId: null,
+    lockedAt: null,
+    lockedByAgentId: null,
+    lockedByUserId: null,
+    sourceTrust: null,
+    archivedAt: null,
+    archivedByAgentId: null,
+    archivedByUserId: null,
+    createdAt: new Date("2026-06-01T00:00:00Z"),
+    updatedAt: new Date(now - 2 * HOUR),
+    backlinks: [],
+    feedbackCounts: emptyCounts(),
+    ...overrides,
+  };
+}
+
+const ISSUE_KEY = "issue";
+const ISSUE_TARGET = "issue-781c5dcf";
+
+function issueBacklink(documentKey: string) {
+  return {
+    targetType: "issue",
+    targetId: ISSUE_TARGET,
+    issueDocumentKey: documentKey,
+    identifier: "PAP-10569",
+  } as never;
+}
+
+const PLAN_DOC = makeDocument({
+  id: "doc-plan",
+  title: "Plan",
+  documentType: "plan",
+  status: "in_review",
+  summary: "Implementation plan for the issue documents tab and ergonomics.",
+  updatedAt: new Date(now - 1 * HOUR),
+  backlinks: [issueBacklink("plan")],
+  feedbackCounts: { ...emptyCounts(), openComments: 5, pendingSuggestions: 2 },
+});
+
+const SPEC_DOC = makeDocument({
+  id: "doc-spec",
+  title: "Documents tab — interaction spec",
+  documentType: "spec",
+  status: "draft",
+  summary: "Scoped search, pinned plan, Add document, cross-issue chip.",
+  updatedAt: new Date(now - 6 * HOUR),
+  backlinks: [issueBacklink("spec")],
+  feedbackCounts: { ...emptyCounts(), openReviewThreads: 1 },
+});
+
+const LINKED_REPORT = makeDocument({
+  id: "doc-report",
+  title: "Roughdraft borrow — findings",
+  documentType: "report",
+  status: "approved",
+  summary: "Cross-linked company document surfaced on the issue.",
+  updatedAt: new Date(now - 30 * HOUR),
+  backlinks: [{ targetType: "issue", targetId: ISSUE_TARGET, identifier: "PAP-10507" } as never],
+});
+
+const TAB_DOCS = [PLAN_DOC, SPEC_DOC, LINKED_REPORT];
+
+function Shell({ children, width = 760 }: { children: React.ReactNode; width?: number }) {
+  return (
+    <div className="bg-background text-foreground p-6">
+      <div className="mx-auto w-full space-y-4" style={{ maxWidth: width }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/** Reconstructs the inline issue-document card header (Chat surface). */
+function InlineDocumentCard({ doc, docKey }: { doc: CompanyDocumentSummary; docKey: string }) {
+  return (
+    <div className="rounded-lg border border-border p-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2 min-w-0">
+            <ChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
+            <span className="shrink-0 rounded-full border border-border px-2 py-0.5 font-mono text-[10px] uppercase tracking-[0.16em] text-muted-foreground">
+              {docKey}
+            </span>
+            <Button variant="ghost" size="sm" className="h-auto px-1.5 py-0 text-[11px] font-normal text-muted-foreground">
+              rev {doc.latestRevisionNumber}
+              <ChevronDown className="h-3 w-3" />
+            </Button>
+            <span className="text-[11px] text-muted-foreground">updated 1h ago</span>
+            <DocumentFeedbackCounts counts={doc.feedbackCounts} />
+          </div>
+          {doc.title && docKey !== "plan" ? <p className="mt-2 text-sm font-medium">{doc.title}</p> : null}
+        </div>
+        <div className="flex items-center gap-1 shrink-0">
+          <Button asChild variant="ghost" size="icon-xs" className="text-muted-foreground" title="Open in Documents">
+            <a href={`/PAP/documents/${doc.id}?from=issue:${docKey}`} aria-label={`Open ${docKey} in Documents`}>
+              <ExternalLink className="h-3.5 w-3.5" />
+            </a>
+          </Button>
+          <Button variant="ghost" size="icon-xs" className="text-muted-foreground" title="Copy document">
+            <Copy className="h-3.5 w-3.5" />
+          </Button>
+          <Button variant="ghost" size="icon-xs" className="text-muted-foreground" title="Document actions">
+            <MoreHorizontal className="h-3.5 w-3.5" />
+          </Button>
+        </div>
+      </div>
+      <div className="mt-3 text-[15px] leading-7 text-muted-foreground">
+        {docKey === "plan"
+          ? "## Goal\nPreserve inline plan editing while making linked docs discoverable…"
+          : doc.summary}
+      </div>
+    </div>
+  );
+}
+
+const meta: Meta = {
+  title: "Pages/Issue Documents Integration",
+  parameters: { layout: "fullscreen" },
+};
+
+export default meta;
+type Story = StoryObj;
+
+/** §6.1 — inline card gains an "Open in Documents" button and 💬 / ✎ feedback counts. */
+export const InlineCard: Story = {
+  render: () => (
+    <Shell>
+      <h3 className="text-sm font-medium text-muted-foreground">Documents</h3>
+      <div className="space-y-3">
+        <InlineDocumentCard doc={PLAN_DOC} docKey="plan" />
+        <InlineDocumentCard doc={SPEC_DOC} docKey="spec" />
+      </div>
+    </Shell>
+  ),
+};
+
+/** §6.2 — the new issue "Documents" tab: scoped search, Add document, pinned plan. */
+export const DocumentsTab: Story = {
+  render: () => (
+    <Shell>
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <div className="relative w-full sm:max-w-xs">
+          <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input placeholder="Search this issue's documents..." className="h-9 pl-9 text-sm" readOnly />
+        </div>
+        <Button variant="outline" size="sm" className="h-9 shrink-0">
+          <Plus className="mr-1.5 h-3.5 w-3.5" />
+          Add document
+        </Button>
+      </div>
+      <div className="overflow-hidden rounded-md border border-border">
+        {TAB_DOCS.map((doc) => {
+          const key = doc.backlinks.find((b) => b.targetType === "issue")?.issueDocumentKey ?? undefined;
+          return (
+            <DocumentRow
+              key={doc.id}
+              document={doc}
+              to={`/PAP/documents/${doc.id}?from=issue:${key ?? "PAP-10569"}`}
+              identifier={key ?? undefined}
+              owner={{ name: "ClaudeCoder" }}
+            />
+          );
+        })}
+      </div>
+    </Shell>
+  ),
+};
+
+/** §6.2 — empty state when only the plan is linked. */
+export const DocumentsTabEmpty: Story = {
+  render: () => (
+    <Shell>
+      <EmptyState
+        icon={FileText}
+        message="Only the plan document is linked. Add a spec, brief, or report to keep more context here."
+      />
+    </Shell>
+  ),
+};
+
+/** §6.3 — cross-issue document mention chip using the chip-match-document tokens. */
+export const MentionChip: Story = {
+  render: () => (
+    <Shell width={560}>
+      <div className="rounded-lg border border-border bg-card p-4 text-sm leading-7">
+        Tracking the rollout in{" "}
+        <a
+          href="/PAP/documents/doc-spec"
+          data-mention-kind="document"
+          title="Documents tab — interaction spec · draft · 💬 1"
+          className="inline-flex items-center gap-1 rounded-full border px-2 py-px align-[-0.125em] text-[0.85em] font-medium leading-none no-underline bg-[var(--chip-match-document-bg)] text-[var(--chip-match-document-fg)] border-[var(--chip-match-document-border)]"
+        >
+          <FileText className="h-3 w-3" aria-hidden="true" />
+          interaction spec
+        </a>{" "}
+        — please leave suggestions there before Friday.
+      </div>
+    </Shell>
+  ),
+};