neoagent 2.3.1-beta.11 → 2.3.1-beta.110

package/docs/configuration.md

@@ -1,51 +1,36 @@
 # Configuration
 
-NeoAgent keeps deployment secrets on the server. The default config file is `~/.neoagent/.env`; run `neoagent setup` to regenerate it interactively. You can move the runtime root by setting `NEOAGENT_HOME`.
+NeoAgent reads server config from `~/.neoagent/.env`. Run `neoagent setup` to generate or update it interactively. Set `NEOAGENT_HOME` to move the runtime root.
 
-AI provider credentials, OAuth client secrets, and deployment controls are not configured through the public web client. The Flutter UI can select providers and models, but the secrets stay in server-side environment variables or in the local NeoAgent database where the app explicitly stores channel settings.
+All AI provider credentials, OAuth client secrets, and deployment settings are server-side only — never sent to the client or exposed in the UI.
 
-## Core Variables
+## Minimal Config
 
-| Variable | Default | Description |
-|---|---:|---|
-| `PORT` | `3333` | HTTP port for the NeoAgent server. |
-| `PUBLIC_URL` | optional | Public base URL used for OAuth callbacks and external links. |
-| `SESSION_SECRET` | required | Random string for session signing. Generate one with `openssl rand -hex 32`. |
-| `NODE_ENV` | `production` | Set to `development` to enable verbose logs. |
-| `SECURE_COOKIES` | `false` | Set `true` when NeoAgent is behind a TLS-terminating proxy. |
-| `TRUST_PROXY` | inferred from `PUBLIC_URL`/`SECURE_COOKIES` | Set `true` when NeoAgent runs behind Nginx, Caddy, Cloudflare, Fly, or another reverse proxy that sends `X-Forwarded-*` headers. |
-| `ALLOWED_ORIGINS` | none | Comma-separated CORS origins, for example `https://example.com`. |
-| `NEOAGENT_DEPLOYMENT_MODE` | `self_hosted` | `self_hosted` enables in-app update controls; `managed` hides operator-only controls for SaaS deployments. |
-| `NEOAGENT_RELEASE_CHANNEL` | `stable` | Release track used by the self-hosted updater. |
-
-## Service Email
+```dotenv
+PORT=3333
+SESSION_SECRET=change-me-to-something-random
+ANTHROPIC_API_KEY=sk-ant-...
+```
 
-Service email is optional. When `NEOAGENT_EMAIL_FROM` and `NEOAGENT_EMAIL_SMTP_HOST` are set, NeoAgent uses SMTP for account security flows: signup confirmation, password reset, unusual login notifications, password change notifications, and email change notifications. Confirmation and reset links use the same `PUBLIC_URL` base as the other server-generated links.
+Generate a session secret: `openssl rand -hex 32`
 
-This mailbox is only for the NeoAgent server. The agent cannot read, search, or send from it, and it is not exposed as a Gmail, Outlook, or messaging integration account. Configure Gmail/Outlook tools separately under official integrations if you want the agent to work with a mailbox.
+## Core Variables
 
 | Variable | Default | Description |
 |---|---:|---|
