neoagent 2.4.4-beta.9 → 2.5.0

package/docs/capabilities.md

@@ -1,127 +1,25 @@
 # Capabilities
 
-NeoAgent can operate real software on the machine it runs on — a browser, Android emulators and devices, and a terminal. It connects to your accounts, remembers context across sessions, and runs scheduled automations without you being present.
+This page is retained for existing links. The documentation now groups
+capabilities by workflow instead of maintaining one long inventory.
 
-## Operator UI
+## Work with the agent
 
-| Section | What it's for |
-|---|---|
-| **Chat** | Interactive agent runs with full tool access, memory, integrations, and messaging |
-| **Runs** | Live and historical step-by-step execution — browser, Android, CLI, messaging, tasks, MCP, subagents |
-| **Tasks** | Schedule-triggered and integration-triggered automations |
-| **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 facts, and session search |
-| **Devices** | Server-side browser and Android runtime controls |
-| **Recordings** | Audio sessions, transcripts, segment playback, AI insights |
-| **Health** | Android Health Connect sync status and synced metrics |
-| **Settings** | AI providers, model routing, runtime settings, messaging credentials |
-| **Logs** | Service logs and diagnostics |
+- [Models and providers](models.md)
+- [Agents and users](agents-and-users.md)
+- [Memory](memory.md)
+- [Skills and MCP](skills.md)
 
-## Agent Tools
+## Connect systems
 
-What the agent can use in chat and automation runs:
+- [Integrations and messaging](integrations.md)
+- [Devices and interfaces](devices.md)
+- [Recordings and health](recordings-and-health.md)
 
-| Area | Capabilities |
-|---|---|
-| **CLI** | PTY-capable `execute_command` with stdin, timeout, stdout/stderr, exit code |
-| **Browser** | Navigate, click, type, extract, screenshot, evaluate JavaScript |
-| **Android** | UI observation, input, screenshots, app launch, intent launch, APK install, `adb shell` |
-| **Web search** | Brave Search API |
-| **Files** | Read, write, edit, list, search |
-| **HTTP** | Direct requests |
-| **Memory** | Semantic search, session search, daily logs, core memory, API key name lookup |
-| **Skills** | Create, list, update, delete persistent skills |
-| **Tasks** | Create, update, delete, and one-time run automations |
-| **MCP** | Add/remove MCP servers, use dynamic MCP tools |
-| **Subagents** | Spawn, wait for, and cancel async helpers inside a run |
-| **Images** | Generate with Grok, analyze with vision models |
-| **Recordings** | List, inspect, search transcripts |
-| **Social video** | Extract transcript and metadata from public YouTube, TikTok, Instagram, and X URLs |
-| **Health** | Read synced mobile health metrics and summaries |
-| **Outputs** | Markdown tables, Mermaid graphs, downloadable artifacts |
+## Run unattended work
 
-## Android Control
+- [Automation and triggers](automation.md)
+- [Security and permissions](security-boundaries.md)
+- [Operations and troubleshooting](operations.md)
 
