diff --git a/examples/chat-ui/AGENT.md b/examples/chat-ui/AGENT.md
index e56c778..d3a89a1 100644
--- a/examples/chat-ui/AGENT.md
+++ b/examples/chat-ui/AGENT.md
@@ -22,4 +22,52 @@
 - **Styling**: Tailwind CSS classes, responsive design patterns
 
 ## Tech Stack
-React 19, TypeScript, Vite, Tailwind CSS, Hono API, Cloudflare Workers, IndexedDB
+React 19, TypeScript, Vite, Tailwind CSS, Hono API, Cloudflare Workers, IndexedDB, React Router, use-mcp
+
+## Chat UI Specific Guidelines
+
+### Background Animation
+- Use CSS `hue-rotate` filter for color cycling (more performant than gradient animation)
+- Isolate animations to `::before` pseudo-elements with `z-index: -1` to prevent inheritance
+- Use `background-size: 100% 100vh` and `background-repeat: repeat-y` for repeating patterns
+- Initialize with random animation delay using CSS custom properties
+
+### Modal Patterns
+- Use `rgba(0,0,0,0.8)` for modal backdrops (avoid gradients that cause banding)
+- Implement click-outside-to-dismiss with `onClick` on backdrop and `stopPropagation` on content
+- Add `cursor-pointer` to all clickable elements including close buttons
+- Use `document.body.style.overflow = 'hidden'` to prevent background scrolling
+
+### MCP Server Management
+- Store multiple servers in localStorage as JSON array (`mcpServers`)
+- Track tool counts separately (`mcpServerToolCounts`) for disabled servers
+- Use server-specific IDs for state management
+- Each MCP server gets unique `useMcp` hook instance for proper isolation
+- OAuth state parameter automatically handles multiple server differentiation
+
+### State Persistence
+- Use localStorage for user preferences (model selection, server configurations)
+- Use sessionStorage for temporary state (single server URL in legacy components)
+- Clear related data when removing servers or models
+
+### UI Indicators
+- Use emoji-based indicators (🧠 for models, 🔌 for MCP servers)
+- Format counts as `enabled/total` (e.g., "1/2 servers, 3/5 tools")
+- Place model selector on left, MCP servers on right for balance
+- Show "none" instead of red symbols for cleaner unconfigured states
+
+### Component Organization
+- Keep disabled components in React tree but hidden with CSS (`{false && ...}`)
+- This prevents MCP connections from being destroyed when modals close
+- Use conditional rendering sparingly, prefer CSS visibility for stateful components
+
+### Routing and OAuth
+- Use React Router for OAuth callback routes (`/oauth/callback`)
+- OAuth callback should match main app styling with loading indicators
+- use-mcp library handles multiple server OAuth flows automatically via state parameters
+
+### Performance Considerations
+- Avoid animating gradients directly (causes repainting)
+- Use transform and filter animations (hardware accelerated)
+- Aggregate tools from multiple sources efficiently
+- Minimize localStorage reads in render loops