docs: mark Wave 2 tasks complete, update file structure and design decisions

docs/TASKS-TUI_Improvements.md

@@ -20,14 +20,14 @@
 | TUI-007b | Wire token usage, model info, thinking levels end-to-end (gateway → types → TUI)                      | ✅ done | a061a64 |
 | TUI-007c | Ctrl+T to cycle thinking levels via `set:thinking` socket event                                       | ✅ done | a061a64 |
 
-## Wave 2 — Layout & Navigation (next)
+## Wave 2 — Layout & Navigation ✅
 
-| ID      | Task                                                      | Status      | Notes            |
-| ------- | --------------------------------------------------------- | ----------- | ---------------- |
-| TUI-008 | Conversation sidebar — list, create, switch conversations | not-started | Depends: TUI-001 |
-| TUI-009 | Keybinding system — Ctrl+N, Ctrl+L, Ctrl+K                | not-started | Depends: TUI-008 |
-| TUI-010 | Scrollable message history — viewport with PgUp/PgDn      | not-started | Depends: TUI-001 |
-| TUI-011 | Message search — find in current conversation             | not-started | Depends: TUI-010 |
+| ID      | Task                                                      | Status  | Notes   |
+| ------- | --------------------------------------------------------- | ------- | ------- |
+| TUI-010 | Scrollable message history — viewport with PgUp/PgDn      | ✅ done | 4d4ad38 |
+| TUI-008 | Conversation sidebar — list, create, switch conversations | ✅ done | 9ef578c |
+| TUI-009 | Keybinding system — Ctrl+L, Ctrl+N, Ctrl+K, Escape        | ✅ done | 9f38f5a |
+| TUI-011 | Message search — find in current conversation             | ✅ done | 8627827 |
 
 ## Wave 3 — Advanced Features
 
@@ -46,15 +46,21 @@
 
 ```
 packages/cli/src/tui/
-├── app.tsx                          ← Thin shell composing all components
+├── app.tsx                          ← Shell composing all components + global keybindings
 ├── components/
 │   ├── top-bar.tsx                  ← Mosaic icon + version + model + connection
-│   ├── bottom-bar.tsx               ← 3-line footer: gateway, cwd+session, tokens+model
-│   ├── message-list.tsx             ← Messages, tool calls, thinking, streaming
-│   └── input-bar.tsx                ← Bordered prompt with context-aware placeholder
+│   ├── bottom-bar.tsx               ← Keybinding hints + 3-line footer: gateway, cwd, tokens
+│   ├── message-list.tsx             ← Messages, tool calls, thinking, streaming, search highlights
+│   ├── input-bar.tsx                ← Bordered prompt with context-aware placeholder
+│   ├── sidebar.tsx                  ← Conversation list with keyboard navigation
+│   └── search-bar.tsx               ← Message search input with match count + navigation
 └── hooks/
-    ├── use-socket.ts                ← Typed Socket.IO (all ServerToClient/ClientToServer events)
-    └── use-git-info.ts              ← Reads cwd + git branch at startup
+    ├── use-socket.ts                ← Typed Socket.IO + switchConversation/clearMessages
+    ├── use-git-info.ts              ← Reads cwd + git branch at startup
+    ├── use-viewport.ts              ← Scrollable viewport with auto-follow + PgUp/PgDn
+    ├── use-app-mode.ts              ← Panel focus state machine (chat/sidebar/search)
+    ├── use-conversations.ts         ← REST client for conversation CRUD
+    └── use-search.ts                ← Message search with match cycling
 ```
 
 ### Cross-Package Changes
@@ -64,12 +70,23 @@ packages/cli/src/tui/
 
 ### Key Design Decisions
 
+#### Wave 1
+
 - Footer is 3 lines: (1) gateway status right-aligned, (2) cwd+branch left / session right, (3) tokens left / provider+model+thinking right
 - Mosaic icon uses brand colors in windmill cross pattern with `GAP` const to prevent prettier collapsing spaces
 - `flexGrow={1}` on header text column prevents re-render artifacts
 - Token/model data comes from gateway via `agent:end` payload and `session:info` events
 - Thinking level cycling via Ctrl+T sends `set:thinking` to gateway, which validates and responds with `session:info`
 
+#### Wave 2
+
+- `useViewport` calculates scroll offset from terminal rows; auto-follow snaps to bottom on new messages
+- `useAppMode` state machine manages focus: only the active panel handles keyboard input via `useInput({ isActive })`
+- Sidebar fetches conversations via REST (`GET /api/conversations`), not socket events
+- `switchConversation` in `useSocket` clears all local state (messages, streaming, tool calls)
+- Search uses `useMemo` for reactive match computation; viewport auto-scrolls to current match
+- Keybinding hints shown in bottom bar: `^L sidebar · ^N new · ^K search · ^T thinking · PgUp/Dn scroll`
+
 ### How to Run
 
 ```bash