hyperclaw 5.0.0 → 5.0.2

package/README.md

@@ -1,40 +1,55 @@
-<p align="center">
-  <img src="assets/icon.png" width="120" alt="HyperClaw">
-  <br>
-  <h1 align="center">🦅 HyperClaw — Personal AI Assistant</h1>
-</p>
+<div align="center">
+  <img src="assets/icon.png" width="140" alt="HyperClaw">
+  <h1>🦅 HyperClaw</h1>
+  <p><strong>Your personal AI assistant — running on your hardware, talking on your channels.</strong></p>
+  <p><em>One command to install. Works on Telegram, Discord, WhatsApp, Signal, iMessage and 25+ more.</em></p>
+</div>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" alt="build">
-  <img src="https://img.shields.io/badge/release-v5.0.0-blue?style=flat-square" alt="release">
-  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square" alt="node">
-  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <a href="https://github.com/mylo-2001/hyperclaw/stargazers"><img src="https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=flat-square&logo=github&color=yellow" alt="GitHub Stars"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/network/members"><img src="https://img.shields.io/github/forks/mylo-2001/hyperclaw?style=flat-square&logo=github" alt="GitHub Forks"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/dw/hyperclaw?style=flat-square&logo=npm&color=red" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/v/hyperclaw?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/actions"><img src="https://img.shields.io/github/actions/workflow/status/mylo-2001/hyperclaw/secrets-scan.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square&logo=node.js" alt="node">
   <img src="https://img.shields.io/badge/typescript-5.4-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="typescript">
-  <img src="https://img.shields.io/badge/security-ethical%20hacking-red?style=flat-square&logo=hackthebox&logoColor=white" alt="security">
+  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <img src="https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue?style=flat-square" alt="platforms">
 </p>
 
 <p align="center">
-  <strong>HyperClaw</strong> is a personal AI assistant you run on your own devices.<br>
-  It answers you on the channels you already use — Telegram, Discord, WhatsApp, Slack, Signal, iMessage,<br>
-  Matrix, IRC, Mattermost, Google Chat, Microsoft Teams, Nostr, and more.<br>
-  It can speak and listen on macOS/iOS/Android, and render a live Canvas you control.<br>
-  The Gateway is just the control plane — the product is the assistant.
+  <a href="docs/README.md">📚 Docs</a> ·
+  <a href="docs/architecture.md">🏗 Architecture</a> ·
+  <a href="docs/configuration.md">⚙️ Config</a> ·
+  <a href="docs/security.md">🔒 Security</a> ·
+  <a href="docs/sandboxing.md">🐳 Sandboxing</a> ·
+  <a href="docs/tlon.md">🌊 Tlon</a> ·
+  <a href="docs/google-chat.md">💬 Google Chat</a> ·
+  <a href="CONTRIBUTING.md">🤝 Contributing</a>
 </p>
 
-<p align="center">
-  <em>If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.</em><br>
-  <em>Built for developers, security researchers, and power users who want full control.</em>
-</p>
+---
 
-<p align="center">
-  <a href="docs/README.md">Docs</a> ·
-  <a href="docs/architecture.md">Architecture</a> ·
-  <a href="docs/configuration.md">Configuration</a> ·
-  <a href="docs/security.md">Security</a> ·
-  <a href="docs/deployment.md">Docker</a> ·
-  <a href="docs/tailscale.md">Tailscale</a> ·
-  <a href="CONTRIBUTING.md">Contributing</a>
-</p>
+> **"One `npm install -g hyperclaw` and your AI is live on Telegram."**
+
+---
+
+## Why HyperClaw?
+
+| Feature | HyperClaw | Cloud assistants | Self-hosted alternatives |
+|---------|:---------:|:----------------:|:------------------------:|
+| Runs on your own hardware | ✅ | ❌ | ✅ |
+| No subscription / pay-per-token only | ✅ | ❌ | ✅ |
+| 28+ messaging channels built-in | ✅ | ❌ | ⚠️ few |
+| Windows native (no WSL) | ✅ | — | ❌ |
+| Config hot-reload (no restart) | ✅ | — | ❌ |
+| Built-in security audit (`--fix`) | ✅ | — | ❌ |
+| DM pairing / allowlist by default | ✅ | — | ⚠️ manual |
+| Voice (TTS + STT) | ✅ | ✅ | ⚠️ |
+| Docker sandbox for agent tools | ✅ | — | ⚠️ |
+| MCP (Model Context Protocol) | ✅ | ⚠️ | ⚠️ |
+| One-command wizard (`hyperclaw onboard`) | ✅ | — | ❌ |
+| OSINT / Ethical hacking mode (`hyperclaw osint`) | ✅ | ❌ | ❌ |
 
 ---
 
