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

package/docs/migration.md

@@ -6,43 +6,37 @@ sidebar_label: Migration
 
 # Migration Guide
 
-Migrate your existing agent setup from **OpenClaw** or **Hermes** to NeoAgent with a single command.
+Migrate your existing agent setup from OpenClaw or Hermes to NeoAgent with a single command.
 
 ## Quick Start
 
 ```bash
-# Detect existing installations and migrate
-neoagent migrate
-
-# Preview what would be migrated (dry run)
-neoagent migrate dry-run
-
-# Check migration status
-neoagent migrate status
+neoagent migrate           # detect and migrate interactively
+neoagent migrate dry-run   # preview what would be migrated
+neoagent migrate status    # check what's detected
 ```
 
 ## What Gets Migrated
 
-| Data Type | OpenClaw | Hermes | Destination |
-|-----------|----------|--------|-------------|
-| **Skills** | `~/.openclaw/skills/*.md` | `~/.hermes/skills/*.md` | `~/.neoagent/agent-data/skills/openclaw-imports/` or `hermes-imports/` |
-| **Memory** | `SOUL.md`, `MEMORY.md`, `USER.md` | `MEMORY.md`, `USER.md` | `~/.neoagent/agent-data/memory/openclaw/` or `hermes/` |
-| **API Keys** | From `.env` | From `.env` | `~/.neoagent/.env` (merged with prompts on conflict) |
+| Data | OpenClaw source | Hermes source | Destination |
+|---|---|---|---|
+| Skills | `~/.openclaw/skills/*.md` | `~/.hermes/skills/*.md` | `~/.neoagent/agent-data/skills/openclaw-imports/` or `hermes-imports/` |
+| Memory | `SOUL.md`, `MEMORY.md`, `USER.md` | `MEMORY.md`, `USER.md` | `~/.neoagent/agent-data/memory/openclaw/` or `hermes/` |
+| API keys | from `.env` | from `.env` | merged into `~/.neoagent/.env` |
 
 ## Prerequisites
 
-- NeoAgent installed (`npm install -g neoagent`)
-- Existing OpenClaw (at `~/.openclaw/`) and/or Hermes (at `~/.hermes/`) installation
+- NeoAgent installed: `npm install -g neoagent`
+- An existing OpenClaw (`~/.openclaw/`) or Hermes (`~/.hermes/`) installation
 
-## Step-by-Step Migration
+## Running Migration
 
-### 1. Run Migration Detection
+### 1. Check what's detected
 
 ```bash
 neoagent migrate status
 ```
 
-This will show:
 ```
 Source agents:
   OpenClaw: FOUND
@@ -51,13 +45,12 @@ Source agents:
 Run `neoagent migrate` to start migration.
 ```
 
-### 2. Preview Migration (Optional)
+### 2. Preview (optional)
 
 ```bash
 neoagent migrate dry-run
 ```
 
-Sample output:
 ```
 === Migration Dry Run ===
 
@@ -65,13 +58,11 @@ OpenClaw detection: FOUND
   Skills: 5
   Memories: 3
   API keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, TELEGRAM_BOT_TOKEN
-  Config: ~/.openclaw/openclaw.json
 
 Hermes detection: FOUND
   Skills: 3
   Memories: 2
   API keys: OPENAI_API_KEY, XAI_API_KEY
-  Config: ~/.hermes/config.yaml
 
 Would migrate to:
   Skills → ~/.neoagent/agent-data/skills/
@@ -79,60 +70,23 @@ Would migrate to:
   API keys → ~/.neoagent/.env
 ```
 
-### 3. Run Full Migration
+### 3. Migrate
 
 ```bash
 neoagent migrate
 ```
 
-Interactive prompts:
-```
-=== NeoAgent Migration ===
-
-  -> OpenClaw detected at ~/.openclaw/
-  -> Hermes detected at ~/.hermes/
-
-What would you like to migrate?
-  [1] Migrate from all detected sources
-  [2] Migrate from OpenClaw only
-  [3] Migrate from Hermes only
-  [4] Cancel
-
-  Choice [1]: 1
-
-Scanning sources...
-  OpenClaw: 5 skills, 3 memories, 3 API keys
-  Hermes: 3 skills, 2 memories, 2 API keys
-
-Migrating skills and memories...
-  → Copied 5 skills to openclaw-imports/
-  → Copied 3 skills to hermes-imports/
-  → Copied 5 memory files
+The interactive flow asks which sources to migrate and prompts when an API key exists in multiple sources:
 
+```
 ⚠️  API Key conflicts detected:
   OPENAI_API_KEY exists in both sources
