diff --git a/frontend/packages/agent/src/index.html b/frontend/packages/agent/src/index.html
index a437fab7..d5a2a334 100644
--- a/frontend/packages/agent/src/index.html
+++ b/frontend/packages/agent/src/index.html
@@ -8,16 +8,10 @@
 </head>
 <body class="agent-shell">
 
-  <!-- Fixed-overlay header (#394 redesign): two-row layout in the
-       main column — row 1 carries the title + meta-nav, row 2 carries
-       the live state strip. The agent icon eats the full header
-       height on the left as the identity anchor; flyout pills + an
-       overflow menu trigger sit on the right. Frosted glass over the
-       terminal — backdrop-filter blur shows the scrolled terminal
-       text behind.
-
-       All asset / API hrefs are relative — see docs/web-ui.md::Per-agent
-       relative paths for why (#14). -->
+  <!-- Fixed-overlay header — see docs/web-ui.md::Per-agent page
+       for the three-column layout (icon · main · pills). All asset
+       / API hrefs are relative — see docs/web-ui.md::Per-agent
+       relative paths for the document-baseURI resolution model. -->
   <header class="agent-header" id="agent-header">
     <img class="agent-icon" src="icon" alt="">
 
@@ -44,9 +38,9 @@
 
     <!-- Right cluster: flyout triggers + overflow menu. Pills stay
          hidden until their list is non-empty; the overflow `⋯` is
-         always visible (rebuild + new-session live inside it per
-         #394 — both rare, both destructive, both deserve one extra
-         click). -->
+         always visible. Rebuild + new-session + logout live inside
+         it — see docs/web-ui.md::Per-agent page (Overflow button)
+         for the rare-destructive-extra-click rationale. -->
     <div class="agent-header-pills">
       <button type="button" id="inbox-pill" class="header-pill header-pill-inbox" hidden
               title="open inbox flyout">
