neoagent 2.1.18-beta.8 → 2.1.18-beta.80

package/.env.example

@@ -16,6 +16,30 @@ SECURE_COOKIES=false
 # Use `managed` for SaaS-style deployments to hide self-update controls in the UI.
 NEOAGENT_DEPLOYMENT_MODE=self_hosted
 
+# Deployment profile:
+#   private -> single-user / trusted host runtime
+#   prod    -> multi-user / isolated per-user VM runtime
+NEOAGENT_PROFILE=private
+
+# VM runtime settings used by `prod`.
+# Set these before switching NEOAGENT_PROFILE=prod.
+# The app can cache a shared base image automatically from a URL, then create
+# lightweight per-user qcow2 overlays on top of it.
+# For Apple Silicon / arm64 hosts, switch this to:
+# https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img
+NEOAGENT_VM_BASE_IMAGE_URL=https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img
+
+# Optional local override. If set, this takes precedence over the download URL.
+NEOAGENT_VM_BASE_IMAGE=
+
+# The guest image must boot a Linux guest that runs `npm run start:guest-agent`
+# and exposes the guest agent on port 8421.
+# Replace this placeholder before using NEOAGENT_PROFILE=prod.
+# Example: openssl rand -hex 32
+NEOAGENT_VM_GUEST_TOKEN=change-this-guest-token-before-prod
+NEOAGENT_VM_MEMORY_MB=4096
+NEOAGENT_VM_CPUS=2
+
 # Self-hosted release track used by `neoagent update`.
 NEOAGENT_RELEASE_CHANNEL=stable
 
@@ -23,6 +47,20 @@ NEOAGENT_RELEASE_CHANNEL=stable
 # Example: http://localhost:3333,https://yourdomain.com
 ALLOWED_ORIGINS=
 
+########################################
+# Service email
+########################################
+
+# Service-only email for account security messages.
+# The agent cannot read, search, or send from this mailbox. It is not a Gmail,
+# Outlook, or messaging integration account; it is only used by the NeoAgent
+# server for signup confirmation, password reset, and security notifications.
+NEOAGENT_EMAIL_FROM=
+NEOAGENT_EMAIL_SMTP_HOST=
+NEOAGENT_EMAIL_SMTP_PORT=587
+NEOAGENT_EMAIL_SMTP_USER=
+NEOAGENT_EMAIL_SMTP_PASS=
+
 ########################################
 # Hosted AI providers
 ########################################
@@ -75,6 +113,32 @@ GOOGLE_OAUTH_CLIENT_ID=your-google-oauth-client-id
 GOOGLE_OAUTH_CLIENT_SECRET=your-google-oauth-client-secret
 GOOGLE_OAUTH_REDIRECT_URI=
 
+# Notion official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+NOTION_OAUTH_CLIENT_ID=your-notion-oauth-client-id
+NOTION_OAUTH_CLIENT_SECRET=your-notion-oauth-client-secret
+NOTION_OAUTH_REDIRECT_URI=
+
+# Microsoft 365 official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+# Leave tenant ID as `common` for a multi-tenant app, or set a specific Entra tenant ID.
+MICROSOFT_OAUTH_CLIENT_ID=your-microsoft-oauth-client-id
+MICROSOFT_OAUTH_CLIENT_SECRET=your-microsoft-oauth-client-secret
+MICROSOFT_OAUTH_REDIRECT_URI=
+MICROSOFT_OAUTH_TENANT_ID=common
+
+# Slack official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+SLACK_OAUTH_CLIENT_ID=your-slack-oauth-client-id
+SLACK_OAUTH_CLIENT_SECRET=your-slack-oauth-client-secret
+SLACK_OAUTH_REDIRECT_URI=
+
+# Figma official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+FIGMA_OAUTH_CLIENT_ID=your-figma-oauth-client-id
+FIGMA_OAUTH_CLIENT_SECRET=your-figma-oauth-client-secret
+FIGMA_OAUTH_REDIRECT_URI=
+
 ########################################
 # Tools and media services
 ########################################