-      Existing in: neoagent
-      Incoming from: openclaw
-    [1] Keep existing
-    [2] Overwrite with new
-    [3] Skip this key
-  Choice [1]: 1
-
-Merging API keys...
-  → Merged 4 API keys
-
-=== Migration Complete ===
-
-Skills migrated to:
-  openclaw-imports/
-  hermes-imports/
-
-Memories migrated to:
-  memory/openclaw/
-  memory/hermes/
-
-Run `neoagent status` to verify the installation.
-Run `neoagent start` to start the server.
+    Existing in: neoagent
+    Incoming from: openclaw
+  [1] Keep existing
+  [2] Overwrite with new
+  [3] Skip this key
+Choice [1]:
 ```
 
 ## Source Paths
@@ -140,99 +94,40 @@ Run `neoagent start` to start the server.
 ### OpenClaw
 
 | Data | Path |
-|------|------|
+|---|---|
 | Config | `~/.openclaw/openclaw.json` |
-| Workspace | `~/.openclaw/workspace/` |
 | Skills | `~/.openclaw/skills/` |
-| Memories | `~/.openclaw/workspace/SOUL.md`, `MEMORY.md`, `USER.md` |
+| Memory | `~/.openclaw/workspace/SOUL.md`, `MEMORY.md`, `USER.md` |
 | Legacy | `~/.clawdbot/` |
 
 ### Hermes
 
 | Data | Path |
-|------|------|
+|---|---|
 | Config | `~/.hermes/config.yaml` |
 | Skills | `~/.hermes/skills/` |
-| Memories | `~/.hermes/memories/MEMORY.md`, `USER.md` |
-| API Keys | `~/.hermes/.env` |
+| Memory | `~/.hermes/memories/MEMORY.md`, `USER.md` |
+| API keys | `~/.hermes/.env` |
 
-## Target Paths (NeoAgent)
+## API Keys Detected and Merged
 
-| Data | Path |
-|------|------|
-| Config | `~/.neoagent/.env` |
-| Skills | `~/.neoagent/agent-data/skills/` |
-| Memory | `~/.neoagent/agent-data/memory/` |
-| Database | `~/.neoagent/data/neoagent.db` |
-
-## API Keys Merged
-
-The following API keys are automatically detected and merged:
-
-- `ANTHROPIC_API_KEY`
-- `OPENAI_API_KEY`
-- `XAI_API_KEY`
-- `GOOGLE_AI_KEY`
-- `MINIMAX_API_KEY`
-- `BRAVE_SEARCH_API_KEY`
-- `DEEPGRAM_API_KEY`
-- `TELEGRAM_BOT_TOKEN`
-- `OPENROUTER_API_KEY`
-- `ELEVENLABS_API_KEY`
-- `SLACK_BOT_TOKEN`
-- `DISCORD_BOT_TOKEN`
-
-## Conflict Resolution
-
-When an API key exists in multiple sources (including your existing NeoAgent config), you'll be prompted:
-
-```
-⚠️  Conflict: OPENAI_API_KEY
-    Existing in: neoagent
-    Incoming from: openclaw
-  [1] Keep existing
-  [2] Overwrite with new
-  [3] Skip this key
-```
-
-Choose `1` to keep the NeoAgent value, `2` to overwrite with the imported value, or `3` to skip entirely.
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `GOOGLE_AI_KEY`, `MINIMAX_API_KEY`, `BRAVE_SEARCH_API_KEY`, `DEEPGRAM_API_KEY`, `TELEGRAM_BOT_TOKEN`, `OPENROUTER_API_KEY`, `ELEVENLABS_API_KEY`, `SLACK_BOT_TOKEN`, `DISCORD_BOT_TOKEN`
 
 ## Post-Migration Steps
 
-1. **Verify installation**: `neoagent status`
-2. **Start server**: `neoagent start`
-3. **Review imported skills**: Check `~/.neoagent/agent-data/skills/openclaw-imports/` and `hermes-imports/`
-4. **Review imported memories**: Check `~/.neoagent/agent-data/memory/`
-5. **Configure messaging channels**: If you had Telegram/Discord configured, verify settings in the NeoAgent UI
+1. `neoagent status` — verify the installation
+2. `neoagent start` — start the server
+3. Review imported skills in `~/.neoagent/agent-data/skills/openclaw-imports/` and `hermes-imports/`
+4. Review imported memory in `~/.neoagent/agent-data/memory/`
+5. Reconfigure messaging channels in the NeoAgent UI if you had Telegram or Discord set up
 
 ## Troubleshooting
 
-### "No OpenClaw or Hermes installation detected"
-
-Ensure your existing installation is at the default path (`~/.openclaw/` or `~/.hermes/`). If it's at a custom path, you can manually copy the data:
-- Skills: Copy `.md` files to `~/.neoagent/agent-data/skills/`
-- Memories: Copy to `~/.neoagent/agent-data/memory/`
-- API keys: Merge into `~/.neoagent/.env`
-
-### "Permission denied" errors
-
-Ensure you have read permissions on the source directories and write permissions on `~/.neoagent/`.
-
-### Migration partially failed
-
-The migration is designed to be idempotent - you can re-run it. Only new files are copied; existing files are not overwritten.
-
-## Manual Migration
-
-If the automated migration doesn't work for your setup:
-
-1. **Skills**: Copy skill `.md` files from source `skills/` directory to `~/.neoagent/agent-data/skills/[source]-imports/`
-2. **Memory**: Copy `SOUL.md`, `MEMORY.md`, `USER.md` to `~/.neoagent/agent-data/memory/[source]/`
-3. **API Keys**: Edit `~/.neoagent/.env` and add keys from source `.env` file
+**"No OpenClaw or Hermes installation detected"** — Installation must be at the default path. If it's elsewhere, migrate manually:
+- Copy `.md` skill files to `~/.neoagent/agent-data/skills/`
+- Copy memory files to `~/.neoagent/agent-data/memory/`
+- Merge API keys into `~/.neoagent/.env`
 
-## Getting Help
+**"Permission denied" errors** — Check read permissions on source directories and write permissions on `~/.neoagent/`.
 
-If you encounter issues:
-- Run `neoagent status` to check NeoAgent health
-- Run `neoagent logs` to view logs
-- Run `neoagent doctor` to diagnose issues
+**Migration partially completed** — Safe to re-run. Only new files are copied; existing files are not overwritten.

package/docs/operations.md

@@ -1,36 +1,28 @@
 # Operations
 
-NeoAgent is a self-hosted service, so operations are part of the product. The CLI exposes the common service, release, and recovery tasks.
-
 ## Service State
 
 ```bash