@@ -53,65 +68,55 @@
 
 ---
 
-## Install
+## 🚀 Get started in 60 seconds
 
-Runtime: Node ≥ 22. Runs **natively on Windows, macOS, and Linux** — no WSL2 required.
+**Requires Node ≥ 22.** Runs natively on Windows, macOS, and Linux — no WSL2 required.
 
 ```bash
+# Install
 npm install -g hyperclaw@latest
-# or: pnpm add -g hyperclaw@latest
 
-# First-time setup wizard
+# Run the interactive setup wizard
 hyperclaw onboard
-
-# Or install with daemon (auto-start on boot, full PC access)
+# Run the interactive setup wizard with deamon
 hyperclaw onboard --install-daemon
 ```
 
-## Uninstall
+The wizard walks you through: AI provider → model → channels → skills. Done.
 
 ```bash
-# Stop and remove daemon (if running)
-hyperclaw daemon uninstall
-
-# Remove the package
-npm uninstall -g hyperclaw
+# After setup, start your assistant
+hyperclaw daemon start
 
-# Remove config and data (optional)
-rm -rf ~/.hyperclaw
-```
+# Interactive terminal chat (multi-turn, streams responses)
+hyperclaw chat
 
-> **Windows users**: HyperClaw runs natively via Node.js. No WSL2, no admin rights needed.
-> The daemon uses **Task Scheduler** and runs as your user account with full desktop access.
+# Send a single message (non-interactive)
+hyperclaw agent --message "What can you do?"
 
-The wizard guides you step by step — provider, model, gateway, channels, and skills.
-Works on **macOS, Linux, and Windows** (native — no WSL2 required). Compatible with npm, pnpm, and bun.
+# Health check
+hyperclaw doctor
+```
 
----
+> **Windows**: No WSL2, no admin rights needed. The daemon uses Task Scheduler and runs as your account.
 
-## Quick start
+<details>
+<summary>More install options</summary>
 
 ```bash
-# 1. Run the onboarding wizard (first time)
-hyperclaw onboard
-
-# 2a. Start the gateway in foreground
-hyperclaw gateway --port 18789 --verbose
+# pnpm
+pnpm add -g hyperclaw@latest
 
-# 2b. Or run as a background daemon (auto-start on boot)
-hyperclaw daemon start
-
-# 3. Talk to your assistant
-hyperclaw agent --message "What can you do?"
-
-# 4. Security / bug bounty — run recon from your phone
-# Just message your Telegram bot: "search HackerOne for targets on acme.com"
+# Install with daemon (auto-start on boot + full PC access)
+hyperclaw onboard --install-daemon
 