package/README.md

@@ -3,21 +3,18 @@
 <p align="center"><strong>Your agent. Your server. Your rules.</strong></p>
 
 <p align="center">
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-18+-5fa04e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-20+-5fa04e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
   <a href="https://sqlite.org"><img src="https://img.shields.io/badge/SQLite-WAL-003b57?style=flat-square&logo=sqlite&logoColor=white" alt="SQLite"></a>
   <a href="https://flutter.dev"><img src="https://img.shields.io/badge/Flutter-web%20%2B%20android-02569B?style=flat-square&logo=flutter&logoColor=white" alt="Flutter"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-a855f7?style=flat-square" alt="License"></a>
 </p>
 
-<p align="center">
-  A self-hosted, proactive AI agent with a Flutter client for web and Android.<br>
-  Connects to OpenAI, xAI, Google, MiniMax Code, and local Ollama.<br>
-  Runs tasks on a schedule, controls a browser, manages files, and talks to you over Telegram, Discord, or WhatsApp.
-</p>
+<p align="center">A self-hosted, proactive AI agent with a Flutter client for web and Android.</p>
 
 | | |
 | --- | --- |
-| <img alt="WebUI" src="https://github.com/user-attachments/assets/3c76d59a-b6e3-4698-929b-9c94741ccf1e" height="420"> | <img alt="Mobile Telegram" src="https://github.com/user-attachments/assets/1fd41a9b-5452-4aa4-9478-888c8ad7363a" height="420"> |
+| <img alt="WebUI" src="https://github.com/user-attachments/assets/3c76d59a-b6e3-4698-929b-9c94741ccf1e" height="420"> | <img height="494" alt="Android" src="https://github.com/user-attachments/assets/e8a0af7a-6881-485d-ad52-f3bc6f2023ca"> | <img alt="Mobile Telegram" src="https://github.com/user-attachments/assets/1fd41a9b-5452-4aa4-9478-888c8ad7363a" height="420"> |
+
 
 ## Install
 
