docs: add responsive terminal documentation

- Add docs/features/terminal.md with user guide, connection states,
  keyboard shortcuts, protocol details, and troubleshooting
- Update docs/architecture/frontend.md with terminal component stack,
  connection hook behavior, and data flow diagrams
- Update docs/architecture/backend.md with terminal system architecture,
  protocol reference, message batching, and reconnect behavior
- Update docs/README.md to include terminal in feature list

docs/architecture/frontend.md

@@ -26,22 +26,26 @@ apps/web/src/
 │   ├── ssh_keys.ts      # SSH key API
 │   ├── tool_types.ts    # Tool type API
 │   ├── users.ts         # User API
+│   ├── sessions.ts      # Tool instance sessions API
 │   └── settings.ts      # Settings API
 ├── components/           # Reusable components
 │   ├── app-shell.tsx    # Main app layout
+│   ├── terminal.tsx     # xterm.js terminal component
 │   ├── protected-route.tsx  # Auth guard
 │   └── [more...]
 ├── context/             # React contexts
 │   └── auth.tsx         # Auth state management
 ├── hooks/               # Custom hooks
 │   ├── use-auth.ts      # Auth hook
-│   └── use-theme.ts     # Theme hook
+│   ├── use-theme.ts     # Theme hook
+│   └── use-terminal-connection.ts  # Terminal WebSocket lifecycle
 ├── pages/               # Page components (routes)
 │   ├── dashboard.tsx    # Dashboard
 │   ├── projects.tsx     # Project list
 │   ├── repo-workspace.tsx   # Repository workspace
 │   ├── git-history.tsx  # Git history
 │   ├── git-repositories.tsx # Repository management
+│   ├── terminal.tsx     # Web terminal
 │   ├── profile.tsx      # User profile
 │   ├── settings.tsx     # User settings
 │   ├── tool-types.tsx   # Tool types
@@ -164,6 +168,7 @@ interface AuthState {
 <Route path="/projects/:projectId" element={<RepoWorkspace />} />
 <Route path="/projects/:projectId/repositories" element={<GitRepositories />} />
 <Route path="/projects/:projectId/repositories/:repoId/history" element={<GitHistory />} />
+<Route path="/terminal/:instanceId" element={<TerminalPage />} />
 <Route path="/profile" element={<ProfilePage />} />
 <Route path="/settings" element={<SettingsPage />} />
 <Route path="/ssh-keys" element={<SSHKeysPage />} />
@@ -269,12 +274,64 @@ test('renders file list', () => {
 4. **Caching**: Browser caches API responses (ETags)
 5. **Optimistic UI**: Immediate feedback before API response
 
+## Terminal Architecture
+
+The web terminal is the most complex component in the frontend. It bridges a browser-based terminal emulator with a server-side PTY session.
+
+### Component Stack
+
+```
+TerminalPage (route)
+└── TerminalComponent
+    ├── Status bar (connection state, latency, actions)
+    ├── Session-ended overlay (reconnect / go back)
+    ├── Reconnect banner (spinner + countdown)
+    └── xterm.js (terminal emulator)
+        ├── FitAddon (auto-resize to container)
+        ├── SerializeAddon (scrollback serialization)
+        └── WebLinksAddon (clickable URLs)
+```
+
+### Connection Hook
+
+`useTerminalConnection` manages the full WebSocket lifecycle:
+
+```
+CONNECTING
+  → onopen → CONNECTED → heartbeat every 15s
+  → onclose (unexpected) → RECONNECTING
+    → backoff: 1s → 2s → 4s → 8s → 16s → 30s max
+    → up to 10 attempts
+    → onopen → restore scrollback → CONNECTED
+  → onclose (expected) → DISCONNECTED
+```
+
+**Key behaviors:**
+- **Local echo**: Printable ASCII chars appear instantly; server echo is deduplicated
+- **Resize**: Debounced 200ms, throttled to 1 message per 500ms
+- **Scrollback**: Serialized to `sessionStorage` on disconnect, restored on reconnect
+- **Keyboard**: `Ctrl+Shift+R` triggers manual reconnect
+
+### Data Flow
+
+```
+User types 'a'
+  → xterm onData event
+  → useTerminalConnection.sendInput('a')
+  → local echo writes 'a' to xterm immediately
+  → WebSocket sends 'a' to server
+  → server PTY echoes 'a' back
+  → client receives 'a' via binary frame
+  → deduplicates against pending echo buffer
+  → (no-op if matched, or writes remaining chars)
+```
+
 ## Future Improvements
 
 - [ ] Add React Query for server state management
 - [ ] Implement virtual scrolling for large file trees
 - [ ] Add service worker for offline support
-- [ ] Implement real-time updates (WebSocket)
+- [x] Implement real-time updates (WebSocket) — Terminal done
 - [ ] Add error boundary components
 
 ## Development Workflow