From e3c24fc10bc358370706b4941202c26a28559765 Mon Sep 17 00:00:00 2001
From: Naiyuan Qing <145280634+NevilleQingNY@users.noreply.github.com>
Date: Fri, 13 Feb 2026 14:33:48 +0800
Subject: [PATCH] chore(desktop): add deep link protocol and build scripts

- Add multica:// protocol for macOS and Windows (production login)
- Add build:staging and build:production scripts
- Update env vars: remove MULTICA_URL, add WEB_URL
- Update README with environment configuration docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md                               | 34 +++++++++++++++++++++++--
 apps/desktop/.env.example               | 17 +++++--------
 apps/desktop/electron-builder.json5     | 14 +++++++++-
 apps/desktop/package.json               |  2 ++
 apps/desktop/src/main/electron-env.d.ts |  4 +--
 5 files changed, 56 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 6c68a07f6e..9ff9804542 100644
--- a/README.md
+++ b/README.md
@@ -45,14 +45,44 @@ pnpm install
 # Desktop app (recommended for local development)
 pnpm dev
 
-# Gateway + Web app (for remote/mobile clients)
+# Web app (for browser-based access)
+pnpm dev:web         # Start Web app on :3000
+
+# Gateway (for remote/mobile clients)
 pnpm dev:gateway     # Start Gateway on :3000
-pnpm dev:web         # Start Web app on :3001
 pnpm dev:all         # Start both Gateway and Web app
 ```
 
 The Desktop app runs a standalone Hub with embedded Agent Engine - no Gateway required for local use.
 
+### Environment Configuration
+
+**Desktop** (`apps/desktop/.env.*`):
+
+| Variable | Description |
+|----------|-------------|
+| `MAIN_VITE_GATEWAY_URL` | WebSocket Gateway URL for remote device pairing |
+| `MAIN_VITE_WEB_URL` | Web app URL for OAuth login redirect |
+
+**Web** (`apps/web/next.config.ts`):
+
+| Variable | Description |
+|----------|-------------|
+| `API_URL` | Backend API URL (default: `https://api-dev.copilothub.ai`) |
+
+**Build for different environments:**
+
+```bash
+# Desktop
+pnpm --filter @multica/desktop build              # Production (.env.production)
+pnpm --filter @multica/desktop build:staging      # Staging (.env.staging)
+
+# Web (Vercel)
+# Set API_URL in Vercel Dashboard → Settings → Environment Variables
+```
+
+See `apps/desktop/.env.example` and `apps/web/.env.example` for details.
+
 ### Monorepo Development
 
 | Command | Purpose |
diff --git a/apps/desktop/.env.example b/apps/desktop/.env.example
index d365f352c9..18f56e2144 100644
--- a/apps/desktop/.env.example
+++ b/apps/desktop/.env.example
@@ -3,11 +3,13 @@
 # =============================================================================
 #
 # Local Development:
-#   Just run `pnpm dev` - connects to dev gateway (multica-dev.copilothub.ai)
-#   GATEWAY_URL is hardcoded in root package.json, no .env file needed.
+#   Just run `pnpm dev` - no .env file needed (uses defaults)
+#
+# Staging Build:
+#   `pnpm build:staging` uses .env.staging
 #
 # Production Build:
-#   `pnpm build` uses .env.production automatically
+#   `pnpm build` uses .env.production
 #
 # Variable naming convention:
 #   MAIN_VITE_*       - Main process only (Node.js, full system access)
@@ -20,16 +22,11 @@
 #
 # MAIN_VITE_GATEWAY_URL - WebSocket Gateway
 #   Hub connects to Gateway for remote device access (QR code pairing)
-#   Dev:  multica-dev.copilothub.ai (hardcoded in root package.json)
-#   Prod: see .env.production
 #
-# MAIN_VITE_MULTICA_URL - REST API Server
-#   HTTP requests for authentication, auto-updates, user data sync
-#   Dev:  not yet used
-#   Prod: see .env.production
+# MAIN_VITE_WEB_URL - Web App URL
+#   Desktop opens this URL for user login (OAuth flow)
 #
 # =============================================================================
 
 MAIN_VITE_GATEWAY_URL=http://localhost:3000
-MAIN_VITE_MULTICA_URL=http://localhost:3001
 MAIN_VITE_WEB_URL=http://localhost:3000
diff --git a/apps/desktop/electron-builder.json5 b/apps/desktop/electron-builder.json5
index 0a7de5ff1a..d8fd3ce2c9 100644
--- a/apps/desktop/electron-builder.json5
+++ b/apps/desktop/electron-builder.json5
@@ -28,7 +28,13 @@
       "NSMicrophoneUsageDescription": "Application requests access to the device's microphone.",
       "NSDocumentsFolderUsageDescription": "Application requests access to the user's Documents folder.",
       "NSDownloadsFolderUsageDescription": "Application requests access to the user's Downloads folder."
-    }
+    },
+    "protocols": [
+      {
+        "name": "Multica",
+        "schemes": ["multica"]
+      }
+    ]
   },
   "dmg": {
     "artifactName": "${productName}-${version}-${arch}.${ext}"
@@ -54,6 +60,12 @@
     "uninstallDisplayName": "${productName}",
     "createDesktopShortcut": "always"
   },
+  "protocols": [
+    {
+      "name": "Multica",
+      "schemes": ["multica"]
+    }
+  ],
   "linux": {
     "target": [
       "AppImage",
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 193eaf00e3..4664aa08a1 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -10,6 +10,8 @@
     "dev": "electron-vite dev",
     "dev:onboarding": "electron-vite dev -- --force-onboarding",
     "build": "electron-vite build && electron-builder",
+    "build:staging": "electron-vite build --mode staging && electron-builder",
+    "build:production": "electron-vite build --mode production && electron-builder",
     "preview": "electron-vite preview",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
   },
diff --git a/apps/desktop/src/main/electron-env.d.ts b/apps/desktop/src/main/electron-env.d.ts
index 94137db5bc..0d40ac2beb 100644
--- a/apps/desktop/src/main/electron-env.d.ts
+++ b/apps/desktop/src/main/electron-env.d.ts
@@ -1,10 +1,10 @@
 /// <reference types="vite-plugin-electron/electron-env" />
 
 // Environment variables loaded from .env files
-// See: .env.example, .env.development, .env.staging, .env.production
+// See: .env.example, .env.staging, .env.production
 interface ImportMetaEnv {
   readonly MAIN_VITE_GATEWAY_URL: string
-  readonly MAIN_VITE_MULTICA_URL: string
+  readonly MAIN_VITE_WEB_URL: string
 }
 
 interface ImportMeta {