add client docs, README, CHANGELOG

docs/overlay.md

@@ -0,0 +1,106 @@
+# Overlay
+
+> Status: Phase 2 — design draft.
+
+The VNOX overlay renders a HUD on top of running games and applications,
+showing voice channel state without alt-tabbing.
+
+---
+
+## What it shows
+
+- who is currently speaking (avatar / nickname + audio indicator)
+- your own mic state (active / muted / push-to-talk held)
+- current channel name
+- latency (RTT to node)
+- hotkey state hints
+
+---
+
+## Architecture
+
+The overlay is a separate process that communicates with the main VNOX client
+via a local IPC socket (Unix socket / named pipe).
+
+The client pushes state updates to the overlay:
+- user speaking events (`VOICE_STATE`)
+- channel changes
+- mute state changes
+
+The overlay renders on top of other applications.
+
+### Rendering approach
+
+| Platform | Method |
+|----------|--------|
+| Windows | DirectX overlay injection or transparent top-level window |
+| Linux (X11) | Shaped transparent window, always-on-top |
+| Linux (Wayland) | Layer shell protocol (wlr-layer-shell) |
+| macOS | CGWindow overlay |
+
+Implementation complexity varies significantly by platform.
+Windows DX injection is the most reliable for full-screen games.
+
+---
+
+## Game integrations
+
+For games that support it, the overlay can receive additional data:
+
+### Positional voice (Phase 4)
+
+Games that expose player position data can send it to VNOX,
+enabling positional audio — players hear each other based on
+in-game distance and direction.
+
+Integration methods:
+
+| Game / Engine | Method |
+|---------------|--------|
+| Minecraft | Fabric/Forge mod that sends position via local socket |
+| Source Engine | Client plugin / VScript |
+| Unreal Engine | Plugin exposing position to named pipe |
+| Unity | SDK that writes position to shared memory |
+
+Protocol for positional data is TBD (Phase 4 design).
+
+### Speaking indicators in-game
+
+Some games support custom HUD elements. Where possible, the overlay
+will render directly within the game's UI rather than as an external window.
+
+---
+
+## Configuration
+
+```toml
+[overlay]
+enabled = true
+
+# Overlay position on screen
+position = "top-right"   # top-left | top-right | bottom-left | bottom-right
+
+# Opacity (0.0–1.0)
+opacity = 0.85
+
+# Show latency
+show_latency = false
+
+# Hotkey to toggle overlay visibility
+toggle_hotkey = "ctrl+shift+o"
+```
+
+---
+
+## Hotkeys
+
+All hotkeys are global (work even when VNOX window is not focused).
+
+| Action | Default |
+|--------|---------|
+| Push-to-talk | `mouse4` |
+| Mute toggle | `ctrl+m` |
+| Deafen toggle | `ctrl+d` |
+| Toggle overlay | `ctrl+shift+o` |
+
+Configurable in Settings → Keybinds.