-The agent operates Android — it is not an app that runs on Android. Controls run on a server-attached emulator or physical device over ADB.
-
-- Start and stop the managed emulator
-- List connected devices and installed apps
-- Screenshot and UIAutomator XML dump
-- Observe visible UI nodes
-- Open apps and launch Android intents
-- Tap, long press, type, swipe, press navigation keys
-- Wait for text, resource IDs, descriptions, or classes to appear
-- Install `.apk` and `.apks` bundles
-- Run `adb shell` commands directly
-
-These actions run on the NeoAgent server. If NeoAgent is deployed remotely, it controls the Android runtime on that machine — not your local device.
-
-## Recordings
-
-Audio sessions are recorded server-side. The web client captures browser microphone and screen audio; the Android app records phone microphone audio via a foreground service.
-
-- Chunked uploads with per-source sequence tracking
-- Session statuses: recording, processing, completed, failed, cancelled
-- Transcript segment retry and deletion
-- Transcript search across sessions
-- Agent tools: `recordings_list`, `recordings_get`, `recordings_search`
-- Social video extraction via `social_video_extract` — title, description, transcript, and a representative frame from YouTube, TikTok, Instagram, and X URLs
-
-Transcription uses Deepgram (`nova-3` model, multi-language by default). Enable `auto_recording_insights` in AI settings to generate summaries, action items, and events automatically after transcription.
-
-## Runtime Modes
-
-| Setting | What runs where |
-|---|---|
-| Default | Browser and CLI run in a per-user isolated runtime; Android runs on the host over ADB |
-| Paired browser extension | Browser actions run in the paired Chrome profile |
-| Desktop CLI backend | Shell commands run on the paired desktop with the companion process's permissions |
-
-The stored runtime profile is normalized to `secure-vm`, but that name does not
-mean every NeoAgent capability runs in a VM. In particular, Android, workspace
-file tools, memory, integrations, messaging, and MCP orchestration remain
-server-side. See [Security Boundaries](security-boundaries.md) for the enforced
-boundaries and current limitations.
-
-The default browser runs in the isolated runtime. A paired Chrome extension is
-an alternative backend, not an isolation boundary: it grants NeoAgent control
-of that browser profile on the paired machine. To pair an extension: download
-`/api/browser-extension/download` from NeoAgent, unzip it, enable Developer
-Mode in `chrome://extensions`, load the folder, then pair after signing in.
-
-## Integrations and Messaging
-
-NeoAgent has two separate layers:
-
-**Official integrations** — structured OAuth-backed tools the agent can use:
-
-| Provider | Tools |
-|---|---|
-| Google Workspace | Gmail, Calendar, Drive, Docs, Sheets |
-| Microsoft 365 | Outlook, Calendar, OneDrive, Teams |
-| Notion | Pages, databases, blocks, search |
-| Slack | Messages, conversations, search |
-| Figma | Files, nodes, comments, rendered images |
-| Home Assistant | Entity state, service calls |
-| Trello | Boards, lists, cards, comments |
-| Spotify | Playback, search, queue |
-| Weather | Current conditions and forecasts (no API key needed) |
-| Personal WhatsApp | Per-account read and send |
-
-**Messaging platforms** — channels for communicating with the agent:
-
-WhatsApp, Telegram, Discord, Slack, Google Chat, Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, Telnyx Voice, plus webhook bridges for Feishu, Nextcloud Talk, Nostr, Synology Chat, Tlon, Zalo, WeChat, and WebChat.
-
-Each official integration account can be set to **Read/Write** (default) or **Read Only**. Write tools are blocked server-side for read-only accounts.
-
-## Android App and Health
-
-The Flutter Android app connects to the same self-hosted backend and can:
-
-- Run chat and operator UI
-- Sync Android Health Connect data (steps, heart rate, sleep, exercise, weight)
-- Record microphone audio via a foreground service
-
-Synced health data is available through the `read_health_data` agent tool and the **Health** UI section.
+For implementation details, start with [Architecture](architecture.md).

package/docs/clients-and-devices.md

@@ -0,0 +1,43 @@
+# Clients and device bridges
+
+The Flutter project uses one root `ChangeNotifier` and shared feature models
+across web, Android, and desktop targets. Platform-specific side effects are
+implemented through bridge classes and native host code.
+
+## Application modes
+
+The standard mode provides the full NeoAgent client. The launcher mode uses a
+separate Android application ID and enables the home-screen launcher activity,
+hardware-button events, device settings, pairing, and launcher widgets.
+
+Build mode is selected at compile time. Release artifacts distinguish standard
+and launcher APKs.
+
+## Backend communication
+
+The backend client wraps authenticated HTTP calls. Socket.IO streams chat
+tokens, run events, approvals, messaging events, device state, and operational
+updates into `MainController`, which notifies the relevant UI.
+
+## Android bridges
+
+Native Kotlin code handles Health Connect, background recording,
+notifications, launcher functions, telecom integration, and Android home
+widgets. Flutter bridges normalize permission and lifecycle behavior before
+updating application state.
+
+## Desktop and Chrome pairing
+
+Desktop companions and browser extensions authenticate with the server and
+register under the owning user. The runtime manager chooses them only when the
+user has selected that backend and the registered device is online.
+
+The Chrome extension uses the protocol in
+`extensions/chrome-browser/protocol.mjs`. Protocol changes require matching
+updates to the extension and backend gateway.
+
+## ADB device control
+
+ADB control is a server capability exposed through the Android service and
+routes. It is independent of the Flutter Android client and can target an
+emulator or physical device attached to the NeoAgent host.

package/docs/configuration.md

@@ -1,141 +1,128 @@
-# Configuration
+# Configuration reference
 
