diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md
index 05fdf3e3..568af3d7 100644
--- a/docs/swarm/ui.md
+++ b/docs/swarm/ui.md
@@ -309,6 +309,22 @@ live rows only.
 
 </details>
 
+### Issue report
+
+The **issues** page lists the open issues of every repo that has one, from
+`GET /api/issue-report`, or of one repo from
+`GET /api/repos/{org}/{repo}/issue-report`. Each row shows whether an open
+dependency blocks the issue and how many other issues depend on it. The
+list sorts by that count by default, and **hide blocked** drops the blocked
+rows.
+
+Picking a repo fetches its report again. The page remembers the pick, so a
+repo that no longer has an open issue stays in the **repo** select with the label
+**no open issues**, and the table stays filtered to it. The repo list and the report
+fail on their own: a repo list that fails to load shows its error beside the
+report, and a report that fails to load clears the table instead of leaving the
+previous repo's issues under the error.
+
 ### Builds
 
 The **builds** page lists the agent config PR heads the swarm builder built,