-| `NEOAGENT_EMAIL_REQUIRE_SIGNUP_CONFIRMATION` | `true` when enabled | Requires new signup email confirmation before sign-in. |
-| `NEOAGENT_EMAIL_REQUIRE_EMAIL_CHANGE_CONFIRMATION` | `true` when enabled | Requires account email changes to be confirmed by the new address. |
-| `NEOAGENT_EMAIL_NOTIFY_UNUSUAL_LOGIN` | `true` | Sends a security notice when a login uses a new device or network pattern. |
-| `NEOAGENT_EMAIL_NOTIFY_ACCOUNT_CHANGES` | `true` | Sends notices for password and email changes. |
-| `NEOAGENT_EMAIL_BRAND_NAME` | `NeoAgent` | Display name used by service email templates. |
-| `NEOAGENT_EMAIL_SUPPORT_URL` | optional | Optional operator support URL reserved for service email templates. |
-| `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | `24` | Confirmation link lifetime. |
-| `NEOAGENT_EMAIL_FROM` | required when enabled | Sender header, for example `NeoAgent <no-reply@example.com>`. |
-| `NEOAGENT_EMAIL_REPLY_TO` | optional | Reply-To header. |
-| `NEOAGENT_EMAIL_SMTP_HOST` | required when enabled | SMTP hostname. |
-| `NEOAGENT_EMAIL_SMTP_PORT` | `587` | SMTP port. |
-| `NEOAGENT_EMAIL_SMTP_SECURE` | `true` on port `465` | Use implicit TLS. |
-| `NEOAGENT_EMAIL_SMTP_REQUIRE_TLS` | `true` unless implicit TLS | Require STARTTLS for non-implicit-TLS SMTP. |
-| `NEOAGENT_EMAIL_SMTP_REJECT_UNAUTHORIZED` | `true` | Reject invalid TLS certificates. Keep enabled in production. |
-| `NEOAGENT_EMAIL_SMTP_USER` | optional | SMTP username. |
-| `NEOAGENT_EMAIL_SMTP_PASS` | optional | SMTP password or app password. |
+| `PORT` | `3333` | HTTP port for the NeoAgent server |
+| `PUBLIC_URL` | optional | Public base URL — required for OAuth callbacks, messaging webhooks, and mobile access |
+| `SESSION_SECRET` | required | Random string for session signing |
+| `NODE_ENV` | `production` | Set to `development` for verbose logs |
+| `SECURE_COOKIES` | `false` | Set `true` when behind a TLS-terminating proxy |
+| `TRUST_PROXY` | inferred | Set `true` when behind Nginx, Caddy, Cloudflare, Fly, or any proxy sending `X-Forwarded-*` |
+| `ALLOWED_ORIGINS` | none | Comma-separated CORS origins |
+| `NEOAGENT_DEPLOYMENT_MODE` | `self_hosted` | `managed` hides operator-only controls for SaaS deployments |
+| `NEOAGENT_RELEASE_CHANNEL` | `stable` | Release track followed by `neoagent update` |
 
 ## AI Providers
 
-At least one hosted-provider API key is required unless you only use local Ollama. The active provider and model routing are selected in the app, but credentials are read from server-side config.
+At least one key is required unless you only use local Ollama.
 
 | Variable | Provider |
 |---|---|
@@ -54,96 +39,104 @@ At least one hosted-provider API key is required unless you only use local Ollam
 | `XAI_API_KEY` | Grok (xAI) |
 | `XAI_BASE_URL` | Optional xAI-compatible base URL override |
 | `GOOGLE_AI_KEY` | Gemini (Google) |
-| `MINIMAX_API_KEY` | MiniMax Code, including `MiniMax-M2.7` |
-| `BRAVE_SEARCH_API_KEY` | Brave Search API for the native `web_search` tool |
+| `MINIMAX_API_KEY` | MiniMax (including `MiniMax-M2.7`) |
+| `BRAVE_SEARCH_API_KEY` | Brave Search for the `web_search` tool |
 | `OPENAI_BASE_URL` | Optional OpenAI-compatible base URL override |
 | `ANTHROPIC_BASE_URL` | Optional Anthropic-compatible base URL override |
-| `DEEPGRAM_API_KEY` | Recordings transcription with Deepgram |
-| `DEEPGRAM_BASE_URL` | Optional Deepgram API base URL override |
-| `DEEPGRAM_MODEL` | Deepgram speech model override, defaults to `nova-3` |
-| `DEEPGRAM_LANGUAGE` | Deepgram language override, defaults to `multi` |
-| `OLLAMA_URL` | Local Ollama server, usually `http://localhost:11434` |
-
-Recording insight generation is controlled in app AI settings with `auto_recording_insights`. It uses the configured AI providers after Deepgram transcription has produced transcript text.
+| `DEEPGRAM_API_KEY` | Recording transcription |
+| `DEEPGRAM_BASE_URL` | Optional Deepgram base URL override |
+| `DEEPGRAM_MODEL` | Deepgram speech model (default: `nova-3`) |
+| `DEEPGRAM_LANGUAGE` | Deepgram language mode (default: `multi`) |
+| `OLLAMA_URL` | Local Ollama server, e.g. `http://localhost:11434` |
 
 ## Official Integrations
 
-Official integrations use OAuth or provider-native account linking and expose structured tools to the agent. The built-in registry currently covers Google Workspace, Notion, Microsoft 365, Slack, Figma, Home Assistant, Weather, Spotify, and personal WhatsApp.
+OAuth app credentials for structured agent tools. All callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback`.
 
-All OAuth callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback` unless you set a provider-specific redirect URI.
+Home Assistant and Trello can be configured per-user in the Flutter UI without any server-side setup.
 
 | Variable | Description |
 |---|---|
