Merge branch 'main' into feat/add-unit-testing

docs/terminal.md

@@ -0,0 +1,93 @@
+# Terminal
+
+The integrated terminal provides a full-featured terminal emulator within Automaker, powered by xterm.js.
+
+## Configuration
+
+Configure the terminal via environment variables in `apps/server/.env`:
+
+### Disable Terminal Completely
+```
+TERMINAL_ENABLED=false
+```
+Set to `false` to completely disable the terminal feature.
+
+### Password Protection
+```
+TERMINAL_PASSWORD=yourpassword
+```
+By default, the terminal is **not password protected**. Add this variable to require a password.
+
+When password protection is enabled:
+- Enter the password in **Settings > Terminal** to unlock
+- The terminal remains unlocked for the session
+- You can toggle password requirement on/off in settings after unlocking
+
+## Keyboard Shortcuts
+
+When the terminal is focused, the following shortcuts are available:
+
+| Shortcut | Action |
+|----------|--------|
+| `Alt+D` | Split terminal right (horizontal split) |
+| `Alt+S` | Split terminal down (vertical split) |
+| `Alt+W` | Close current terminal |
+
+Global shortcut (works anywhere in the app):
+| Shortcut | Action |
+|----------|--------|
+| `Cmd+`` (Mac) / `Ctrl+`` (Windows/Linux) | Toggle terminal view |
+
+## Features
+
+### Multiple Terminals
+- Create multiple terminal tabs using the `+` button
+- Split terminals horizontally or vertically within a tab
+- Drag terminals to rearrange them
+
+### Theming
+The terminal automatically matches your app theme. Supported themes include:
+- Light / Dark / System
+- Retro, Dracula, Nord, Monokai
+- Tokyo Night, Solarized, Gruvbox
+- Catppuccin, One Dark, Synthwave, Red
+
+### Font Size
+- Use the zoom controls (`+`/`-` buttons) in each terminal panel
+- Or use `Cmd/Ctrl + Scroll` to zoom
+
+### Scrollback
+- The terminal maintains a scrollback buffer of recent output
+- Scroll up to view previous output
+- Output is preserved when reconnecting
+
+## Architecture
+
+The terminal uses a client-server architecture:
+
+1. **Frontend** (`apps/app`): xterm.js terminal emulator with WebGL rendering
+2. **Backend** (`apps/server`): node-pty for PTY (pseudo-terminal) sessions
+
+Communication happens over WebSocket for real-time bidirectional data flow.
+
+### Shell Detection
+
+The server automatically detects the best shell:
+- **WSL**: User's shell or `/bin/bash`
+- **macOS**: User's shell, zsh, or bash
+- **Linux**: User's shell, bash, or sh
+- **Windows**: PowerShell 7, PowerShell, or cmd.exe
+
+## Troubleshooting
+
+### Terminal not connecting
+1. Ensure the server is running (`npm run dev:server`)
+2. Check that port 3008 is available
+3. Verify the terminal is unlocked
+
+### Slow performance with heavy output
+The terminal throttles output at ~60fps to prevent UI lockup. Very fast output (like `cat` on large files) will be batched.
+
+### Shortcuts not working
+- Ensure the terminal is focused (click inside it)
+- Some system shortcuts may conflict (especially Alt+Shift combinations on Windows)