-neoagent status
-neoagent logs
+neoagent status      # install root, config path, runtime paths, release channel, service state
+neoagent logs        # first stop for unexpected behavior in UI, messaging, OAuth, or tasks
 neoagent restart
 ```
 
-`neoagent status` reports the install root, config path, runtime data paths, release channel, and service state. `neoagent logs` is the first place to look when the service starts but the UI, messaging, OAuth, or tasks behave unexpectedly.
-
 ## Release Channels
 
 ```bash
-neoagent channel
-neoagent channel stable
-neoagent channel beta
+neoagent channel           # show current channel
+neoagent channel stable    # switch to stable releases (recommended for most installs)
+neoagent channel beta      # switch to prerelease builds
 ```
 
-The release channel controls what `neoagent update` follows. Use `stable` for normal self-hosted installs and `beta` when you intentionally want prerelease builds.
-
 ## Updates
 
 ```bash
 neoagent update
 ```
 
-On git installs, the updater follows the channel branch policy and reinstalls dependencies if the source changes. On npm installs, it attempts a global package reinstall from the matching npm tag.
-
-After updating, NeoAgent verifies that the bundled web client exists and restarts the service.
+Follows the configured release channel. On git installs, pulls the latest source and reinstalls dependencies when they change. On npm installs, reinstalls the global package from the matching npm tag. Verifies the bundled web client and restarts the service.
 
 ## Recovery
 
@@ -38,21 +30,32 @@ After updating, NeoAgent verifies that the bundled web client exists and restart
 neoagent fix
 ```
 
-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.
+Use when NeoAgent is in a broken state after a self-edit or corrupted install. On git installs: backs up runtime data, saves local tracked changes, resets source files, reinstalls dependencies, and restarts.
 
-If the failure is configuration-only, rerun:
+For configuration-only issues:
 
 ```bash
 neoagent setup
 neoagent restart
 ```
 