-NeoAgent reads server config from `~/.neoagent/.env`. Run `neoagent setup` to generate or update it interactively. Set `NEOAGENT_HOME` to move the runtime root.
+NeoAgent reads server configuration from `~/.neoagent/.env`. Set
+`NEOAGENT_HOME` before installation to use another runtime root.
 
-All AI provider credentials, OAuth client secrets, and deployment settings are server-side only — never sent to the client or exposed in the UI.
+Prefer the setup wizard or environment CLI over manual file edits:
 
-## Admin Dashboard
-
-The admin dashboard at `/admin` provides a web UI for operator tasks including AI provider key management, server logs, and runtime updates. Credentials are generated during `neoagent setup` (or run `neoagent admin` to view them).
-
-Navigate to **Providers** in the sidebar to set or rotate API keys without editing `.env` manually — changes take effect immediately without a server restart.
-
-## Minimal Config
-
-```dotenv
-PORT=3333
-SESSION_SECRET=change-me-to-something-random
-ANTHROPIC_API_KEY=sk-ant-...
+```bash
+neoagent setup
+neoagent env list
 ```
 
-Generate a session secret: `openssl rand -hex 32`
+Use `neoagent env set` or `neoagent env unset` with the variable named in the
+tables below. Restart NeoAgent after changing values that are only read during
+startup.
 
-## Core Variables
+## Core server
 
-| Variable | Default | Description |
-|---|---:|---|
-| `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` |
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `3333` | HTTP port |
+| `PUBLIC_URL` | unset | Public HTTPS base URL for remote clients, OAuth, and webhooks |
+| `SESSION_SECRET` | required | Session-signing secret |
+| `NODE_ENV` | `production` | Node environment |
+| `SECURE_COOKIES` | inferred | Require secure session cookies |
+| `TRUST_PROXY` | inferred | Trust proxy headers from the deployment proxy |
+| `ALLOWED_ORIGINS` | unset | Additional comma-separated CORS origins |
+| `NEOAGENT_PROFILE` | `prod` | Deployment/runtime policy profile |
+| `NEOAGENT_RELEASE_CHANNEL` | `stable` | Update channel |
 
-## AI Providers
+Generate a session secret before setting it:
 
-At least one key is required unless you only use local Ollama.
+```bash
+neoagent env set SESSION_SECRET "$(openssl rand -hex 32)"
+```
+
+## Model providers
 
-| Variable | Provider |
+| Variable | Provider or feature |
 |---|---|
-| `ANTHROPIC_API_KEY` | Claude (Anthropic) |
-| `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) |
-| `MINIMAX_API_KEY` | MiniMax (including `MiniMax-M2.7`) |
-| `NVIDIA_API_KEY` | NVIDIA NIM (free-tier + paid: Nemotron, Kimi, Llama 4, DeepSeek, etc.) |
-| `OPENROUTER_API_KEY` | OpenRouter — access 300+ models from all providers through one API; free-tier models included |
-| `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 |
+| `ANTHROPIC_API_KEY` | Anthropic |
+| `OPENAI_API_KEY` | OpenAI and supported embedding/transcription paths |
+| `GOOGLE_AI_KEY` | Google Gemini and supported embeddings |
+| `XAI_API_KEY` | xAI |
+| `MINIMAX_API_KEY` | MiniMax |
+| `NVIDIA_API_KEY` | NVIDIA NIM |
+| `OPENROUTER_API_KEY` | OpenRouter |
+| `OPENAI_BASE_URL` | OpenAI-compatible base URL override |
+| `ANTHROPIC_BASE_URL` | Anthropic-compatible base URL override |
+| `OLLAMA_URL` | Ollama server URL |
+| `BRAVE_SEARCH_API_KEY` | Web search |
 | `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` |
+| `DEEPGRAM_BASE_URL` | Deepgram-compatible base URL override |
+| `DEEPGRAM_MODEL` | Speech model |
+| `DEEPGRAM_LANGUAGE` | Speech language mode |
 
-## Official Integrations
+Account-backed model providers use `neoagent login`, not these API-key fields.
 
-OAuth app credentials for structured agent tools. All callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback`.
+## Official integrations
 
-Home Assistant and Trello can be configured per-user in the Flutter UI without any server-side setup.
-
-| Variable | Description |
+| Variable prefix | Integration |
 |---|---|