-# 5. Check status
-hyperclaw doctor
+# Uninstall
+hyperclaw daemon uninstall
+npm uninstall -g hyperclaw
+rm -rf ~/.hyperclaw   # optional — removes config and data
 ```
 
-Upgrading? Run `hyperclaw doctor` to check and migrate.
+</details>
 
 ---
 
@@ -124,7 +129,7 @@ HyperClaw connects to the channels you already use (28+ channels):
 | ✈️ Telegram | ✅ Recommended | Bot API via @BotFather |
 | 🎮 Discord | ✅ Recommended | discord.js — full bot |
 | 🌐 WebChat | ✅ Built-in | Gateway WebSocket, no setup |
-| 🖥️ CLI / Terminal | ✅ Built-in | `hyperclaw agent` |
+| 🖥️ CLI / Terminal | ✅ Built-in | `hyperclaw chat` (interactive) · `hyperclaw agent -m "..."` (single) |
 | 📲 WhatsApp (Baileys) | ✅ Available | No Meta API — scan QR |
 | 📱 WhatsApp (Cloud API) | ✅ Available | Meta Business API |
 | 💼 Slack | ✅ Available | Bolt — Events API |
@@ -148,6 +153,7 @@ HyperClaw connects to the channels you already use (28+ channels):
 | 📧 Email | ✅ Available | SMTP + IMAP |
 | 🎙️ Voice Call | ✅ Available | Terminal voice session |
 | 🌐 Chrome Extension | ✅ Available | Browser sidebar |
+| 🌊 Tlon (Urbit Groups) | ✅ Available | Decentralized — see [docs/tlon.md](docs/tlon.md) |
 
 Twitch is also available via IRC over WebSocket.
 
@@ -183,18 +189,30 @@ Google Chat / Matrix / IRC / Mattermost / Teams / Nostr / WebChat
 
 ---
 
-## Providers
-
-HyperClaw supports any OpenAI-compatible API and Anthropic natively:
-
-| Provider | IDs |
-|----------|-----|
-| **Anthropic** | `anthropic` — Claude 4 Opus/Sonnet/Haiku |
-| **OpenRouter** | `openrouter` — 200+ models |
-| **OpenAI** | `openai` — GPT-4o, GPT-4.1 |
-| **xAI** | `xai` — Grok |
-| **Groq** | `groq` — Llama, Mixtral (fast) |
-| **Custom** | `custom` — any OpenAI-compatible endpoint |
+## AI Models
+
+HyperClaw supports 20+ providers. Pick one in the wizard or set `provider.providerId` in config:
+
+| Provider | ID | Notes |
+|----------|-----|-------|
+| **Anthropic** | `anthropic` | Claude Opus/Sonnet/Haiku — native streaming |
+| **Anthropic OAuth** | `anthropic-oauth` | Claude Code / Max subscription |
+| **OpenRouter** | `openrouter` | 200+ models — one key |
+| **OpenAI** | `openai` | GPT-4o, o3, o4-mini |
+| **Google** | `google` | Gemini 2.5 Pro, 2.0 Flash |
+| **xAI** | `xai` | Grok 3, Grok 3 Mini |
+| **Groq** | `groq` | Llama 3.3, Mixtral — fast inference |
+| **Mistral** | `mistral` | Mistral Large, Codestral |
+| **DeepSeek** | `deepseek` | DeepSeek V3, R1 reasoning |
+| **Perplexity** | `perplexity` | Sonar — search-augmented AI |
+| **Hugging Face** | `huggingface` | Open-source models |
+| **MiniMax** | `minimax` | MiniMax Text-01 |
+| **Qwen** | `qwen` | Alibaba Qwen 3, Qwen Max |
+| **Z.AI** | `zai` | GLM-4 models |
+| **Vercel AI Gateway** | `vercel-ai` | Multi-model proxy |
+| **Ollama** | `ollama` | Local models — `ollama serve` |
+| **LM Studio** | `lmstudio` | Local models — enable local server |
+| **Custom** | `custom` | Any OpenAI-compatible `/chat/completions` |
 
 ---
 
@@ -229,6 +247,47 @@ Or use OpenRouter (access to all models with one key):
 
 Full reference: [docs/configuration.md](docs/configuration.md)
 
+### Config hot reload
+
+The gateway watches `~/.hyperclaw/hyperclaw.json` and applies changes automatically — no restart needed for most settings:
+
+```json
+{
+  "gateway": {
+    "reload": { "mode": "hybrid", "debounceMs": 300 }
+  }
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `hybrid` _(default)_ | Hot-applies safe changes, auto-restarts for critical ones |
+| `hot` | Hot-applies only — warns when a restart is needed |
+| `restart` | Restarts on any change |
+| `off` | Disables file watching |
+
+### Reverse proxy / trustedProxies
+
+If you run behind Nginx, Caddy, or Cloudflare Tunnel, set `trustedProxies` so the gateway resolves the real client IP from `X-Forwarded-For`:
+
+```json
+{
+  "gateway": {
+    "trustedProxies": ["127.0.0.1", "10.0.0.0/8"]
+  }
+}
+```
+
+### DM scope isolation
+
+Isolate DM sessions per channel/peer (useful when multiple people share one gateway):
+
+```json
+{
+  "session": { "dmScope": "per-channel-peer" }
+}
+```
+
 ---
 
 ## Security defaults
@@ -242,7 +301,14 @@ HyperClaw connects to real messaging surfaces. Inbound DMs are treated as untrus
 - Set `dmPolicy: "open"` only if you want anyone to reach your assistant.
 - Non-main sessions (groups/channels) can run in Docker sandboxes: `agents.defaults.sandbox.mode: "non-main"`
 
-Run `hyperclaw doctor` to surface risky/misconfigured policies.
+Run the security audit regularly:
+
+```bash
+hyperclaw security audit           # standard scan
+hyperclaw security audit --deep    # live gateway probe
+hyperclaw security audit --fix     # auto-fix safe issues
+hyperclaw security audit --json    # machine-readable output
+```
 
 Full guide: [docs/security.md](docs/security.md)
 
@@ -251,7 +317,8 @@ Full guide: [docs/security.md](docs/security.md)
 ## Features
 
 - **Local-first Gateway** — single control plane for sessions, channels, tools, and events
-- **Multi-channel inbox** — 27+ channels, unified session model
+- **Config hot reload** — gateway watches `~/.hyperclaw/hyperclaw.json`, hot-applies changes (hybrid/hot/restart/off)
+- **Multi-channel inbox** — 28+ channels, unified session model
 - **Multi-agent routing** — route channels/accounts to isolated agent workspaces
 - **Extended thinking** — Claude extended thinking with `/think high` in chat
 - **Voice** — Talk Mode with ElevenLabs TTS + system TTS fallback
@@ -261,6 +328,7 @@ Full guide: [docs/security.md](docs/security.md)
 - **Auto-memory** — extracts facts from conversations automatically
 - **Skills** — bundled and workspace skills (reminders, translator, web search, etc.)
 - **Daemon mode** — launchd/systemd user service, auto-restart, `🩸` icon
+- **Update notifications** — notifies when a newer version is available on npm (non-blocking check at startup)
 - **MCP support** — Model Context Protocol server and client
 - **Docker** — sandboxed agent execution, browser tools with Puppeteer
 - **Tailscale** — Serve/Funnel for remote access without port forwarding
@@ -292,6 +360,134 @@ The Gateway alone delivers a great experience. Apps add extra features:
 
 ---
 
+## Development channels
+
+Three release channels, switch any time:
+
+```bash
+hyperclaw update --channel stable   # tagged releases (default)
+hyperclaw update --channel beta     # prereleases
+hyperclaw update --channel dev      # moving head of main
+```
+
+| Channel | npm dist-tag | Notes |
+|---------|-------------|-------|
+| `stable` | `latest` | Tagged releases — recommended |
+| `beta` | `beta` | Prerelease — new features, may have rough edges |
+| `dev` | `dev` | Latest main branch (when published) |
+
+---
+
+## Integrations (Skills & Tools)
+
+The agent has built-in tools for common integrations — no extra packages needed. Full reference: [docs/integrations.md](docs/integrations.md)
+
+### Core Tools
+
+| Tool | How to enable |
+|------|---------------|
+| **Weather** | Free — no key needed (Open-Meteo) |
+| **Image generation** | Set `OPENAI_API_KEY` (DALL-E 3) or `STABILITY_API_KEY` |
+| **GIF search** | Set `GIPHY_API_KEY` or `TENOR_API_KEY` |
+| **Spotify** | Set `SPOTIFY_CLIENT_ID` + `SPOTIFY_CLIENT_SECRET` + `SPOTIFY_REFRESH_TOKEN` |
+| **Home Assistant** | Set `HA_URL` + `HA_TOKEN` (long-lived access token) |
+| **GitHub** | Set `GITHUB_TOKEN` |
+| **Canvas** | Built-in — view at `http://localhost:18789/canvas` |
+| **Browser** | Built-in — enable `browser.enabled: true` |
+| **Gmail** | Set `GOOGLE_CREDENTIALS_PATH` + configure Pub/Sub |
+
+### Productivity
+
+| Tool | How to enable |
+|------|---------------|
+| **Apple Notes** | macOS only — built-in (requires Accessibility permissions) |
+| **Apple Reminders** | macOS only — built-in (requires Accessibility permissions) |
+| **Things 3** | macOS only — install Things 3, no extra config |
+| **Obsidian** | Install Local REST API plugin, set `OBSIDIAN_API_KEY` (and optionally `OBSIDIAN_PORT`, default 27123) |
+| **Bear Notes** | macOS only — install Bear, no extra config |
+| **Trello** | Set `TRELLO_API_KEY` + `TRELLO_TOKEN` (from trello.com/app-key) |
+
+### Music
+
+| Tool | How to enable |
+|------|---------------|
+| **Sonos** | Set `SONOS_IP` to your speaker's local IP address |
+| **Music search** | Free — no key needed (iTunes Search API) |
+
+### Smart Home
+
+| Tool | How to enable |
+|------|---------------|
+| **Philips Hue** | Set `HUE_BRIDGE_IP` + `HUE_USERNAME` (from bridge discovery) |
+| **8Sleep** | Set `EIGHTSLEEP_EMAIL` + `EIGHTSLEEP_PASSWORD` |
+
+### Security & Messaging
+
+| Tool | How to enable |
+|------|---------------|
+| **1Password** | Install `op` CLI, set `OP_SERVICE_ACCOUNT_TOKEN` |
+| **iMessage** | macOS only — built-in (requires Full Disk Access + Accessibility) |
+
+Example — ask the agent:
+```
+"What's the weather in Athens for the next 3 days?"
+"Generate an image of a space lobster"
+"Play some Daft Punk on Spotify"
+"Turn on the living room lights"      # Home Assistant or Philips Hue
+"List my open GitHub issues"
+"Add 'Buy milk' to my Reminders"
+"Create a note in Obsidian: Meeting notes..."
+"Add a card to my Trello board"
+"Set my 8Sleep to temperature 20 on the left side"
+"Get my GitHub password from 1Password"
+"Send an iMessage to +1234567890: I'll be late"
+"What's playing on my Sonos?"
+```
+
+---
+
+## Agent-to-Agent (sessions tools)
+
+When the gateway is running, the agent can communicate with other connected sessions:
+
+| Tool | Description |
+|------|-------------|
+| `sessions_list` | List all active sessions connected to the gateway |
+| `sessions_send` | Send a message to another session by session ID |
+| `sessions_history` | Get the chat transcript of a session (`"self"` for current) |
+
+Example — ask the agent:
+```
+"List all connected sessions and send a briefing to the first one"
+```
+
+---
+
+## Terminal chat (`hyperclaw chat`)
+
+Interactive multi-turn chat with the agent directly from your terminal:
+
+```bash
+hyperclaw chat                          # start a session
+hyperclaw chat --thinking high          # enable extended thinking
+hyperclaw chat --session my-session     # named session
+hyperclaw chat --model claude-opus-4-6  # override model
+```
+
+| Input | Action |
+|-------|--------|
+| Any text + Enter | Send message to agent |
+| `exit` / `quit` / `bye` | Quit the chat |
+| `/exit` / `/quit` / `/bye` | Quit the chat |
+| `Ctrl+C` | Quit the chat |
+| `/clear` | Clear conversation history |
+| `/model` | Show current model |
+| `/help` | Show available commands |
+
+Responses stream token-by-token as they are generated. The full conversation history is kept for the entire session (true multi-turn context).
+
+---
+
 ## Chat commands
 
 Send these in any connected channel (Telegram, Discord, Slack, etc.):
@@ -304,6 +500,91 @@ Send these in any connected channel (Telegram, Discord, Slack, etc.):
 | `/think <level>` | `off` · `low` · `medium` · `high` · `xhigh` |
 | `/verbose on\|off` | Verbose mode |
 | `/usage off\|tokens\|full` | Per-response usage footer |
+| `/restart` | Restart the gateway (owner-only in groups) |
+| `/activation mention\|always` | Group activation toggle |
+
+## SkillHub
+
+SkillHub is HyperClaw's skill registry. Full guide: [docs/skillhub.md](docs/skillhub.md)
+
+The agent can install skills on demand or you can install them via the wizard:
+
+```bash
+# Install a skill
+hyperclaw skills install web-search
+
+# List installed skills
+hyperclaw skills list
+```
+
+Featured skills: `web-search` · `file-manager` · `code-runner` · `github-tools` · `calendar-tools` · `summarizer`
+
+### Installing skills — 3 ways
+
+**Option 1 — tell the agent (easiest):**
+
+```
+You › Install the web-search skill
+You › Install this: https://clawhub.ai/user/skill-name
+```
+
+The agent automatically calls `install_skill_from_hub` — no commands needed.
+
+**Option 2 — `/skills` inside `hyperclaw chat`:**
+
+```
+You › /skills
+```
+
+Shows installed skills and how to add more:
+
+```
+  Installed skills:
+  • Web Search      (web-search)
+  • File Manager    (file-manager)
+
+  How to add a skill:
+  1. Tell the agent:  "Install the web-search skill"
+  2. Paste a link:    "Install this: https://clawhub.ai/user/skill-name"
+  3. CLI:             hyperclaw skill install <name>
+  4. Re-run wizard:   hyperclaw onboard
+```
+
+`/skills` also appears in `/help` and in the chat header when you open `hyperclaw chat`.
+
+**Option 3 — CLI:**
+
+```bash
+hyperclaw skill install web-search
+hyperclaw skills list
+```
+
+### Install from URL
+
+Give the agent a clawhub.ai link and it installs automatically:
+
+```
+"Install this skill: https://clawhub.ai/b0tresch/stealth-browser"
+```
+
+The agent calls `install_skill_from_hub` — fetches SKILL.md + extra files, writes them to `~/.hyperclaw/workspace/skills/`, and runs `npm install` if needed.
+
+### Self-writing skills
+
+The agent can create fully custom skills on demand:
+
+```
+"Create a skill that summarizes my daily Telegram messages"
+```
+
+`create_skill` supports:
+- **`content`** — SKILL.md instructions
+- **`files`** — JSON map of extra files (e.g. `{"scripts/run.js": "..."}`)
+- **`npmInstall: "true"`** — auto-runs `npm install` after writing files
+
+Skills are saved to `~/.hyperclaw/workspace/skills/{id}/` and loaded on the next message.
+
+---
 
 ## HyperClaw Bot commands
 
@@ -326,23 +607,6 @@ Control the gateway remotely via your Telegram or Discord bot (`hyperclaw bot st
 | `/security` | Security audit summary |
 | `/help` | List all commands |
 
-## Agent-to-Agent (session tools)
-
-When the gateway is running, the agent has access to session tools for agent-to-agent communication:
-
-| Tool | Description |
-|------|-------------|
-| `sessions_list` | List all active WebSocket sessions connected to the gateway |
-| `sessions_send` | Send a message to another session (by session ID) |
-| `sessions_history` | Get the chat transcript of a session (`"self"` for current) |
-
-Example — ask the agent to ping another session:
-```
-"List all connected sessions and send a hello to the first one"
-```
-
----
-
 ## From source
 
 ```bash
@@ -379,6 +643,18 @@ Sandbox image (no PC access, restricted tools):
 docker build -f Dockerfile.sandbox -t hyperclaw:sandbox .
 ```
 
+Or use **Docker Compose** for the full stack (gateway + browser sandbox):
+
+```bash
+# Copy and fill in your API keys
+cp env.example .env
+
+# Start gateway + sandbox
+docker compose --profile full up -d
+```
+
+See [`docker-compose.yml`](docker-compose.yml) and [`env.example`](env.example) for all options.
+
 ---
 
 ## Monorepo structure
@@ -398,7 +674,7 @@ hyperclaw/
 │   ├── media/              # Voice, TTS, STT, audio
 │   ├── routing/            # Session routing + multi-agent dispatch
 │   ├── security/           # Auth, sandboxing, DM policy
-│   └── …                  # (sdk, types, webhooks, logging, plugins…)
+│   └── …                   # (sdk, types, webhooks, logging, plugins…)
 ├── packages/
 │   ├── core/               # Inference engine, agent loop
 │   ├── gateway/            # Gateway package (standalone)
@@ -419,9 +695,83 @@ hyperclaw/
 
 ---
 
+## Documentation
+
+| Topic | File |
+|-------|------|
+| **Getting started** | [docs/README.md](docs/README.md) |
+| Architecture overview | [docs/architecture.md](docs/architecture.md) |
+| Configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Environment variables | [docs/environment.md](docs/environment.md) |
+| API keys guide | [docs/API-KEYS-README.md](docs/API-KEYS-README.md) |
+| OAuth providers | [docs/oauth-providers.md](docs/oauth-providers.md) |
+| **Integrations (all tools)** | [docs/integrations.md](docs/integrations.md) |
+| **SkillHub & custom skills** | [docs/skillhub.md](docs/skillhub.md) |
+| **Update notifications** | [docs/update-notifications.md](docs/update-notifications.md) |
+| **Security** | [docs/security.md](docs/security.md) · [SECURITY.md](SECURITY.md) |
+| Deployment / Docker | [docs/deployment.md](docs/deployment.md) |
+| Tailscale remote access | [docs/tailscale.md](docs/tailscale.md) |
+| Remote gateway setup | [docs/remote-gateway-setup.md](docs/remote-gateway-setup.md) |
+| Multi-agent routing | [docs/multi-agent.md](docs/multi-agent.md) |
+| Session management | [docs/session-management.md](docs/session-management.md) |
+| Sandboxing (Docker isolation) | [docs/sandboxing.md](docs/sandboxing.md) |
+| MCP (Model Context Protocol) | [docs/mcp.md](docs/mcp.md) |
+| OSINT / Ethical Hacking mode | [docs/osint.md](docs/osint.md) |
+| Voice / Talk Mode | [docs/voice.md](docs/voice.md) |
+| Canvas (A2UI) | [docs/canvas-a2ui.md](docs/canvas-a2ui.md) |
+| Browser control | [docs/browser.md](docs/browser.md) |
+| **Channel guides** | |
+| Telegram | [docs/telegram.md](docs/telegram.md) |
+| Discord | [docs/discord-setup.md](docs/discord-setup.md) |
+| WhatsApp | [docs/whatsapp.md](docs/whatsapp.md) |
+| Slack | [docs/slack.md](docs/slack.md) |
+| Google Chat | [docs/google-chat.md](docs/google-chat.md) |
+| Tlon (Urbit Groups) | [docs/tlon.md](docs/tlon.md) |
+| Matrix | [docs/matrix.md](docs/matrix.md) |
+| Zalo / Zalo Personal | [docs/zalo.md](docs/zalo.md) · [docs/zalo-personal.md](docs/zalo-personal.md) |
+| LINE | [docs/line.md](docs/line.md) |
+| Nostr | [docs/nostr.md](docs/nostr.md) |
+| Nextcloud Talk | [docs/nextcloud-talk.md](docs/nextcloud-talk.md) |
+| Microsoft Teams | [docs/msteams.md](docs/msteams.md) |
+| Twitch | [docs/twitch.md](docs/twitch.md) |
+| iMessage (BlueBubbles) | [docs/imessage-native.md](docs/imessage-native.md) |
+| **Apps** | |
+| Mobile & Desktop apps | [docs/mobile-desktop-apps.md](docs/mobile-desktop-apps.md) |
+| Mobile nodes (iOS/Android) | [docs/mobile-nodes.md](docs/mobile-nodes.md) |
+| macOS remote control | [docs/macos-remote-control.md](docs/macos-remote-control.md) |
+| **Help** | |
+| FAQ | [docs/faq.md](docs/faq.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Contributing | [docs/contributing.md](docs/contributing.md) |
+
+---
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome! 🤖
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome!
+
+Found a bug? [Open an issue](https://github.com/mylo-2001/hyperclaw/issues/new/choose).  
+Found a vulnerability? Email [securityhyperclaw.ai@gmail.com](mailto:securityhyperclaw.ai@gmail.com) — we respond within 48 h.
+
+---
+
+## Community
+
+| | |
+|--|--|
+| 💬 **Discussions** | [GitHub Discussions](https://github.com/mylo-2001/hyperclaw/discussions) — questions, ideas, show & tell |
+| 🐛 **Bug reports** | [GitHub Issues](https://github.com/mylo-2001/hyperclaw/issues) — templates for bugs & features |
+| 🔒 **Security** | [SECURITY.md](SECURITY.md) — responsible disclosure |
+
+---
+
+<div align="center">
+
+**If HyperClaw is useful to you, a ⭐ helps others find it.**
+
+[![Star on GitHub](https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=social)](https://github.com/mylo-2001/hyperclaw)
+
+</div>
 
 ---