+## Troubleshooting
+
+| Symptom | First step |
+|---|---|
+| Service won't start | `neoagent logs` — look for startup errors |
+| UI loads but agent doesn't respond | Confirm an AI provider key is set in **Settings → AI Providers** |
+| OAuth integration fails | Confirm `PUBLIC_URL` is reachable and the redirect URI matches |
+| Messaging not delivering | Check credentials in the messaging tab; confirm `PUBLIC_URL` for webhook-based platforms |
+| Tasks not running | Confirm the task is enabled; check **Runs** and **Logs** for error output |
+| Broken after update | `neoagent fix` — resets source, reinstalls, restarts |
+
 ## Runtime Data
 
-| Path | Purpose |
+| Path | Contents |
 |---|---|
 | `~/.neoagent/.env` | Server config and secrets |
-| `~/.neoagent/data/` | Database, session data, logs, and update status |
-| `~/.neoagent/agent-data/` | Skills, memory, and daily data |
+| `~/.neoagent/data/` | Database, session data, logs, update status |
+| `~/.neoagent/agent-data/` | Skills, memory, daily data |
 
-Back up these paths before moving a server or doing manual repair work.
+Back up these paths before moving a server or doing manual repairs.

package/docs/skills.md

@@ -1,16 +1,16 @@
 # Skills
 
-Skills are Markdown files that teach the agent how to use local capabilities or follow a workflow. NeoAgent loads them at runtime from `~/.neoagent/agent-data/skills/` by default, so edits do not require a service restart.
+Skills are Markdown files that instruct the agent on how to use a local capability or follow a multi-step workflow. They load at runtime from `~/.neoagent/agent-data/skills/`, so edits take effect without restarting the service.
 
 ## Built-in Skills
 
 | Skill | Description |
 |---|---|
-| `browser.md` | Puppeteer-powered web browsing and scraping |
-| `cli.md` | Execute shell commands in a persistent terminal |
-| `files.md` | Read, write, and search files on the host |
-| `memory.md` | Store and recall long-term memories |
-| `messaging.md` | Send messages via connected messaging platforms such as WhatsApp, Telegram, Discord, Slack, Matrix, Teams, Google Chat, or webhook bridges |
+| `browser.md` | Web browsing and scraping with Puppeteer |
+| `cli.md` | Shell commands in a persistent PTY terminal |
+| `files.md` | Read, write, and search host files |
+| `memory.md` | Store and recall long-term facts |
+| `messaging.md` | Send via Telegram, WhatsApp, Discord, Slack, Matrix, Teams, Google Chat, or webhooks |
 | `system-stats.md` | CPU, memory, and disk usage |
 | `weather.md` | Current weather via wttr.in |
 | `ip-info.md` | Public IP and geolocation |
@@ -21,16 +21,16 @@ Skills are Markdown files that teach the agent how to use local capabilities or
 | `find-large-files.md` | Locate large files |
 | `docker-status.md` | Docker container status |
 | `tail-log.md` | Tail any log file |
-| `news-hackernews.md` | Fetch Hacker News top stories |
+| `news-hackernews.md` | Fetch top Hacker News stories |
 | `qr-code.md` | Generate QR codes |
-| `pdf-toolkit.md` | Inspect, extract, merge, split, and compress PDF files |
+| `pdf-toolkit.md` | Inspect, extract, merge, split, compress PDFs |
 | `git-summary.md` | Summarize git status, branches, commits, and diffs |
-| `csv-toolkit.md` | Inspect and transform CSV or TSV data files |
-| `markdown-workbench.md` | Clean up, outline, and convert Markdown notes or docs |
+| `csv-toolkit.md` | Inspect and transform CSV or TSV files |
+| `markdown-workbench.md` | Clean up, outline, and convert Markdown documents |
 
-## Adding a Skill
+## Creating a Custom Skill
 
-Create a Markdown file in `~/.neoagent/agent-data/skills/`:
+Add a Markdown file to `~/.neoagent/agent-data/skills/`:
 
 ```markdown
 # My Skill Name
@@ -39,21 +39,21 @@ Brief description of what this skill does and when to use it.
 
 ## Usage
 
-Explain the steps or commands the agent should follow.
+Step-by-step instructions or exact commands the agent should follow.
 ```
 