@@ -36,14 +33,12 @@ neoagent fix
 neoagent logs
 ```
 
-Use `neoagent fix` if a self-edit or broken local install leaves NeoAgent in a bad state. On git installs it backs up runtime data, saves local tracked changes, resets tracked source files, reinstalls dependencies, and restarts the service.
-
 ## Links
 
-[⚙️ Configuration](docs/configuration.md) · [🧰 Skills](docs/skills.md) · [🐛 Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
+[Docs](https://neolabs-systems.github.io/NeoAgent/) | [Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
 
 ---
 
 <p align="center">
-  Made with ❤️ by <a href="https://github.com/neooriginal">Neo</a> · <a href="https://github.com/NeoLabs-Systems">NeoLabs Systems</a>
+  Made by <a href="https://github.com/neooriginal">Neo</a> | <a href="https://github.com/NeoLabs-Systems">NeoLabs Systems</a>
 </p>

package/docs/automation.md

@@ -0,0 +1,53 @@
+# Automation
+
+NeoAgent is built for proactive work: tasks that run later, repeat on a schedule, use tools, and notify you when there is something useful to report.
+
+## Scheduler
+
+Use the **Scheduler** section in the UI to create recurring tasks. A scheduled task has:
+
+| Field | Purpose |
+|---|---|
+| Name | Human-readable task label |
+| Cron expression | Five-field cron schedule |
+| Prompt | Self-contained instruction for the future run |
+| Enabled state | Active or paused |
+| Model override | Optional model for this task |
+
+Scheduled prompts should include the condition for notifying you. For example, ask NeoAgent to message you only when a monitored thing changes, fails, or needs attention.
+
+## Tool Capabilities
+
+Automation can use the same tool surface as normal chat runs:
+
+| Capability | Examples |
+|---|---|
+| Browser | Navigate, click, type, extract page content, take screenshots, evaluate page JavaScript |
+| Files | Read, write, search, and summarize host files through skills |
+| CLI | Run shell commands in a persistent terminal through skills |
+| Memory | Store durable facts and retrieve useful context |
+| Messaging | Send a proactive result through a connected platform |
+| MCP | Use tools exposed by configured remote MCP servers |
+| Official integrations | Use structured OAuth-backed app tools where available |
+| Recordings | List, open, and search recording transcripts |
+| Health | Read synced Android Health Connect metrics as summaries |
+| Android | Drive a server-attached emulator or device through UI and ADB tools |
+| Subagents | Spawn async helper agents inside a longer run |
+| Outputs | Generate artifacts, Grok images, Mermaid graphs, and markdown tables |
+
+Prefer official integrations and structured MCP tools over browser automation when both can answer the task. They are usually less brittle and easier to audit.
+
+See [Capabilities](capabilities.md) for the broader tool inventory.
+
+## Safety Expectations
+
+NeoAgent runs on your server and can touch real files, messaging surfaces, browser sessions, and connected services. Keep scheduled prompts narrow and self-contained.
+
+For sensitive automations:
+
+- Use allowlists for messaging platforms.
+- Keep secrets in server config, not prompts or skills.
+- Prefer read-only checks unless the task explicitly needs to mutate data.
+- Ask for notification only when a condition is met to avoid noisy repeated messages.
+- Review run history in **Runs** and service logs in **Logs** when behavior is surprising.
+- Remember that browser, CLI, Android runtime, and local file tools run on the NeoAgent server or configured worker, not necessarily on your current laptop.

package/docs/capabilities.md

@@ -0,0 +1,125 @@
+# Capabilities
+
+This page lists the product surfaces that are easy to miss from the short README. It is based on the current server routes, agent tool registry, Flutter sections, Android bridge code, and integration providers in this repository.
+
+## Operator UI
+
+The Flutter client exposes the main operator surfaces:
+
+| Section | What it is for |
+|---|---|
+| Chat | Normal agent runs with tools, memory, integrations, and messaging |
+| Runs | Live and historical run steps, including browser, Android, CLI, messaging, scheduler, MCP, and subagent work |
+| Logs | Service logs and diagnostics from the server you are connected to |
+| Scheduler | Recurring cron tasks and one-time future runs |
+| Skills | Built-in and custom reusable workflows |
+| Integrations | OAuth account connections for structured app tools |
+| MCP | Remote MCP server registration and tool discovery |
+| Memory | Long-term memory, core memory, and session search |
+| Devices | Server-side browser and Android runtime controls |
+| Recordings | Recording sessions, transcripts, segments, and playback |
+| Health | Android Health Connect sync status and synced metrics |
+| Wearables | Supported Bluetooth recording devices and audio upload status |
+| Settings | AI providers, model routing, runtime settings, messaging, and service controls |
+
+## Recordings
+
+NeoAgent records audio as server-side sessions with one or more sources. The web client can record browser microphone and screen audio, the Android app can record phone microphone audio through a foreground service, and the wearable bridge can upload audio chunks from supported Bluetooth devices.
+
+Recording sessions support:
+
+- Chunked uploads with per-source sequence checks.
+- Sources, chunks, transcript segments, session status, and playback URLs.
+- Statuses for recording, processing, completed, failed, and cancelled sessions.
+- Retry transcription and delete transcript segment actions.
+- Full session deletion with storage cleanup.
+- Agent tools for listing, opening, and searching transcripts: `recordings_list`, `recordings_get`, and `recordings_search`.
+
+Transcription uses Deepgram when `DEEPGRAM_API_KEY` is configured. The default speech model is `nova-3`, and the default language mode is `multi`. When `auto_recording_insights` is enabled in AI settings, NeoAgent can generate structured recording insights such as a summary, action items, and events.
+
+## Android Control
+
+NeoAgent can let the AI control an Android emulator or device attached to the NeoAgent server or configured worker. This is the Android capability in the comparison: the agent can observe and operate Android, not only run an Android companion app.
+
+Android control supports:
+
+- Starting and stopping the managed Android emulator.
+- Listing ADB-connected devices and installed apps.
+- Taking screenshots and UIAutomator XML dumps.
+- Observing visible UI nodes.
+- Opening apps and Android intents.
+- Tapping, long pressing, typing, swiping, and pressing Android navigation keys.
+- Waiting for text, resource IDs, descriptions, or classes to appear.
+- Installing `.apk` and universal `.apks` bundles.
+- Running `adb shell` commands when higher-level tools are not enough.
+
+These actions run where the NeoAgent backend is running. If NeoAgent is deployed on a remote server, the AI controls the Android runtime attached to that server, not the laptop where you are reading the docs.
+
+## Android App, Health, And Wearables
+
+The Flutter Android app is still useful as a client. It can sign in to the same self-hosted backend, run chat and operator UI flows, sync Health Connect data, record audio locally, and bridge supported wearables.
+
+Android app capabilities include:
+
+- `NEOAGENT_BACKEND_URL` build/run configuration for real devices.
+- Health Connect permission flow and background sync.
+- Microphone recording through an Android foreground service.
+- Boot restore hooks for recording and wearable services when Android allows them.
+- Bluetooth wearable bridge support for HeyPocket-style devices.
+- Upload of wearable chunks and synchronization state to the backend.
+
+## Health Data
+
+Health data comes from the Android app through `/api/mobile/health`. NeoAgent stores sync runs and normalized metric samples. The built-in metric aliases include steps, heart rate, sleep sessions, exercise sessions, and weight.
+
+The agent tool `read_health_data` returns summaries and recent samples. It is designed to answer questions such as recent step totals or available health metrics without dumping every raw record.
+
+## Integrations And Messaging
+
+NeoAgent has two separate integration layers:
+
+- Official integrations expose structured tools for Google Workspace, Microsoft 365, Notion, Slack, Figma, and a separate personal WhatsApp connection.
+- Messaging platforms let the agent talk through WhatsApp, Telegram, Discord, Slack, Google Chat, Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, configurable webhook bridges, and Telnyx Voice.
+
+Official integration examples include Gmail thread search and send mail, Google Calendar events, Drive upload/download/export/share links, Docs create/append/replace, Sheets read/update/append/create, Microsoft Outlook/Calendar/OneDrive/Teams tools, Notion search/page/block/database tools, Slack conversation/message tools, Figma file/node/comment/image tools, and a personal WhatsApp integration with isolated chat read/send tools and per-account read-only versus read/write access.
+
+Messaging examples include Telegram and Discord messages, Slack channel replies, Matrix room messages, Google Chat and Teams webhook delivery, Signal bridge delivery, iMessage/BlueBubbles sends, WhatsApp text and media sends, Telnyx inbound voice, Telnyx outbound calls, and scheduled-task call delivery.
+
+## Agent Tools
+
+NeoAgent's agent tool surface includes more than basic chat:
+
+| Area | Examples |
+|---|---|
+| CLI | PTY-capable `execute_command` with stdin, timeout, stdout, stderr, exit code, and duration |
+| Browser | Navigate, click, type, extract, screenshot, and evaluate page JavaScript |
+| Android control | UI observation, input, screenshots, app launch, intent launch, APK install, and shell commands |
+| Web search | Brave Search API through `web_search` |
+| Files | Read, write, edit, list, and search files |
+| HTTP | Direct HTTP requests |
+| Memory | Semantic memory, session search, daily logs, API key name reads, and core memory |
+| Skills | Create, list, update, and delete persistent skills |
+| Scheduler | Recurring tasks, one-time runs, model overrides, and optional Telnyx call delivery |
+| MCP | Add, list, and remove MCP servers, plus dynamic MCP tool use |
+| Subagents | Spawn, list, wait for, and cancel async subagents inside a run |
+| Output | Generate markdown tables and Mermaid graphs |
+| Images | Generate images with Grok and analyze local image files with a vision-capable model |
+| Recordings | List, inspect, and search recording transcripts |
+| Health | Read synced mobile health metrics |
+
+Generated binary or text artifacts can be promoted into user-scoped artifact storage under `~/.neoagent/data/artifacts` and served through authenticated `/api/artifacts/:id/content` URLs.
+
+## Runtime Modes
+
+Runtime settings let operators choose where higher-risk work runs:
+
+| Profile | Runtime shape |
+|---|---|
+| `trusted-host` | CLI, browser, and Android tools run on the host |
+| `secure-vm` | CLI, browser, and Android tools run through the local VM backend |
+
+Production policy can require the secure VM profile and a strong VM guest token.
+
+These controls matter operationally: the browser, Android emulator, local files, and shell commands run wherever the NeoAgent backend, VM, or paired browser extension is running, not necessarily on the computer where you are reading the docs. Logs from a different server or remote browser may not match the logs on the local machine.
+
+For extension-only remote browser control, download `/api/browser-extension/download` from NeoAgent, unzip it on the remote machine, load the folder in `chrome://extensions`, and pair after logging in. The extension uses Chrome's debugger permission for full browser control, so Chrome will show its normal debugging warning while attached. The popup can check whether the server has a newer extension bundle, but unpacked Developer Mode installs still need a manual download and reload.

