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/backend.md

@@ -13,16 +13,16 @@ The Headquarter backend is built with **FastAPI** and follows a layered architec
 │  Middleware: CORS → Request Logging → Exception Logging      │
 ├─────────────────────────────────────────────────────────────┤
 │  API Layer (src/api/)                                        │
-│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐          │
-│  │  Auth   │ │ Projects │ │ Users  │ │   Git    │          │
-│  │ Routes  │ │ Routes   │ │ Routes │ │ Repos    │          │
-│  └────┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘          │
-├───────┼───────────┼───────────┼───────────┼─────────────────┤
-│       │           │           │           │                  │
-│  Auth │  Project  │   User    │   Git     │                  │
-│ Layer │  Service  │  Service  │ Service   │                  │
-│       │           │           │           │                  │
-├───────┴───────────┴───────────┴───────────┴─────────────────┤
+│  ┌─────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐           │
+│  │  Auth   │ │Terminal │ │Projects│ │   Git    │           │
+│  │ Routes  │ │   WS    │ │ Routes │ │ Repos    │           │
+│  └────┬────┘ └────┬────┘ └───┬────┘ └────┬─────┘           │
+├───────┼───────────┼──────────┼───────────┼──────────────────┤
+│       │           │          │           │                  │
+│  Auth │  Terminal │ Project  │   Git     │                  │
+│ Layer │  Manager  │ Service  │ Service   │                  │
+│       │  + Session│          │           │                  │
+├───────┴───────────┴──────────┴───────────┴──────────────────┤
 │  Data Layer                                                  │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
 │  │  Models  │  │ Database │  │   Config │                   │
@@ -37,6 +37,7 @@ The Headquarter backend is built with **FastAPI** and follows a layered architec
 src/
 ├── api/                    # API Routes
 │   ├── auth.py            # Authentication endpoints
+│   ├── terminal.py        # WebSocket terminal endpoint
 │   ├── projects.py        # Project endpoints
 │   ├── git_repositories.py # Repository endpoints
 │   ├── users.py           # User endpoints
@@ -55,6 +56,11 @@ src/
 │   ├── tool_type.py       # Tool type model
 │   ├── ssh_key.py         # SSH key model
 │   └── user_config.py     # User config model
+├── services/              # Business Logic
+│   ├── terminal_manager.py # Terminal session manager
+│   ├── terminal_session.py # PTY + docker exec session
+│   ├── docker.py          # Docker operations
+│   └── profile_resolver.py # Profile resolution
 ├── utils/                  # Utilities
 │   ├── git_url_parser.py  # URL parsing
 │   ├── git_files.py       # Git file operations
@@ -64,6 +70,65 @@ src/
 └── main.py                # Application entry point
 ```
 
+## Terminal System
+
+The terminal system provides interactive shell access to running tool instances via WebSocket.
+
+### Architecture
+
+```
+Client (WebSocket)
+  ↕
+terminal.py (FastAPI WS endpoint)
+  ├─ Auth validation (session cookie)
+  ├─ Instance ownership check
+  ├─ Session lifecycle (create / monitor / cleanup)
+  └─ Echo state detection (termios)
+  ↕
+TerminalManager
+  ├─ create_session() → spawns TerminalSession
+  ├─ _read_loop() → batches PTY output → WebSocket
+  ├─ _write_loop() → WebSocket input → PTY
+  └─ _heartbeat_loop() → closes idle connections (60s)
+  ↕
+TerminalSession
+  ├─ start() → pty.openpty() + docker exec
+  ├─ read_output() → select.select() + os.read()
+  ├─ write_input() → os.write() to PTY master
+  ├─ resize() → TIOCSWINSZ ioctl
+  └─ check_echo_state() → termios.ECHO flag
+```
+
+### Protocol
+
+**Binary frames**: Raw terminal I/O (hot path)
+**Text (JSON) frames**: Control messages
+
+**Control messages:**
+
+| Direction | Type | Purpose |
+|-----------|------|---------|
+| Client → Server | `ping` | Heartbeat (every 15s idle) |
+| Server → Client | `pong` | Heartbeat response |
+| Client → Server | `resize` | Terminal dimensions changed |
+| Server → Client | `set_echo_state` | Enable/disable local echo |
+| Server → Client | `session_ended` | Container process exited |
+
+### Message Batching
+
+The read loop batches small PTY reads into single WebSocket frames:
+- Buffer accumulates data for up to 16ms
+- Flushed immediately when no new data is available
+- Reduces WebSocket frame overhead for rapid output
+
+### Reconnect Behavior
+
+The server cannot resume a `docker exec` PTY across connections. On reconnect:
+1. Old session is terminated
+2. New `docker exec` is spawned
+3. Client restores scrollback from `sessionStorage`
+4. New shell appears seamlessly to the user
+
 ## Layers
 
 ### 1. API Layer (`src/api/`)