-The agent reads all `.md` files in the skills directory on each conversation turn. Keep each skill focused, include exact commands or tool names when they matter, and avoid storing secrets in skill files.
+The agent reads all `.md` files in the skills directory on each turn. Keep skills focused. Include exact tool names or shell commands when precision matters. Don't store secrets in skill files.
+
+**When to use a custom skill** — repeated workflows involving specific local paths, commands, or multi-step procedures. For connecting to third-party services, prefer official integrations or MCP tools instead.
 
 ## Skill Store
 
-The **Skills** section also exposes a built-in catalog through `/api/store`. Catalog entries install into the same runtime skills directory, so they stay GitHub-readable Markdown files and can be edited or removed after installation.
+The **Skills** section in the UI includes a built-in catalog from `/api/store`. Skills install as Markdown files into the runtime skills directory — editable and removable after installation.
 
-The catalog includes system, network, info, document, data, and git helpers such as disk usage, process monitoring, tail logs, finding large files, ping, DNS lookup, SSL certificate checks, weather, crypto prices, PDFs, CSV or TSV data, Markdown cleanup, and git summaries.
+Catalog categories: system, network, info, document, data, and git helpers.
 
 ## MCP Tools
 
-External tools are connected via the [Model Context Protocol](https://modelcontextprotocol.io). Configure MCP servers in the Flutter app under **Models / Settings -> MCP**. Connected tools appear alongside built-in skills automatically.
-
-Use official integrations or structured MCP tools when they exist. They are usually safer and more reliable than browser automation or shell scraping.
+External tools connect via the [Model Context Protocol](https://modelcontextprotocol.io). Configure MCP servers in **Settings → MCP**. Connected tools appear alongside built-in skills automatically.
 
-See [Capabilities](capabilities.md) for the broader built-in agent tool surface beyond Markdown skills.
+Use official integrations or MCP tools when they exist — they are more reliable than browser automation or shell scraping and easier to audit.

package/docs/why-neoagent.md

@@ -1,19 +1,21 @@
 # Why NeoAgent
 
-NeoAgent is not trying to beat OpenClaw at every surface. OpenClaw is broader. NeoAgent is better if you want a focused self-hosted server where the AI can operate a server-attached Android emulator or device, use recordings and health data, keep credentials server-side, and stay on a smaller set of common messaging paths.
+NeoAgent is the right choice if you want a focused self-hosted agent with real Android device control, recordings, health data, and a practical operator UI. OpenClaw covers more platforms but is a different kind of product.
 
-This comparison is based on the public [OpenClaw README](https://raw.githubusercontent.com/openclaw/openclaw/main/README.md) checked on April 7, 2026 and the current NeoAgent repository behavior.
+This comparison is based on the public [OpenClaw README](https://raw.githubusercontent.com/openclaw/openclaw/main/README.md) as of April 7, 2026 and the current NeoAgent repository.
 
-| Category | NeoAgent | OpenClaw |
+| | NeoAgent | OpenClaw |
 |---|---|---|
-| Best fit | A focused personal automation server with Android device control, recordings, health data, and built-in operator controls. | A broad personal assistant gateway with many channels, nodes, and companion surfaces. |
-| Setup shape | `npm install -g neoagent` followed by `neoagent install`. | `openclaw onboard` is the preferred guided setup path. |
-| Architecture | Self-hosted Node server, SQLite runtime data, built-in web UI, Android client, server-side credentials. | Gateway control plane with channel connections, optional apps/nodes, and a much wider platform surface. |
-| Android control | AI control of a server-attached Android emulator or device: screenshots, UI dumps, visible node inspection, app launch, intent launch, taps, long press, typing, swipes, key presses, wait-for-element, APK installs, and `adb shell`. | Broader node/app ecosystem with Android node capabilities documented publicly. |
-| Messaging breadth | Broad built-in messaging tab coverage: WhatsApp, Telegram, Discord, Slack, Google Chat, Signal, iMessage/BlueBubbles, IRC, Teams, Matrix, LINE, Mattermost, Twitch, and configurable webhook bridges for Feishu, Nextcloud Talk, Nostr, Synology Chat, Tlon, Zalo, WeChat, and WebChat, plus Telnyx Voice. | Still broader as a gateway ecosystem: the public README lists the same major channels plus a larger channel/node/app surface around them. |
-| Operator UX | Built-in UI sections for chat, runs, logs, tasks, skills, integrations, MCP, memory, devices, recordings, health, and settings. | Broader gateway, web, canvas, platform, node, and channel surfaces. |
-| Credentials | AI provider keys and OAuth client secrets are server-side; channel settings are stored through the app where supported. | Public docs describe a broader config and auth surface across gateway, channels, nodes, and apps. |
-| Automation | Trigger-based tasks, one-time runs, browser/file/CLI skills, MCP tools, official integrations, subagents, recording search, health summaries, and messaging delivery. | Broader automation platform including cron, webhooks, nodes, and channel-specific actions. |
-| Recovery | CLI-first service operations: `neoagent status`, `neoagent logs`, release channels, `neoagent update`, and `neoagent fix`. | Public README highlights onboarding, updating, and doctor-style diagnostics. |
+| **Best for** | Personal automation server with Android control, recordings, and health data | Broad AI gateway with many channels, nodes, and companion surfaces |
+| **Setup** | `npm install -g neoagent && neoagent install` | `openclaw onboard` guided setup |
+| **Architecture** | Self-hosted Node server, SQLite, bundled web UI, server-side credentials | Gateway control plane with channels, optional nodes, wider platform surface |
+| **Android control** | Full AI control: screenshots, UI dumps, tap, swipe, type, intent launch, APK install, `adb shell` | Android node capabilities via the node ecosystem |
+| **Messaging** | 15+ platforms built-in — Telegram, WhatsApp, Discord, Slack, Signal, Matrix, iMessage, Teams, IRC, LINE, Mattermost, Telnyx Voice, webhook bridges | Larger channel/node ecosystem |
+| **Operator UI** | Chat, runs, logs, tasks, skills, integrations, MCP, memory, devices, recordings, health, settings | Gateway, canvas, platform, node, and channel surfaces |
+| **Credentials** | All secrets server-side; channel settings stored through the app | Broader config surface across gateway, channels, and nodes |
+| **Automation** | Cron tasks, integration triggers, browser/CLI skills, MCP, subagents, recording search, health summaries, messaging delivery | Cron, webhooks, nodes, channel-specific actions |
+| **Recovery** | `neoagent status`, `neoagent logs`, `neoagent update`, `neoagent fix` | Doctor-style diagnostics plus channel/node tooling |
 
-Choose NeoAgent when you want the shortest path to a self-hosted proactive agent with a practical operator UI. Choose OpenClaw when you need maximum channel coverage, gateway/node architecture, or the larger companion-app ecosystem.
+**Choose NeoAgent** when you want the shortest path to a self-hosted proactive agent with Android control and a practical operator UI.
+
+**Choose OpenClaw** when you need maximum channel coverage, a gateway/node architecture, or the larger companion-app ecosystem.

package/extensions/chrome-browser/background.mjs

@@ -40,6 +40,9 @@ async function resolveServerUrl(preferred) {
 function websocketUrl(serverUrl, token) {
   const url = new URL('/api/browser-extension/ws', serverUrl);
   url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  // Token in the URL is required for the HTTP upgrade handshake; the browser
+  // WebSocket API does not support custom headers. Ensure the server's access
+  // log scrubs query strings on this path to avoid persisting the token.
   url.searchParams.set('token', token);
   return url.toString();
 }
@@ -192,14 +195,19 @@ async function startPairing(serverUrl) {
   });
   const payload = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(payload.error || `Pairing failed: ${response.status}`);
+  const approvalUrl = String(payload.approvalUrl || '');
+  const approvalParsed = (() => { try { return new URL(approvalUrl); } catch { return null; } })();
+  if (!approvalParsed || !['http:', 'https:'].includes(approvalParsed.protocol)) {
+    throw new Error('Invalid approval URL returned by server.');
+  }
   await setStorage({
     serverUrl: normalized,
     pairingId: payload.pairingId,
     pairingSecret: payload.pairingSecret,
-    approvalUrl: payload.approvalUrl,
+    approvalUrl,
     status: 'approval_pending',
   });
-  await chrome.tabs.create({ url: payload.approvalUrl, active: true });
+  await chrome.tabs.create({ url: approvalUrl, active: true });
   return payload;
 }
 

package/flutter_app/.metadata

@@ -0,0 +1,42 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "ac4e799d237041cf905519190471f657b657155a"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+    - platform: android
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+    - platform: linux
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+    - platform: macos
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+    - platform: web
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+    - platform: windows
+      create_revision: ac4e799d237041cf905519190471f657b657155a
+      base_revision: ac4e799d237041cf905519190471f657b657155a
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'