-| `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace OAuth client ID |
-| `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace OAuth client secret |
-| `GOOGLE_OAUTH_REDIRECT_URI` | Optional Google Workspace OAuth callback URL |
-| `NOTION_OAUTH_CLIENT_ID` | Notion OAuth client ID |
-| `NOTION_OAUTH_CLIENT_SECRET` | Notion OAuth client secret |
+| `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace client ID |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace client secret |
+| `GOOGLE_OAUTH_REDIRECT_URI` | Optional Google OAuth callback URL |
+| `NOTION_OAUTH_CLIENT_ID` | Notion client ID |
+| `NOTION_OAUTH_CLIENT_SECRET` | Notion client secret |
 | `NOTION_OAUTH_REDIRECT_URI` | Optional Notion OAuth callback URL |
-| `MICROSOFT_OAUTH_CLIENT_ID` | Microsoft 365 OAuth client ID |
-| `MICROSOFT_OAUTH_CLIENT_SECRET` | Microsoft 365 OAuth client secret |
-| `MICROSOFT_OAUTH_REDIRECT_URI` | Optional Microsoft 365 OAuth callback URL |
-| `MICROSOFT_OAUTH_TENANT_ID` | Optional Entra tenant selector, defaults to `common` |
-| `SLACK_OAUTH_CLIENT_ID` | Slack OAuth client ID |
-| `SLACK_OAUTH_CLIENT_SECRET` | Slack OAuth client secret |
+| `MICROSOFT_OAUTH_CLIENT_ID` | Microsoft 365 client ID |
+| `MICROSOFT_OAUTH_CLIENT_SECRET` | Microsoft 365 client secret |
+| `MICROSOFT_OAUTH_REDIRECT_URI` | Optional Microsoft OAuth callback URL |
+| `MICROSOFT_OAUTH_TENANT_ID` | Entra tenant selector (default: `common`) |
+| `SLACK_OAUTH_CLIENT_ID` | Slack client ID |
+| `SLACK_OAUTH_CLIENT_SECRET` | Slack client secret |
 | `SLACK_OAUTH_REDIRECT_URI` | Optional Slack OAuth callback URL |
-| `FIGMA_OAUTH_CLIENT_ID` | Figma OAuth client ID |
-| `FIGMA_OAUTH_CLIENT_SECRET` | Figma OAuth client secret |
+| `FIGMA_OAUTH_CLIENT_ID` | Figma client ID |
+| `FIGMA_OAUTH_CLIENT_SECRET` | Figma client secret |
 | `FIGMA_OAUTH_REDIRECT_URI` | Optional Figma OAuth callback URL |
-| `HOME_ASSISTANT_BASE_URL` | Optional fallback Home Assistant base URL. Users can configure this per account in Official Integrations. |
-| `HOME_ASSISTANT_OAUTH_CLIENT_ID` | Optional fallback Home Assistant OAuth client ID. |
-| `HOME_ASSISTANT_OAUTH_CLIENT_SECRET` | Optional fallback Home Assistant OAuth client secret. |
-| `HOME_ASSISTANT_OAUTH_REDIRECT_URI` | Optional fallback Home Assistant OAuth callback URL. |
-| `HOME_ASSISTANT_ALLOW_PRIVATE_BASE_URL` | Optional safety override. Set to `1` only if you intentionally allow Home Assistant base URLs on localhost/private networks. |
-| `SPOTIFY_OAUTH_CLIENT_ID` | Spotify OAuth client ID |
-| `SPOTIFY_OAUTH_CLIENT_SECRET` | Spotify OAuth client secret |
+| `TRELLO_API_KEY` | Server-side Trello Power-Up key — if set, users only need their personal token |
+| `SPOTIFY_OAUTH_CLIENT_ID` | Spotify client ID |
+| `SPOTIFY_OAUTH_CLIENT_SECRET` | Spotify client secret |
 | `SPOTIFY_OAUTH_REDIRECT_URI` | Optional Spotify OAuth callback URL |
 
-Home Assistant no longer requires server-side setup. Each user can open Official Integrations, select Home Assistant, and enter their own base URL and OAuth app credentials.
-For safety, local/private Home Assistant targets are blocked by default unless `HOME_ASSISTANT_ALLOW_PRIVATE_BASE_URL=1` is set on the server.
+## Messaging
 
-Weather integration uses Open-Meteo public endpoints and does not require OAuth environment variables.
+Messaging platform credentials (Telegram, Discord, WhatsApp, Slack, etc.) are configured through the Flutter app messaging tab — not `.env`. The exception is Telnyx, which requires server-side webhook verification.
 
-## Messaging
+| Variable | Description |
+|---|---|
+| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
 
-Messaging platform credentials are stored through the Flutter app messaging tab, not in `.env`. This includes Telegram, Discord, Slack, Google Chat, Microsoft Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, and the configurable webhook bridges. Use the app to set platform tokens, webhook URLs, inbound secrets, polling options, and access lists.
+Generic inbound webhook path: `PUBLIC_URL + /api/messaging/webhook/:platform`
 
-Generic inbound messaging callbacks use:
+## Service Email
 
-```text
-PUBLIC_URL + /api/messaging/webhook/:platform
-```
+Optional. When configured, NeoAgent uses SMTP for account flows: signup confirmation, password reset, and security notifications. This mailbox is for the NeoAgent server only — it is not exposed as a Gmail or Outlook integration.
+
+| Variable | Default | Description |
+|---|---:|---|
+| `NEOAGENT_EMAIL_FROM` | required | Sender address, e.g. `NeoAgent <no-reply@example.com>` |
+| `NEOAGENT_EMAIL_SMTP_HOST` | required | SMTP hostname |
+| `NEOAGENT_EMAIL_SMTP_PORT` | `587` | SMTP port |
+| `NEOAGENT_EMAIL_SMTP_USER` | optional | SMTP username |
+| `NEOAGENT_EMAIL_SMTP_PASS` | optional | SMTP password or app password |
+| `NEOAGENT_EMAIL_SMTP_SECURE` | `true` on port 465 | Use implicit TLS |
+| `NEOAGENT_EMAIL_SMTP_REQUIRE_TLS` | `true` | Require STARTTLS |
+| `NEOAGENT_EMAIL_SMTP_REJECT_UNAUTHORIZED` | `true` | Reject invalid TLS certs — keep enabled in production |
+| `NEOAGENT_EMAIL_REPLY_TO` | optional | Reply-To header |
+| `NEOAGENT_EMAIL_REQUIRE_SIGNUP_CONFIRMATION` | `true` | Require email confirmation before first sign-in |
+| `NEOAGENT_EMAIL_REQUIRE_EMAIL_CHANGE_CONFIRMATION` | `true` | Require confirmation when changing account email |
+| `NEOAGENT_EMAIL_NOTIFY_UNUSUAL_LOGIN` | `true` | Security notice for new device or network logins |
+| `NEOAGENT_EMAIL_NOTIFY_ACCOUNT_CHANGES` | `true` | Notices for password and email changes |
+| `NEOAGENT_EMAIL_BRAND_NAME` | `NeoAgent` | Display name in email templates |
+| `NEOAGENT_EMAIL_SUPPORT_URL` | optional | Support link for email templates |
+| `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | `24` | Confirmation link expiry |
 
