docs: update README, CHANGELOG, CLAUDE.md, AGENTS.md for Tier 3-4 features (xAI, Voyage AI, gateway lock, shell completion, tailscale serve, DM pairing, lane queue, credential redaction, usage dashboard)

README.md

@@ -5,9 +5,9 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces.
 ## Features
 
 - **Multi-Frontend**: Telegram bot + Terminal UI (minimal & fullscreen modes) + Web UI dashboard
-- **Multi-Model**: Anthropic Claude, OpenAI, GitHub Copilot, Gemini, Bedrock, Zhipu AI (GLM), Ollama, llama.cpp with intelligent routing
+- **Multi-Model**: Anthropic Claude, OpenAI, GitHub Copilot, Gemini, Bedrock, Zhipu AI (GLM), xAI (Grok), Ollama, llama.cpp with intelligent routing
 - **Multi-Channel**: Telegram, Discord, Slack, WhatsApp with unified adapter interface
-- **Web Dashboard**: SPA control panel with health monitoring, chat, session browser, and settings editor
+- **Web Dashboard**: SPA control panel with health monitoring, chat, session browser, usage stats, and settings editor
 - **Model Switching**: Switch between cloud/local models on demand
 - **Session Persistence**: SQLite-backed conversation history
 - **Fallback Chains**: Automatic failover when primary model fails
@@ -17,16 +17,21 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces.
 - **Multi-Agent Routing**: Config-driven agent selection per sender/channel with tool profiles
 - **Media Pipeline**: Image analysis, outbound attachments, audio transcription across all channels
 - **Session Transfer**: Move conversations between frontends
-- **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, etc.)
+- **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, `completion`, etc.)
+- **Shell Completion**: Auto-generated completions for bash, zsh, and fish with `--install` flag
 - **Cron Scheduling**: Automated messages on cron schedules with output routing
 - **Inbound Webhooks**: HTTP endpoints that trigger agent processing with HMAC auth and template rendering
 - **Heartbeat Monitor**: Periodic health checks (gateway, model, channels, memory, disk) with failure notifications
 - **Gmail Pub/Sub Watcher**: Monitor Gmail inbox via Google Cloud Pub/Sub push notifications with polling fallback
-- **Vector Memory Search**: Hybrid keyword + semantic search with embeddings (OpenAI, Gemini, Ollama, llama.cpp)
+- **Vector Memory Search**: Hybrid keyword + semantic search with embeddings (OpenAI, Gemini, Ollama, llama.cpp, Voyage AI)
 - **Docker Deployment**: Multi-stage Dockerfile and docker-compose.yml for production containers
 - **Health Diagnostics**: `flynn doctor` validates config, connectivity, and system state
 - **MCP Integration**: External tool servers via Model Context Protocol
 - **Skills System**: Extensible capability packages (bundled, managed, workspace tiers)
+- **Gateway Lock**: Single-client mode — reject additional WebSocket connections when one is active
+- **Tailscale Serve**: Auto-expose gateway via Tailscale Serve on daemon start with lifecycle management
+- **DM Pairing Codes**: Allow unknown senders to pair with the bot via time-limited codes across all channels
+- **Lane Queue**: Per-session FIFO queue serializes concurrent gateway requests
 
 ## Quick Start
 
@@ -58,6 +63,7 @@ Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts`
 | `flynn sessions` | List active sessions |
 | `flynn doctor` | Validate config and check system health |
 | `flynn config` | Show resolved configuration (secrets redacted) |
+| `flynn completion <shell>` | Generate shell completions (bash, zsh, fish) |
 
 ### Examples
 
@@ -76,6 +82,11 @@ flynn config
 
 # List sessions
 flynn sessions
+
+# Generate shell completions
+flynn completion bash              # Print bash completions to stdout
+flynn completion zsh --install     # Install zsh completions to ~/.zshrc
+flynn completion fish --install    # Install fish completions to config
 ```
 
 ## Configuration
@@ -114,6 +125,7 @@ hooks:
 | Bedrock | `provider: bedrock`, AWS credentials |
 | Ollama | `provider: ollama`, `model`, optional `endpoint` |
 | Zhipu AI (GLM) | `provider: zhipuai`, `api_key` or `ZHIPUAI_API_KEY`, optional `endpoint` |
+| xAI (Grok) | `provider: xai`, `api_key` or `XAI_API_KEY` |
 | llama.cpp | `provider: llamacpp`, `endpoint` |
 
 ### Model Tiers
@@ -150,6 +162,7 @@ Flynn includes a built-in web control dashboard served by the WebSocket gateway.
 | **Dashboard** | System health cards, channel status, usage stats. Auto-refreshes every 10s |
 | **Chat** | Session selector, streaming tool events, markdown rendering with syntax highlighting |
 | **Sessions** | Browse all sessions, view message history, delete sessions |
+| **Usage** | Token usage summary cards, per-session breakdown table, auto-refresh |
 | **Settings** | Edit hook patterns (confirm/log/silent), view tools, channels, and redacted config |
 
 The dashboard is a vanilla JS SPA with no build step — hash-based routing, ES modules, and the existing WebSocket JSON-RPC protocol.
@@ -171,6 +184,13 @@ pnpm tui:fs
 | `/help` | Show help |
 | `/reset` | Clear history |
 | `/status` | Show session info |
+| `/compact` | Compact conversation context |
+| `/usage` | Show token usage and cost |
+| `/verbose` | Toggle verbose output mode |
+| `/local` | Switch to local model |
+| `/cloud` | Switch to cloud model |
+| `/model` | Show model info and options |
+| `/pair` | Generate/list/revoke DM pairing codes |
 | `/fullscreen` | Switch to fullscreen mode |
 | `/transfer telegram` | Transfer session to Telegram |
 | `/quit` | Exit |