-| `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 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 client ID |
-| `FIGMA_OAUTH_CLIENT_SECRET` | Figma client secret |
-| `FIGMA_OAUTH_REDIRECT_URI` | Optional Figma OAuth callback URL |
-| `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 |
-
-## Messaging
-
-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.
-
-| Variable | Description |
+| `GOOGLE_OAUTH_` | Google Workspace |
+| `MICROSOFT_OAUTH_` | Microsoft 365 |
+| `GITHUB_OAUTH_` | GitHub |
+| `NOTION_OAUTH_` | Notion |
+| `SLACK_OAUTH_` | Slack |
+| `FIGMA_OAUTH_` | Figma |
+| `SPOTIFY_OAUTH_` | Spotify |
+| `TRELLO_API_KEY` | Shared Trello application key |
+
+OAuth providers generally use a client ID, client secret, and optional redirect
+URI. The default callback is
+`PUBLIC_URL/api/integrations/oauth/callback`. Home Assistant and personal
+Trello credentials are configured through the application.
+
+## Service email
+
+SMTP is optional. When configured, it supports account confirmation, password
+reset, email changes, and security notifications.
+
+| Variable | Purpose |
 |---|---|
-| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
-
-Generic inbound webhook path: `PUBLIC_URL + /api/messaging/webhook/:platform`
-
-## Service Email
-
-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_PUBLIC_URL` | `PUBLIC_URL` | Public base URL used in confirmation and reset links |
-| `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | `24` | Confirmation link expiry |
-
-## Runtime Isolation
-
-| Variable | Description |
+| `NEOAGENT_EMAIL_FROM` | Sender address |
+| `NEOAGENT_EMAIL_SMTP_HOST` | SMTP host |
+| `NEOAGENT_EMAIL_SMTP_PORT` | SMTP port |
+| `NEOAGENT_EMAIL_SMTP_USER` | SMTP user |
+| `NEOAGENT_EMAIL_SMTP_PASS` | SMTP password |
+| `NEOAGENT_EMAIL_SMTP_SECURE` | Implicit TLS |
+| `NEOAGENT_EMAIL_SMTP_REQUIRE_TLS` | Require STARTTLS |
+| `NEOAGENT_EMAIL_SMTP_REJECT_UNAUTHORIZED` | Reject invalid certificates |
+| `NEOAGENT_EMAIL_REPLY_TO` | Reply-To address |
+| `NEOAGENT_EMAIL_REQUIRE_SIGNUP_CONFIRMATION` | Confirm new accounts |
+| `NEOAGENT_EMAIL_REQUIRE_EMAIL_CHANGE_CONFIRMATION` | Confirm email changes |
+| `NEOAGENT_EMAIL_NOTIFY_UNUSUAL_LOGIN` | Notify on unusual login |
+| `NEOAGENT_EMAIL_NOTIFY_ACCOUNT_CHANGES` | Notify on account changes |
+| `NEOAGENT_EMAIL_PUBLIC_URL` | Base URL used in email links |
+| `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | Confirmation token lifetime |
+
+## Isolated runtime
+
+| Variable | Purpose |
 |---|---|
-| `NEOAGENT_VM_GUEST_TOKEN` | Required for `secure-vm` policy — use 32+ characters, no placeholder values |
+| `NEOAGENT_VM_BASE_IMAGE_URL` | Download source for the guest image |
+| `NEOAGENT_VM_BASE_IMAGE` | Existing local guest image |
+| `NEOAGENT_VM_GUEST_TOKEN` | Server-to-runtime authentication token |
+| `NEOAGENT_VM_MEMORY_MB` | Guest memory allocation |
+| `NEOAGENT_VM_CPUS` | Guest CPU allocation |
 
-Runtime profiles (`trusted-host`, `secure-vm`) are set in user settings, not `.env`. See [Capabilities: Runtime Modes](capabilities.md#runtime-modes).
+The installer generates the guest token. Do not reuse the example values from
+documentation or issue reports.
 
-## Runtime Paths
+## Messaging
+
+Messaging credentials are normally configured in **Settings > Messaging**.
+`TELNYX_WEBHOOK_TOKEN` remains a server environment value for Telnyx webhook
+verification.
+
+## Runtime paths
 
 | Path | Contents |
 |---|---|
-| `~/.neoagent/.env` | Server config and secrets |
-| `~/.neoagent/data/` | Database, sessions, logs, update status |
-| `~/.neoagent/agent-data/` | Skills, memory, daily data |
-
-## Security
+| `~/.neoagent/.env` | Configuration and secrets |
+| `~/.neoagent/data/` | Database, sessions, logs, update state |
+| `~/.neoagent/agent-data/` | Skills, memory files, daily data |
 
-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.
+The canonical complete variable list and comments are in
+[`.env.example`](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/.env.example).

package/docs/development.md

@@ -0,0 +1,82 @@
+# Development and testing
+
+Read
+[GUIDELINES.md](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/GUIDELINES.md)
+before changing code. It defines module boundaries, security requirements,
+naming, and project-specific constraints.
+
+## Setup
+
+```bash
+git clone https://github.com/NeoLabs-Systems/NeoAgent.git
+cd NeoAgent
+npm ci
+npm run dev:backend
+```
+
+Use a separate `NEOAGENT_HOME` when development data must not share the normal
+installation.
+
+Run the backend and Flutter web development client with:
+
+```bash
+npm run dev:stack
+```
+
+Do not run a Flutter web release build during normal development. The release
+pipeline and maintainer own that artifact.
+
+## Server conventions
+
+- Keep Express routes limited to request parsing and response handling.
+- Put business logic in domain services.
+- Use CommonJS and start new server files with `'use strict';`.
+- Route all database access through the shared database module.
+- Route all model calls through the AI engine and provider layer.
+- Use runtime path helpers and the shared logger.
+- Validate external and user-supplied data at system boundaries.
+
+## Tests
+
+Run the smallest relevant suite while working:
+
+```bash
+npm run test:unit
+npm run test:integration
+npm run test:security
+npm run test:contract
+npm run test:e2e
+npm run test:ws
+```
+
+Run the complete backend suite before submitting:
+
+```bash
+npm run test:backend
+```
+
+Flutter changes use:
+
+```bash
+cd flutter_app
+flutter analyze --no-pub
+cd ..
+npm run flutter:test
+```
+
+Documentation changes use:
+
+```bash
+npm run docs:build
+npm run docs:dev
+```
+
+The Docusaurus build treats broken routes as errors. Check both desktop and
+narrow layouts after changing navigation, tables, or images.
+
+## Contributions
+
+Contributor pull requests target `beta`. Keep changes focused, include tests
+for behavior changes, document new commands and settings, and never commit
+runtime data or credentials. See
+[CONTRIBUTING.md](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/CONTRIBUTING.md).

package/docs/devices.md

@@ -0,0 +1,62 @@
+# Devices and interfaces
+
+NeoAgent clients connect to one self-hosted server. A client interface does not
+move the server-side data or tools onto that client unless a device is
+explicitly paired as a runtime backend.
+
+## Web interface
+
+The web interface provides chat, runs, tasks, agents, integrations, memory,
+devices, recordings, health, settings, permissions, and logs. It is served by
+the NeoAgent backend.
+
+## Android app
+
+The Android app connects to the same backend and adds:
+
+- Health Connect synchronization
+- Background microphone recording
+- Android notification forwarding
+- Native notifications and device pairing
+
+The normal Android app is distinct from the Android device that the agent
+controls over ADB.
+
+## Launcher mode
+
+NeoAgent also has an Android launcher build. It provides an integrated home
+experience, pairing, device controls, AI widgets, and hardware-button
+integration. Launcher releases use a separate application package from the
+standard Android client.
+
+## Desktop companion
+
+The Flutter desktop client can pair with a server. When selected in settings,
+shell and desktop-control actions run on the paired desktop with that user's
+permissions. Pair only a machine and OS account that the agent is allowed to
+operate.
+
+## Chrome extension
+
+The bundled extension pairs a Chrome profile with NeoAgent. Browser actions can
+then run in that profile instead of the isolated server browser.
+
+Download the extension from `/api/browser-extension/download`, load the
+unpacked directory through `chrome://extensions`, and pair it after signing in.
+Use a dedicated browser profile because pairing grants the agent access to its
+open sessions and sites.
+
+## Android control
+
+NeoAgent controls a server-attached emulator or physical Android device over
+ADB. The agent can inspect screenshots and UI nodes, tap, swipe, type, launch
+apps and intents, install application bundles, and run `adb shell`.
+
+If NeoAgent runs on a remote server, it controls the Android device attached to
+that server, not the phone displaying the NeoAgent client.
+
+## Wearable firmware
+
+The repository includes an ESP-IDF firmware target for the Waveshare ESP32-S3
+Touch AMOLED 1.8 board. This is a source-level hardware target, not part of the
+npm installer. See [Hardware](hardware.md).