package/docs/configuration.md

@@ -1,66 +1,133 @@
 # Configuration
 
-All settings live in `~/.neoagent/.env` by default. Run `neoagent setup` to regenerate interactively. AI provider credentials are configured through the server environment or `neoagent setup`, not through the web UI. If a self-edit or local install issue leaves NeoAgent broken, rerun setup or restore the env file and restart the service.
-You can override the runtime root with `NEOAGENT_HOME`.
+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`.
 
-## Variables
+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.
 
-### Core
+## Core Variables
 
 | Variable | Default | Description |
-|---|---|---|
-| `PORT` | `3333` | HTTP port |
-| `PUBLIC_URL` | *(optional)* | Public base URL used for callbacks and external links |
-| `SESSION_SECRET` | *(required)* | Random string for session signing — generate with `openssl rand -hex 32` |
-| `NODE_ENV` | `production` | Set to `development` to enable verbose logs |
-| `SECURE_COOKIES` | `false` | Set `true` when behind a TLS-terminating proxy |
-| `ALLOWED_ORIGINS` | *(none)* | Comma-separated CORS origins, e.g. `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 |
+|---|---:|---|
+| `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. |
 
-### AI Providers
+## Service Email
 
-At least one hosted-provider API key is required unless you only use local Ollama. The active provider and model routing are configured in the Flutter app; credentials stay in server-side config.
+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.
+
+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.
+
+| 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. |
+
+## 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.
 
 | Variable | Provider |
 |---|---|
 | `ANTHROPIC_API_KEY` | Claude (Anthropic) |
-| `OPENAI_API_KEY` | GPT-4o / Whisper (OpenAI) |
+| `OPENAI_API_KEY` | GPT and Whisper (OpenAI) |
 | `XAI_API_KEY` | Grok (xAI) |
 | `XAI_BASE_URL` | Optional xAI-compatible base URL override |
 | `GOOGLE_AI_KEY` | Gemini (Google) |
-| `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace official integrations OAuth client ID |
-| `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace official integrations OAuth client secret |
-| `GOOGLE_OAUTH_REDIRECT_URI` | Optional override for the Google Workspace OAuth callback URL |
-| `MINIMAX_API_KEY` | MiniMax Code (Coding Plan / Token Plan for `MiniMax-M2.7`) |
+| `MINIMAX_API_KEY` | MiniMax Code, including `MiniMax-M2.7` |
 | `BRAVE_SEARCH_API_KEY` | Brave Search API for the native `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 Nova-3 multilingual |