@@ -425,6 +445,7 @@ memory:
 | Gemini | `provider: gemini`, `api_key`, `model` |
 | Ollama | `provider: ollama`, `endpoint` (default: localhost:11434), `model` |
 | llama.cpp | `provider: llamacpp`, `endpoint`, optional `model` |
+| Voyage AI | `provider: voyageai`, `api_key` or `VOYAGE_API_KEY`, `model` (default: `voyage-3-large`) |
 
 Embeddings are indexed in the background — when memory is written, the namespace is marked dirty and re-indexed within 30 seconds. The vector index is stored in `vectors.db` alongside the session database.
 
@@ -438,13 +459,88 @@ When embeddings are disabled or the provider is unreachable, search falls back g
 | `provider` | no | Embedding provider (default: `openai`) |
 | `model` | no | Embedding model name (default: `text-embedding-3-small`) |
 | `endpoint` | no | Provider endpoint (required for `ollama`/`llamacpp`) |
-| `api_key` | no | API key (required for `openai`/`gemini`) |
+| `api_key` | no | API key (required for `openai`/`gemini`/`voyageai`) |
 | `dimensions` | no | Vector dimensions (auto-detected from model if not set) |
 | `chunk_size` | no | Max tokens per chunk (default: `512`) |
 | `chunk_overlap` | no | Token overlap between chunks (default: `50`) |
 | `top_k` | no | Number of vector results to return (default: `5`) |
 | `hybrid_weight` | no | Vector vs keyword weight, 0.0-1.0 (default: `0.7`) |
 
+## Gateway Lock
+
+Single-client mode for the WebSocket gateway. When enabled, only one WebSocket connection is allowed at a time. Additional connections are rejected with close code `4003`.
+
+```yaml
+server:
+  lock: true
+```
+
+The web UI detects the locked state and disables auto-reconnect when rejected.
+
+## Tailscale Serve
+
+Automatically expose the gateway via Tailscale Serve when the daemon starts. Requires Tailscale to be installed and authenticated on the host.
+
+```yaml
+server:
+  tailscale:
+    serve: true
+```
+
+When enabled, Flynn runs `tailscale serve` on startup to expose the gateway port over your tailnet, and cleans up on shutdown. The `flynn doctor` command includes a Tailscale availability check.
+
+## DM Pairing Codes
+
+Allow unknown senders to authenticate with the bot via time-limited pairing codes. Works across all channel adapters (Telegram, Discord, Slack, WhatsApp).
+
+```yaml
+pairing:
+  enabled: true
+  code_ttl: "10m"       # Code expiry time (default: 10 minutes)
+  code_length: 6        # Code length (default: 6 digits)
+```
+
+### How it works
+
+1. Generate a code via the TUI (`/pair generate`), gateway API (`pairing.generate`), or web dashboard
+2. Share the code with the user
+3. The user sends the code as their first DM to the bot
+4. If valid, the user's sender ID is permanently approved for that channel
+5. Approved users can be listed (`/pair list`) and revoked (`/pair revoke <channel> <id>`)
+
+### TUI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/pair` | Generate a new pairing code |
+| `/pair generate [label]` | Generate a code with optional label |
+| `/pair list` | List pending codes and approved senders |
+| `/pair revoke <channel> <id>` | Revoke an approved sender |
+
+### Gateway API
+
+| Method | Description |
+|--------|-------------|
+| `pairing.generate` | Generate a new pairing code (optional `label` param) |
+| `pairing.list` | List pending codes and approved senders |
+| `pairing.revoke` | Revoke an approved sender (`channel` + `senderId` params) |
+
+## Shell Completion
+
+Generate shell completions for bash, zsh, or fish:
+
+```bash
+# Print completions to stdout
+flynn completion bash
+flynn completion zsh
+flynn completion fish
+
+# Install directly to shell config
+flynn completion bash --install    # Appends to ~/.bashrc
+flynn completion zsh --install     # Appends to ~/.zshrc
+flynn completion fish --install    # Writes to ~/.config/fish/completions/flynn.fish
+```
+
 ## Docker Deployment
 
 Flynn includes a production-ready Dockerfile with multi-stage build.
@@ -549,7 +645,9 @@ src/
 ├── auth/                 # OAuth flows (GitHub Copilot)
 ├── backends/native/      # Agent implementation + orchestrator
 ├── channels/             # Channel adapters (Telegram, Discord, Slack, WhatsApp, WebChat)
+│   └── pairing.ts        # DM pairing code manager
 ├── cli/                  # CLI commands (commander)
+│   └── completion.ts     # Shell completion generator (bash/zsh/fish)
 ├── config/               # YAML config + Zod validation
 ├── context/              # Token estimation + compaction
 ├── daemon/               # Lifecycle management + routing
@@ -557,9 +655,11 @@ src/
 │   ├── telegram/         # Telegram bot
 │   └── tui/              # Terminal UI (minimal + fullscreen)
 ├── gateway/              # WebSocket gateway + web UI dashboard
-│   ├── handlers/         # JSON-RPC method handlers
+│   ├── handlers/         # JSON-RPC method handlers (agent, sessions, system, pairing, tools, config)
+│   ├── tailscale.ts      # Tailscale Serve lifecycle management
+│   ├── lane-queue.ts     # Per-session FIFO request queue
 │   └── ui/               # SPA dashboard (vanilla JS)
-│       ├── pages/        # Dashboard, Chat, Sessions, Settings
+│       ├── pages/        # Dashboard, Chat, Sessions, Usage, Settings
 │       └── lib/          # WebSocket RPC client
 ├── hooks/                # Confirmation engine
 ├── mcp/                  # MCP tool server integration