-Telnyx webhook verification is configured through the environment.
+## Runtime Isolation
 
 | Variable | Description |
 |---|---|
-| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
-
-## Runtime Isolation
+| `NEOAGENT_VM_GUEST_TOKEN` | Required for `secure-vm` policy — use 32+ characters, no placeholder values |
 
-Runtime profile and backend selection are stored in user settings, not normally in `.env`. The main profiles are `trusted-host` and `secure-vm`. They control whether CLI, browser, and Android tools run on the host or through the local VM backend.
+Runtime profiles (`trusted-host`, `secure-vm`) are set in user settings, not `.env`. See [Capabilities: Runtime Modes](capabilities.md#runtime-modes).
 
-Production policy can require the VM backend. In that case, set a strong `NEOAGENT_VM_GUEST_TOKEN` of at least 32 characters and avoid placeholder values.
+## Analytics
 
-The app exposes two browser backend choices: Cloud and Chrome extension. Cloud uses the current deployment policy, which means host browser control for trusted private installs and VM browser control for isolated production installs. Chrome extension uses the paired extension connection instead of the server-local Puppeteer browser. To install only the extension on a remote machine, open NeoAgent, download `/api/browser-extension/download`, unzip it, load the folder through `chrome://extensions` with Developer mode enabled, then pair after logging in to NeoAgent. Unpacked Chrome extensions cannot replace themselves automatically; use the extension popup's update check to compare against the server bundle, then download and reload the latest ZIP when needed.
+NeoAgent can send anonymous usage events to your own Mixpanel project. Events cover navigation and feature usage only — no message content, credentials, or personal data.
 
-## Secrets Guidance
+| Variable | Description |
+|---|---|
+| `NEOAGENT_MIXPANEL_TOKEN` | Public Mixpanel project token — leave blank to disable analytics |
 
-Treat `SESSION_SECRET`, provider API keys, OAuth client secrets, service email SMTP credentials, messaging credentials, and Telnyx tokens as sensitive. Do not commit them, print them in logs, or expose them in client-side code. Store them in server-side environment variables or a secrets manager, restrict access to operators who need them, and rotate them immediately if you suspect exposure.
+When analytics is enabled, the web client shows a cookie-consent banner until accepted or declined.
 
 ## Runtime Paths
 
-| Path | Purpose |
+| Path | Contents |
 |---|---|
-| `~/.neoagent/.env` | Server config and deployment secrets |
-| `~/.neoagent/data/` | Database, sessions, update status, and logs |
-| `~/.neoagent/agent-data/` | Skills, memory, and daily data files |
+| `~/.neoagent/.env` | Server config and secrets |
+| `~/.neoagent/data/` | Database, sessions, logs, update status |
+| `~/.neoagent/agent-data/` | Skills, memory, daily data |
 
-## Minimal `.env` Example
+## Security
 
-```dotenv
-PORT=3333
-SESSION_SECRET=change-me-to-something-random
-ANTHROPIC_API_KEY=sk-ant-...
-```
+Treat `SESSION_SECRET`, all API keys, OAuth client secrets, SMTP credentials, and messaging tokens as sensitive. Don't commit them, log them, or expose them in client code or screenshots. Rotate immediately if you suspect exposure.

package/docs/getting-started.md

@@ -1,13 +1,26 @@
 # Getting Started
 
-NeoAgent installs as a Node CLI and runs a self-hosted server with a bundled Flutter web client. The same server can be reached from the Android client when you point it at the deployed backend URL.
+Install takes about 5 minutes. The first VM boot downloads and configures an Ubuntu guest image, which adds a few more minutes on first run.
 
 ## Requirements
 
-- Node.js 20 or newer.
-- A reachable server URL if you want OAuth callbacks, mobile access, or messaging webhooks.
-- At least one hosted AI provider API key, unless you only use local Ollama.
-- Android Studio or a Flutter Android toolchain if you build the Android client yourself.
+| | |
+|---|---|
+| Node.js | 20 or newer |
+| QEMU | for VM-isolated browser and Android |
+| AI provider key | Anthropic, OpenAI, Gemini, Grok, MiniMax, or local Ollama |
+
+No API key is required if you only use local Ollama.
+
+### Install QEMU
+
+```bash
+# macOS
+brew install qemu
+
+# Ubuntu / Debian
+sudo apt-get update && sudo apt-get install -y qemu-system qemu-utils
+```
 
 ## Install
 
@@ -16,49 +29,55 @@ npm install -g neoagent
 neoagent install
 ```
 
-`neoagent install` runs setup if `~/.neoagent/.env` does not exist, installs dependencies, builds or verifies the bundled web client, and starts the service through the host service manager when available.
+This runs setup (if no existing config), installs dependencies, and starts the service.
 
-On macOS, NeoAgent uses a `launchd` user service. On Linux, it uses a `systemd --user` service. On unsupported platforms it falls back to a background Node process.
+Open **http://localhost:3333** in your browser when the install finishes.
 
-## Setup
+## First Run
 
-Run setup again whenever you need to regenerate server config:
+1. Create an account.
+2. Open **Settings → AI Providers** and add at least one API key.
+3. Send a message in **Chat** to confirm the agent responds.
 
-```bash
-neoagent setup
-```
-
-The setup flow asks for the server port, public URL, release channel, AI provider keys, Ollama URL, and official integration OAuth settings. Provider credentials live in server-side config, not in the web client.
+Everything else — integrations, messaging, tasks, Android control — is configured inside the app.
 
 ## Service Commands
 
 ```bash
-neoagent status
+neoagent status      # check install root, config path, and service state
 neoagent start
 neoagent stop
 neoagent restart
-neoagent logs
+neoagent logs        # first stop when something behaves unexpectedly
+```
+
+## Re-running Setup
+
+Run this to regenerate config or change provider keys:
+
+```bash
+neoagent setup
 ```
 
-Use `neoagent status` to confirm the install root, config path, release channel, and service state. Use `neoagent logs` when the service starts but the UI or integrations do not behave as expected.
+The wizard prompts for port, public URL, release channel, AI keys, Ollama URL, and OAuth credentials.
 
-## Updates And Recovery
+## Updates and Recovery
 
 ```bash
-neoagent channel stable
-neoagent channel beta
-neoagent update
-neoagent fix
+neoagent channel stable   # switch to stable releases
+neoagent channel beta     # switch to prerelease builds
+neoagent update           # update to latest on the current channel
+neoagent fix              # reset after a broken install or self-edit
 ```
 
-`neoagent update` follows the configured release channel. `neoagent fix` is for recovery after a self-edit or broken local install. On git installs it backs up runtime data, saves local tracked changes, resets tracked source files, reinstalls dependencies, and restarts the service.
+`neoagent fix` backs up runtime data, resets source files, reinstalls dependencies, and restarts the service. Use it when `neoagent setup && neoagent restart` hasn't resolved an issue.
 
 ## Runtime Paths
 
-| Path | Purpose |
+| Path | Contents |
 |---|---|
 | `~/.neoagent/.env` | Server config and secrets |
-| `~/.neoagent/data/` | Database, sessions, update status, and logs |
-| `~/.neoagent/agent-data/` | Skills, memory, and daily data files |
+| `~/.neoagent/data/` | Database, session data, logs |
+| `~/.neoagent/agent-data/` | Skills, memory, daily data |
 
-Set `NEOAGENT_HOME` if you need to move the runtime root.
+Set `NEOAGENT_HOME` to move the runtime root.

package/docs/hardware.md

@@ -5,4 +5,4 @@ sidebar_label: Hardware
 
 # Hardware
 
-There is no dedicated hardware or wearable firmware bundled with NeoAgent.
+NeoAgent includes a dedicated ESP-IDF wearable firmware target under `firmware/neoagent_wearable_esp32s3_amoled` for the Waveshare ESP32-S3 Touch AMOLED 1.8 board.

package/docs/index.md

@@ -6,9 +6,7 @@ sidebar_label: Overview
 
 # NeoAgent
 
-NeoAgent is a self-hosted proactive AI agent with a bundled Flutter client for web and Android. It runs on your server, keeps credentials server-side, and gives you an operator UI for chat, runs, logs, tasks, skills, integrations, MCP, memory, Android control, recordings, Health Connect data, and settings.
-
-It is designed for people who want a focused personal automation server rather than a broad gateway platform. NeoAgent can run triggered tasks, control a browser, operate a server-attached Android emulator or device, manage files, remember long-term context, connect to hosted AI providers or local Ollama, search recordings, read synced health summaries, and send results through Telegram, Discord, WhatsApp, or Telnyx Voice.
+Self-hosted AI agent server. Runs as a system service, keeps all credentials on your machine, and provides a full operator UI for chat, automation, Android device control, recordings, integrations, and memory.
 
 ## Quick Start
 
@@ -17,34 +15,30 @@ npm install -g neoagent
 neoagent install
 ```
 
-Open the server URL, sign in, configure providers and messaging, then create a task or chat run.
+Opens at `http://localhost:3333` when complete. See [Getting Started](getting-started.md) for prerequisites and first-run steps.
 
-## What NeoAgent Does
+## What You Can Do
 
-| Area | Capability |
+| | |
 |---|---|
-| AI providers | OpenAI, Anthropic, xAI, Google, MiniMax Code, and local Ollama |
-| Operator UI | Chat, live runs, logs, tasks, skills, integrations, MCP, memory, devices, recordings, health, settings |
-| Automation | Triggered tasks, one-time runs, browser control, file access, CLI skills, subagents, and messaging delivery |
-| Android control | AI control of a server-attached Android emulator or device: screenshots, UI dumps, taps, typing, intents, APK installs, and ADB shell |
-| Recordings | Web and Android audio sessions with transcript search and AI insights |
-| Integrations | Google Workspace, Notion, Microsoft 365, Slack, Figma, and remote MCP servers |
-| Messaging | Telegram, Discord, WhatsApp text/media, and Telnyx Voice calls |
-| Outputs | Artifacts, Grok image generation, vision analysis, markdown tables, and Mermaid graphs |
-| Recovery | `neoagent status`, `neoagent logs`, `neoagent update`, release channels, and `neoagent fix` |
-
-## Main Paths
-
-| Need | Start here |
+| **Chat with tools** | Browse the web, run shell commands, read/write files, call APIs, generate images |
+| **Automate** | Schedule tasks on cron, trigger from integrations or weather events, deliver results via messaging |
+| **Control Android** | Screenshot, observe UI, tap, type, swipe, launch apps, install APKs, run `adb shell` |
+| **Connect accounts** | Google Workspace, Microsoft 365, Notion, Slack, Figma, Home Assistant, Trello, Spotify |
+| **Message anywhere** | Telegram, WhatsApp, Discord, Signal, Matrix, iMessage, Teams, Telnyx Voice, and more |
+| **Record and transcribe** | Audio sessions from browser or Android, transcript search, AI-generated insights |
+| **Remember** | Long-term semantic memory, session logs, core facts, daily summaries |
+
+## Documentation
+
+| | |
 |---|---|
-| Install and first run | [Getting Started](getting-started.md) |
-| Full product surface | [Capabilities](capabilities.md) |
-| Android device control | [Capabilities: Android Control](capabilities.md#android-control) |
-| Recordings and transcripts | [Capabilities: Recordings](capabilities.md#recordings) |
-| Scheduled tasks | [Automation](automation.md) |
-| OAuth apps and messaging | [Integrations](integrations.md) |
-| Skills and MCP | [Skills](skills.md) |
-| Secrets and runtime settings | [Configuration](configuration.md) |
-| Logs, updates, and repair | [Operations](operations.md) |
-| OpenClaw comparison | [Why NeoAgent](why-neoagent.md) |
-| Migration from OpenClaw/Hermes | [Migration Guide](migration.md) |
+| [Getting Started](getting-started.md) | Install, first run, service commands |
+| [Capabilities](capabilities.md) | Full tool and feature inventory |
+| [Configuration](configuration.md) | Environment variables, provider keys, OAuth setup |
+| [Automation](automation.md) | Tasks, cron scheduling, integration triggers |
+| [Integrations](integrations.md) | OAuth accounts and messaging platforms |
+| [Skills](skills.md) | Built-in skills catalog, custom skills, MCP |
+| [Operations](operations.md) | Updates, logs, recovery |
+| [Why NeoAgent](why-neoagent.md) | Comparison with OpenClaw |
+| [Migration](migration.md) | Migrate from OpenClaw or Hermes |

package/docs/integrations.md

@@ -1,84 +1,66 @@
 # Integrations
 
-NeoAgent has two integration layers: official integrations for structured app tools, and messaging platforms for talking to the agent.
+NeoAgent has two integration layers: official integrations for structured app tools, and messaging platforms for communicating with the agent.
 
 ## Official Integrations
 
-The built-in registry includes:
+Structured OAuth-backed tools the agent can use in chat and automation. Connect accounts in the Flutter app under **Integrations**.
 
-| Provider | Use |
+| Provider | What the agent can do |
 |---|---|
-| Google Workspace | Gmail, Calendar, Drive, Docs, and Sheets tools |
-| Notion | Search, pages, databases, blocks, comments, and raw Notion API requests |
-| Microsoft 365 | Outlook, Calendar, OneDrive, Teams, and Microsoft Graph requests |
-| Slack | Conversations, history, posting, search, user info, and Slack Web API requests |
-| Figma | Current user, files, nodes, rendered images, comments, and Figma REST requests |
-| Home Assistant | Entity/config reads, service calls, and Home Assistant REST API requests |
-| Weather | Keyless Open-Meteo current weather and forecast tools |
-| Spotify | Playback state, recently played, search, and playback controls |
+| **Google Workspace** | Search and send Gmail, read/create Calendar events, Drive upload/download/share, Docs create/append, Sheets read/write |
+| **Microsoft 365** | Outlook mail, Calendar, OneDrive, Teams messages, Graph API |
+| **Notion** | Search pages, read/write databases and blocks, manage comments |
+| **Slack** | Read and send messages, search conversations |
+| **Figma** | Read files and nodes, get rendered images, manage comments |
+| **Home Assistant** | Read entity state, call services |
+| **Trello** | Manage boards, lists, cards, comments, and search |
+| **Spotify** | Playback controls, search, queue management |
+| **Weather** | Current conditions and forecasts — no API key needed |
+| **Personal WhatsApp** | Per-account read and send with isolated access |
 
-OAuth app credentials are configured through server environment variables for most providers. Home Assistant can also be configured per-user in the Flutter **Integrations** UI without any server-side setup. Account connections are created in the Flutter UI under **Integrations**. Connected tools are exposed to the agent as structured tools, so prefer them over browser automation when they can do the job.
+### Access Modes
 
-Weather note: the Weather integration uses Open-Meteo public APIs and does not require OAuth client credentials.
+Each connected account can be set to **Read/Write** (default) or **Read Only**. Read-only blocks all write operations server-side — sending, creating, updating, and deleting.
 
-### Per-Account Access Mode
+### OAuth Setup
 
-Each connected official integration account can be configured per connection as:
+Most providers require OAuth app credentials in server config before users can connect. See [Configuration: Official Integrations](configuration.md#official-integrations) for the required environment variables.
 
-- `Read / Write` (default)
-- `Read Only`
+Home Assistant and Trello can be configured per-user in the **Integrations** UI without any server-side setup.
 
-When an account is set to `Read Only`, write operations are blocked for that connection (for example: sending email, posting messages, creating/updating/deleting resources, or write-method API requests).
+The default OAuth callback URL is `PUBLIC_URL + /api/integrations/oauth/callback`.
 
-This setting is managed in the Flutter **Integrations** UI on each connected account row and is enforced server-side during tool execution.
-
-The default callback is:
-
-```text
-PUBLIC_URL + /api/integrations/oauth/callback
-```
-
-You can override it with provider-specific redirect URI variables listed in [Configuration](configuration.md).
+**If an OAuth connection fails:**
+1. Confirm `PUBLIC_URL` is reachable by the provider
+2. Confirm the redirect URI in your OAuth app matches NeoAgent's callback URL
+3. Confirm the client ID and secret are set in server config
+4. Restart after changing environment variables: `neoagent restart`
 
 ## Messaging Platforms
 
-NeoAgent can talk through:
+Channels through which users and the agent communicate. Configure credentials in the Flutter app under **Settings → Messaging** — not in `.env`.
 
 | Platform | Notes |
 |---|---|
-| WhatsApp | Messaging-platform bridge in app settings for talking to the agent; separate official personal WhatsApp integration for structured read/send tools |
-| Telegram | Bot token plus approved chats |
-| Discord | Bot token plus server or channel access |
-| Slack | Bot token sends plus Events API callbacks |
-| Google Chat | Space webhook sends plus app callback ingestion |
-| Microsoft Teams | Incoming webhook sends plus outgoing webhook ingestion |
-| Matrix | Homeserver access token with room send and polling |
-| Signal | signal-cli REST API bridge |
-| iMessage / BlueBubbles | BlueBubbles-compatible bridge for macOS-hosted iMessage |
-| IRC and Twitch | IRC-style channel connections |
-| LINE and Mattermost | Native send paths with webhook ingestion |
-| Feishu, Nextcloud Talk, Nostr, Synology Chat, Tlon, Zalo, Zalo Personal, WeChat, and WebChat | Configurable webhook bridges |
-| Telnyx Voice | Inbound and outbound calling with text-to-speech; tasks can call a number |
-
-Messaging channel credentials are configured through the Flutter app messaging tab (not `.env`) for channel setup and inbound callback routing. The generic inbound callback path is:
-
-```text
-PUBLIC_URL + /api/messaging/webhook/:platform
-```
-
-Use the per-platform inbound secret or native signature fields in the messaging tab for webhook callbacks.
-
-Telnyx exception: only the Telnyx voice webhook verification token stays in server environment variables as `TELNYX_WEBHOOK_TOKEN`, because webhook request verification is performed server-side. Other Telnyx and messaging channel credentials should be configured in the Flutter app messaging tab as part of channel/client configuration.
-
-## Credentials
-
-Keep provider API keys, OAuth client secrets, and messaging tokens on the server. Do not put them in docs, skill files, client-side code, screenshots, or logs.
-
-If an OAuth provider fails to connect, check:
-
-- `PUBLIC_URL` is reachable by the provider.
-- The provider redirect URI matches NeoAgent's callback URL.
-- The provider client ID and client secret are set on the server.
-- The NeoAgent service was restarted after changing environment variables.
-
-See [Capabilities](capabilities.md) for examples of the structured tools exposed by each provider.
+| **WhatsApp** | Messaging bridge for agent chat; separate official integration for structured read/send tools |
+| **Telegram** | Bot token plus approved chat IDs |
+| **Discord** | Bot token plus server or channel access |
+| **Slack** | Bot token sends, Events API callbacks |
+| **Google Chat** | Space webhook sends, app callback ingestion |
+| **Microsoft Teams** | Incoming webhook sends, outgoing webhook ingestion |
+| **Matrix** | Homeserver access token, room send, polling |
+| **Signal** | signal-cli REST API bridge |
+| **iMessage / BlueBubbles** | BlueBubbles-compatible bridge on a macOS host |
+| **IRC and Twitch** | IRC-style channel connections |
+| **LINE and Mattermost** | Native send, webhook ingestion |
+| **Telnyx Voice** | Inbound and outbound calls with text-to-speech |
+| **Webhook bridges** | Feishu, Nextcloud Talk, Nostr, Synology Chat, Tlon, Zalo, WeChat, WebChat |
+
+Inbound webhook path: `PUBLIC_URL + /api/messaging/webhook/:platform`
+
+`TELNYX_WEBHOOK_TOKEN` is the only messaging credential that goes in `.env` — all others are configured through the app messaging tab.
+
+## Security
+
+Keep OAuth client secrets, bot tokens, and API keys on the server. Don't put them in skill files, task prompts, screenshots, or logs. Rotate immediately if a credential is exposed.