docs: add comprehensive JSDoc comments to TUI components

Improves documentation across all TUI files:
- App.tsx: Main component with keyboard shortcuts reference
- index.tsx: Entry point with usage examples
- useSessionManager.ts: Hook with detailed API documentation
- All components: Props, returns, and behavior descriptions
- Helper functions: Parameter and return type documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/tui/index.tsx

@@ -1,9 +1,27 @@
 /**
  * @fileoverview TUI entry point for Claudeman
  *
- * Renders the terminal user interface using Ink (React for CLI).
- * This provides a full-screen TUI similar to the web interface,
- * with tabs for sessions and real-time terminal output.
+ * Entry point for the terminal user interface, providing a full-screen
+ * session manager similar to the web interface but entirely in the terminal.
+ *
+ * @description
+ * Built with Ink (React for CLI), the TUI offers:
+ * - Session discovery from ~/.claudeman/screens.json
+ * - Tab-based session navigation (like browser tabs)
+ * - Real-time terminal output via screen hardcopy polling
+ * - Ralph Wiggum loop tracking
+ * - Respawn status monitoring
+ *
+ * @example
+ * ```bash
+ * # Start the TUI
+ * claudeman tui
+ * # Or via npm
+ * npm run tui
+ * ```
+ *
+ * @see {@link ./App.tsx} for main application component
+ * @see {@link ./hooks/useSessionManager.ts} for state management
  */
 
 import React from 'react';
@@ -11,7 +29,13 @@ import { render } from 'ink';
 import { App } from './App.js';
 
 /**
- * Checks if the terminal supports raw mode (required for TUI)
+ * Checks if the terminal supports raw mode input.
+ *
+ * @description
+ * Raw mode is required for Ink to capture keyboard input directly.
+ * This check fails when stdin is piped or redirected (e.g., `echo | claudeman tui`).
+ *
+ * @returns true if raw mode is available, false otherwise
  */
 function isRawModeSupported(): boolean {
   return Boolean(
@@ -21,8 +45,15 @@ function isRawModeSupported(): boolean {
 }
 
 /**
- * Starts the TUI application
- * @returns Promise that resolves when the app exits
+ * Starts the TUI application in the current terminal.
+ *
+ * @description
+ * Initializes the Ink renderer and displays the TUI.
+ * The terminal is cleared for a full-screen experience.
+ * This function blocks until the user exits the TUI.
+ *
+ * @throws Exits with code 1 if TTY/raw mode is not supported
+ * @returns Promise that resolves when the TUI exits
  */
 export async function startTUI(): Promise<void> {
   // Check if we're in an interactive terminal