diff --git a/COMPONENT_GUIDE.md b/COMPONENT_GUIDE.md
index 4d91a92..8eb6f7f 100644
--- a/COMPONENT_GUIDE.md
+++ b/COMPONENT_GUIDE.md
@@ -62,6 +62,7 @@
 - Section with title + action → **SectionHeader**
 - Empty content placeholder → **EmptyState**
 - Grouped content box → **Card** (with optional accent)
+- Grouped items with header + meta + footer → **GroupCard** (e.g., app instances)
 
 ### "I need to display text"
 - Code/JSON payload → **CodeBlock** (with line numbers, copy button)
@@ -122,6 +123,17 @@ TreeView for hierarchical data (Application → Routes → Processors)
   onSelect navigates or opens DetailPanel
 ```
 
+### Agent/instance health pattern
+```
+StatCard strip (top, recalculates per scope)
+  → GroupCard grid (2-col for all, full-width for single app)
+    Each GroupCard: header (app name + count) + meta (TPS, routes) + instance rows
+    Instance rows: StatusDot + name + Badge + metrics
+    Single instance: expanded with LineChart panels
+  → EventFeed (bottom, filtered by scope)
+URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/:instanceId
+```
+
 ## Component Index
 
 | Component | Layer | When to use |