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>
+  ),
+};