feat: Add comprehensive design documentation for Krates

- Canvas: Infinite zoomable workspace with LOD and navigation
- Spotlight: Fuzzy search with type filters and view shortcuts
- Krate: Window group container with non-overlapping placement
- Detail Window: YAML/Describe/Logs/Shell views with maximize
- Top Bar: Cluster info, user presence, admin toggle
- Admin Drawer: Multi-user presence and spectate functionality
- Minimap: Browse and navigate canvas overview
- Collection Window: List/tree views with filtering and sorting
- Shell/Logs: Real-time terminal and log streaming
- Backend: Go service with K8s API, WebSocket handlers, CRDT sync
- Architecture: Full project structure and tech stack

design/top-bar.md

@@ -0,0 +1,131 @@
+# Top Bar Feature Specification
+
+## Overview
+The top bar is the primary navigation and status bar for the application. It provides quick access to cluster information, user presence, and global actions.
+
+## Layout
+
+### Container
+- Position: `absolute; top: 0; left: 0; right: 0; z-index: 10; height ~56px`
+- Layout: `display: flex; align-items: center; padding: 13px 18px`
+- Background: None (transparent over canvas)
+
+## Components
+
+### Left Side (left→right)
+
+#### Logo Pill
+- **Text**: `krates / yard`
+- **Styling**:
+  - `background: rgba(14,18,25,.82)`
+  - `border: 1px solid rgba(140,165,200,.18)`
+  - `border-radius: 9px`
+  - `padding: 7px 12px`
+  - `backdrop-filter: blur(6px)`
+- **Diamond glyph**: `clip-path: polygon(50% 0,100% 50%,50% 100%,0 50%)`
+- **Color**: Accent (e.g., `#4dd6e8` cyan)
+
+#### Cluster Pill
+- Content: Cluster name + green health dot
+- Health dot:
+  - Color: `#4ad07a`
+  - `box-shadow: 0 0 8px #4ad07a` (glow effect)
+- Optional: Click to switch clusters (multi-cluster support)
+
+#### Krate Count Pill
+- Only shown when krates exist
+- Content: `N krates` or similar
+- Accent-colored
+
+### Right Side
+
+#### Synced Pill
+- Content: `synced` text + pulsing accent dot
+- Dots color: `#4dd6e8` (cyan)
+- Animation:
+  - Opacity: 50% at 50%
+  - Duration: `1.6s`
+  - Easing: `ease-in-out infinite`
+- Visual indicator of WebSocket connection status
+
+#### Admin Button
+- Content: `◉ admin`
+- Active state: Accent-outlined (e.g., cyan border)
+- Inactive state: Muted (gray, subtle)
+- Toggle: Opens/closes admin drawer
+
+#### Roster Avatars
+- Overlapping circles: `margin-left: -7px`
+- Size: 30×30px
+- Color: Per-user (from palette)
+- Content: 2-letter initials
+- **Self indicator**: `★` (star) instead of initials
+- Interactive: Click to jump to user's krate (admin mode)
+
+## Admin Drawer Trigger
+
+### Button Position
+- Rightmost interactive element
+- Click to slide in right-side panel
+
+### Drawer Features
+- Width: 380px
+- Position: `absolute; right: 0; z-index: 56`
+- Backdrop: `rgba(7,9,13,.4)` (click to close)
+- Background: `rgba(13,17,24,.98); border-left: 1px solid rgba(140,165,200,.2)`
+
+### User Card Content
+For each connected user:
+- Avatar circle + name
+- Status: `active · namespace` or `idle Nm`
+- Current search query + "typing…" indicator (if spotlight open)
+- Krate count
+- Clickable krate rows: name + view badges + status dot
+- **Spectate**: Click user's krate to fly camera to it
+
+### Self User
+- Shows real-time state
+- Displays current spotlight query
+- Lists actual open krates
+- Updates live as user interacts
+
+## Keyboard Shortcuts
+
+| Key | Context | Action |
+|---|---|---|
+| None (top bar is static UI) | - | - |
+
+## State Management
+
+### Top Bar References
+```
+- clusterName: string
+- clusterHealthy: boolean
+- krateCount: number
+- users: User[]
+- currentUser: User
+- adminOpen: boolean
+```
+
+### User Object
+```typescript
+interface User {
+  id: string;
+  name: string;
+  color: string;
+  initials: string;
+  self: boolean;
+  status: 'active' | 'idle';
+  namespace?: string;
+  idleMinutes?: number;
+  query?: string;
+  krateIds: string[];
+}
+```
+
+## Gotchas
+1. **Admin presence**: Requires CRDT awareness or WebSocket presence channel
+2. **Roster overflow**: Handle many users gracefully (scroll or truncate with `+N`)
+3. **Self identification**: Mark current user with star `★`, not just initials
+4. **Health dot**: Use shadow for glow, not just color
+5. **Synced animation**: CSS keyframe or React state toggle every 800ms