+| `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 (`http://localhost:11434`) |
+| `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.
 
-`GOOGLE_OAUTH_CLIENT_SECRET` is sensitive, just like `SESSION_SECRET`. Do not commit it to version control, print it to logs, or expose it in client-side code. Store it in server-side environment variables or a secrets manager, restrict access to operators who need it, and rotate it immediately if you suspect it was exposed.
+## Official Integrations
 
-### Messaging
+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, and personal WhatsApp.
+
+All OAuth callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback` unless you set a provider-specific redirect URI.
 
 | Variable | Description |
 |---|---|
-| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification |
+| `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 |
+| `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 |
+| `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_REDIRECT_URI` | Optional Figma OAuth callback URL |
+
+## Messaging
+
+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 messaging callbacks use:
+
+```text
+PUBLIC_URL + /api/messaging/webhook/:platform
+```
 
-Telegram, Discord, and WhatsApp tokens are stored in the database via the Flutter app settings page — not in `.env`.
+Telnyx webhook verification is configured through the environment.
 
-## Runtime data paths
+| Variable | Description |
+|---|---|
+| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
 
-- Config: `~/.neoagent/.env`
-- Database/session/logs: `~/.neoagent/data/`
-- Skills/memory/daily data files: `~/.neoagent/agent-data/`
+## Runtime Isolation
 
----
+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.
+
+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.
+
+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.
+
+## Secrets Guidance
+
+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.
+
+## Runtime Paths
+
+| Path | Purpose |
+|---|---|
+| `~/.neoagent/.env` | Server config and deployment secrets |
+| `~/.neoagent/data/` | Database, sessions, update status, and logs |
+| `~/.neoagent/agent-data/` | Skills, memory, and daily data files |
 
-## Minimal `.env` example
+## Minimal `.env` Example
 
 ```dotenv
 PORT=3333

package/docs/getting-started.md

@@ -0,0 +1,64 @@
+# 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.
+
+## 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.
+
+## Install
+
+```bash
+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.
+
+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.
+
+## Setup
+
+Run setup again whenever you need to regenerate server config:
+
+```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.
+
+## Service Commands
+
+```bash
+neoagent status
+neoagent start
+neoagent stop
+neoagent restart
+neoagent logs
+```
+
+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.
+
+## Updates And Recovery
+
+```bash
+neoagent channel stable
+neoagent channel beta
+neoagent update
+neoagent fix
+```
+
+`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.
+
+## Runtime Paths
+
+| Path | Purpose |
+|---|---|
+| `~/.neoagent/.env` | Server config and secrets |
+| `~/.neoagent/data/` | Database, sessions, update status, and logs |
+| `~/.neoagent/agent-data/` | Skills, memory, and daily data files |
+
+Set `NEOAGENT_HOME` if you need to move the runtime root.

package/docs/hardware.md

@@ -0,0 +1,11 @@
+---
+title: Waveshare ESP32-S3 1.8inch AMOLED Setup
+sidebar_label: Waveshare 1.8inch AMOLED
+---
+
+# Waveshare ESP32-S3 1.8inch AMOLED Setup
+
+Use this only if you want to build or flash this board:
+
+Waveshare ESP32-S3 1.8inch AMOLED Touch Display Dev Board
+

package/docs/index.md

@@ -0,0 +1,50 @@
+---
+slug: /
+title: NeoAgent
+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, scheduler tasks, skills, integrations, MCP, memory, Android control, recordings, Health Connect data, wearables, and settings.
+
+It is designed for people who want a focused personal automation server rather than a broad gateway platform. NeoAgent can run scheduled 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.
+
+## Quick Start
+
+```bash
+npm install -g neoagent
+neoagent install
+```
+
+Open the server URL, sign in, configure providers and messaging, then create a scheduled task or chat run.
+
+## What NeoAgent Does
+
+| Area | Capability |
+|---|---|
+| AI providers | OpenAI, Anthropic, xAI, Google, MiniMax Code, and local Ollama |
+| Operator UI | Chat, live runs, logs, scheduler, skills, integrations, MCP, memory, devices, recordings, health, wearables, settings |
+| Automation | Recurring scheduled 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, Android, and wearable 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 |
+|---|---|
+| 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) |
+| Want to flash a Waveshare ESP32-S3 1.8inch AMOLED | [Waveshare ESP32-S3 1.8inch AMOLED Setup](hardware.md) |
+| OpenClaw comparison | [Why NeoAgent](why-neoagent.md) |