@conversionpros/aiva 1.0.0

package/docs/network-architecture-rollout-scope.md

@@ -0,0 +1,43 @@
+# Network Architecture Rollout — Policy Gate Model
+
+## Machines to Update
+1. nates-mac-mini (100.95.26.113, user: aiva)
+2. james-mac-mini (100.88.226.81, user: jamesbrown)  
+3. conversion-mac-mini (100.72.95.78, user: brandonburgan)
+
+## Changes Per Machine
+
+### 1. Update openclaw.json agent list
+- Add "assistant" agent as `default: true` with 20m heartbeat
+- Change "main" agent to `default: false`, workspace `~/.openclaw/workspace-main-gate`, 30m heartbeat
+- Keep all other agents (content, email, outreach, peekaboo, research) as-is
+- Reference: `/Users/brandonburgan/.openclaw/workspace/sops/openclaw-config-reference.md`
+
+### 2. Create main gate workspace
+On each machine, create `~/.openclaw/workspace-main-gate/` with:
+- Copy SOUL.md from `/Users/brandonburgan/.openclaw/workspace/templates/client-main-agent/SOUL.md`
+- Copy AGENTS.md from `/Users/brandonburgan/.openclaw/workspace/templates/client-main-agent/AGENTS.md`
+- Create `memory/` directory
+
+### 3. Update assistant workspace
+The existing `~/.openclaw/workspace/` becomes the assistant's workspace. Add/update:
+- Copy SOUL.md from `/Users/brandonburgan/.openclaw/workspace/templates/client-assistant-agent/SOUL.md`
+  BUT preserve any existing USER.md, TOOLS.md, MEMORY.md, IDENTITY.md (machine-specific)
+
+### 4. Restart gateway and verify
+- Restart gateway on each machine
+- Verify both main and assistant agents are running
+- Send test message through each machine's AIVA app: "[System Test After Restart] Architecture update complete. Confirm receipt."
+
+## SSH Access
+- nates-mac-mini: `ssh aiva@100.95.26.113`
+- james-mac-mini: `ssh jamesbrown@100.88.226.81` (password: Basketballev13!)
+- conversion-mac-mini: `ssh brandonburgan@100.72.95.78` (password: CMP2024!)
+
+All have PATH at /opt/homebrew/bin
+
+## IMPORTANT
+- Read the OpenClaw config reference at `sops/openclaw-config-reference.md` before making ANY config changes
+- Make sure the gateway restarts properly after each change
+- If a gateway fails to restart, revert the config change immediately
+- Preserve all existing auth profiles, gateway tokens, and machine-specific settings

package/docs/scope-google-oauth-integration.md

@@ -0,0 +1,351 @@
+# Project Scope: Google OAuth Integration for AIVA App
+
+**Author:** AIVA  
+**Date:** 2026-02-23  
+**Status:** Draft — Pending Brandon's Review  
+
+---
+
+## 1. Overview
+
+### What We're Building
+Native Google OAuth 2.0 integration in the AIVA app, providing centralized email (Gmail) and calendar access through server-side API endpoints.
+
+### Why
+The current approach uses **GOG CLI**, which requires:
+- Per-device installation of the `gog` binary
+- Per-device OAuth browser flow and keyring setup (`GOG_KEYRING_PASSWORD`)
+- Each OpenClaw agent instance to have local filesystem access to credentials
+- Manual re-auth when tokens expire or devices change
+
+This creates friction for multi-device setups and makes the system brittle. The new approach:
+- **Authenticate once** in the AIVA app settings UI
+- **Tokens managed server-side** (encrypted, auto-refreshed)
+- **OpenClaw agents call AIVA API endpoints** instead of local CLI commands
+- **Zero per-device setup** for email and calendar access
+- **Works with both Gmail (personal) and Google Workspace accounts**
+
+---
+
+## 2. Architecture
+
+### 2.1 Google Cloud Console Setup
+
+1. **Create OAuth 2.0 credentials** in the existing Google Cloud project (or a new `aiva-app` project)
+2. **OAuth consent screen** configured as:
+   - App name: "AIVA" (or "AIVA by CMP")
+   - Type: **External** (supports both Gmail and Workspace accounts)
+   - Authorized domains: the AIVA app domain
+3. **OAuth client ID** — type: Web Application
+   - Authorized redirect URI: `https://<aiva-app-domain>/api/integrations/google/callback`
+   - For local dev: `http://localhost:<port>/api/integrations/google/callback`
+4. Store `client_id` and `client_secret` in environment variables (never in code)
+
+### 2.2 OAuth 2.0 Flow (Authorization Code Grant with PKCE)
+
+```
+User clicks "Connect Google Account"
+        │
+        ▼
+Frontend requests → GET /api/integrations/google/auth-url
+        │
+        ▼
+Backend generates:
+  - code_verifier (random 128 chars)
+  - code_challenge = SHA256(code_verifier)
+  - state token (CSRF protection, stored in session)
+  - Returns Google OAuth URL with scopes, redirect_uri, code_challenge
+        │
+        ▼
+User redirected to Google → signs in → grants consent
+        │
+        ▼
+Google redirects to → GET /api/integrations/google/callback?code=...&state=...
+        │
+        ▼
+Backend:
+  1. Validates state token
+  2. Exchanges auth code + code_verifier for access_token + refresh_token
+  3. Fetches user profile (email, name) via Google userinfo endpoint
+  4. Encrypts tokens → stores in oauth-tokens.json
+  5. Redirects user back to settings page with success status
+```
+
+### 2.3 Token Storage
+
+**File:** `oauth-tokens.json` (separate from existing `tokens.json` to avoid coupling)
+
+```json
+{
+  "google": {
+    "accounts": [
+      {
+        "id": "uuid-v4",
+        "email": "brandon@example.com",
+        "name": "Brandon Burgan",
+        "type": "personal",
+        "access_token": "<AES-256-GCM encrypted>",
+        "refresh_token": "<AES-256-GCM encrypted>",
+        "token_expiry": "2026-02-23T08:53:00Z",
+        "scopes": ["gmail.modify", "calendar", "contacts.readonly"],
+        "connected_at": "2026-02-23T07:53:00Z"
+      }
+    ]
+  }
+}
+```
+
+- Encryption matches existing `tokens.json` pattern (AES-256-GCM with key from env)
+- File added to `.gitignore`
+
+### 2.4 Token Refresh
+
+- On every API call, check `token_expiry`
+- If expiring within **5 minutes**, refresh proactively using the `refresh_token`
+- If refresh fails (revoked, expired), mark account as `disconnected` and notify via status endpoint
+- No user interaction needed for refresh — fully automatic
+
+### 2.5 Required OAuth Scopes
+
+| Scope | Purpose |
+|---|---|
+| `https://www.googleapis.com/auth/gmail.modify` | Read, send, archive, mark read/unread |
+| `https://www.googleapis.com/auth/calendar` | Read/write calendar events |
+| `https://www.googleapis.com/auth/contacts.readonly` | Read contacts for autocomplete |
+| `https://www.googleapis.com/auth/userinfo.email` | Get authenticated user's email |
+| `https://www.googleapis.com/auth/userinfo.profile` | Get user's display name |
+
+**Note:** `gmail.modify` is used instead of the broader `mail.google.com` to minimize scope. It covers read, send, archive, and label management.
+
+---
+
+## 3. Frontend (Settings Page)
+
+### 3.1 UI Components
+
+**Settings → Integrations → Google Account**
+
+- **"Connect Google Account" button** — initiates OAuth flow
+- **Connected account card** showing:
+  - Profile picture (from Google)
+  - Email address
+  - Account type badge: "Personal" or "Workspace"
+  - Connection status: Connected ✅ / Expired ⚠️ / Disconnected ❌
+  - Last synced timestamp
+- **"Disconnect" button** — with confirmation dialog
+- **"Add Another Account" button** — for connecting multiple accounts
+
+### 3.2 Multiple Account Support
+
+Users can connect both personal Gmail and Google Workspace accounts simultaneously. Each account is independently managed with its own tokens. The email and calendar tabs show a combined view with account selector/filter.
+
+### 3.3 State Handling
+
+- Poll `/api/integrations/google/status` on settings page load
+- After OAuth callback redirect, show success/error toast
+- If token refresh fails, show warning banner in email/calendar tabs
+
+---
+
+## 4. Backend API Endpoints
+
+All endpoints require AIVA app authentication (`x-aiva-internal` header or session auth).
+
+### 4.1 OAuth Management
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/integrations/google/auth-url` | Generate OAuth authorization URL. Query params: `account_type=personal\|workspace` |
+| `GET` | `/api/integrations/google/callback` | Handle OAuth callback. Exchanges code for tokens, stores encrypted. Redirects to settings. |
+| `GET` | `/api/integrations/google/status` | Returns list of connected accounts with email, type, status, expiry. No tokens exposed. |
+| `DELETE` | `/api/integrations/google/disconnect` | Body: `{ accountId }`. Revokes token with Google, deletes from storage. |
+
+### 4.2 Email Endpoints
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/integrations/google/email/inbox` | List emails. Query: `accountId`, `maxResults` (default 20), `pageToken`, `q` (search), `labelIds` |
+| `GET` | `/api/integrations/google/email/:id` | Get full email (headers, body, attachments metadata). Query: `accountId` |
+| `POST` | `/api/integrations/google/email/send` | Send email. Body: `{ accountId, to, cc, bcc, subject, body, inReplyTo?, threadId? }` |
+| `POST` | `/api/integrations/google/email/:id/archive` | Remove INBOX label. Body: `{ accountId }` |
+| `POST` | `/api/integrations/google/email/:id/mark-read` | Remove UNREAD label. Body: `{ accountId }` |
+
+All email endpoints use the Gmail API v1 (`gmail.googleapis.com`).
+
+### 4.3 Calendar Endpoints
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/integrations/google/calendar/events` | List events. Query: `accountId`, `calendarId` (default "primary"), `timeMin`, `timeMax`, `maxResults` |
+| `POST` | `/api/integrations/google/calendar/events` | Create event. Body: `{ accountId, calendarId?, summary, start, end, description?, attendees?, location? }` |
+| `PUT` | `/api/integrations/google/calendar/events/:id` | Update event. Body: same as create + `{ accountId, calendarId? }` |
+| `DELETE` | `/api/integrations/google/calendar/events/:id` | Delete event. Query: `accountId`, `calendarId?` |
+
+All calendar endpoints use the Google Calendar API v3.
+
+### 4.4 Response Format
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null
+}
+```
+
+On token expiry that can't be auto-refreshed:
+```json
+{
+  "success": false,
+  "error": "GOOGLE_AUTH_EXPIRED",
+  "message": "Google account requires re-authentication",
+  "accountId": "..."
+}
+```
+
+---
+
+## 5. Migration Path
+
+### 5.1 Transition Strategy
+
+| Phase | Email Source | Calendar Source | GOG Status |
+|---|---|---|---|
+| Current | GOG CLI | GOG CLI | Required on every device |
+| Phase 2 complete | AIVA API | GOG CLI | Required only for calendar |
+| Phase 3 complete | AIVA API | AIVA API | Not required |
+| Phase 4 complete | AIVA API | AIVA API | Can be uninstalled |
+
+### 5.2 Backward Compatibility
+
+- During rollout, **both paths remain functional** — GOG CLI continues to work alongside new API endpoints
+- OpenClaw TOOLS.md gets updated with new API instructions but GOG fallback documented
+- Feature flag: `GOOGLE_INTEGRATION_ENABLED=true` in env to toggle new endpoints
+
+### 5.3 Agent Migration (Phase 4)
+
+OpenClaw agents currently run:
+```bash
+GOG_KEYRING_PASSWORD=openclaw gog calendar events primary --from ... --to ... --account ...
+GOG_KEYRING_PASSWORD=openclaw gog gmail inbox --account ...
+```
+
+After migration, agents call:
+```bash
+curl -H "x-aiva-internal: true" "http://localhost:PORT/api/integrations/google/calendar/events?accountId=...&timeMin=...&timeMax=..."
+curl -H "x-aiva-internal: true" "http://localhost:PORT/api/integrations/google/email/inbox?accountId=..."
+```
+
+TOOLS.md and relevant SOPs updated to reflect new commands. Old GOG references removed after Phase 4 validation.
+
+---
+
+## 6. Security
+
+### 6.1 Token Encryption at Rest
+- **AES-256-GCM** encryption for both `access_token` and `refresh_token`
+- Encryption key sourced from environment variable (same pattern as existing `tokens.json`)
+- Tokens never written to disk unencrypted
+
+### 6.2 Scope Minimization
+- Request only the scopes listed in §2.5 — no `mail.google.com` (full access)
+- `gmail.modify` instead of `gmail.compose` + `gmail.readonly` (single scope covers all needs)
+- Contacts are read-only
+
+### 6.3 Token Revocation
+- On disconnect, call Google's revocation endpoint (`https://oauth2.googleapis.com/revoke`)
+- Delete tokens from `oauth-tokens.json` immediately after revocation
+- If revocation API call fails, still delete local tokens (defense in depth)
+
+### 6.4 Git Safety
+- `oauth-tokens.json` in `.gitignore`
+- `GOOGLE_CLIENT_SECRET` only in env, never in code
+- No tokens logged (even at debug level)
+
+### 6.5 CSRF Protection
+- `state` parameter in OAuth flow validated on callback
+- `state` stored server-side in short-lived session/cache (5 min TTL)
+
+---
+
+## 7. Phases
+
+### Phase 1: OAuth Flow + Token Management + Settings UI
+- Google Cloud Console project setup (consent screen, credentials)
+- `/auth-url`, `/callback`, `/status`, `/disconnect` endpoints
+- Token encryption/storage/refresh logic
+- Settings page UI (connect, status, disconnect)
+- Multiple account support
+- **Deliverable:** User can connect/disconnect Google accounts from AIVA settings
+
+### Phase 2: Email API Endpoints + Email Tab Migration
+- All 5 email endpoints (inbox, get, send, archive, mark-read)
+- Update AIVA email tab to use new endpoints instead of GOG
+- Search/filter support
+- Thread view support
+- **Deliverable:** Email fully works through AIVA app, GOG no longer needed for email
+
+### Phase 3: Calendar API Endpoints + Calendar Migration
+- All 4 calendar endpoints (list, create, update, delete)
+- Update AIVA calendar features to use new endpoints
+- Multi-calendar support (primary + secondary calendars)
+- **Deliverable:** Calendar fully works through AIVA app, GOG no longer needed at all
+
+### Phase 4: OpenClaw Agent Migration
+- Update TOOLS.md with new API-based commands
+- Update SOPs referencing GOG CLI
+- Test all agent workflows (email check, send, calendar lookup, event creation)
+- Remove GOG CLI from device requirements
+- **Deliverable:** Zero dependency on GOG CLI across all devices and agents
+
+---
+
+## 8. Effort Estimates
+
+| Phase | Scope | Estimate |
+|---|---|---|
+| Phase 1 | OAuth flow + tokens + settings UI | 2–3 days |
+| Phase 2 | Email endpoints + email tab migration | 2–3 days |
+| Phase 3 | Calendar endpoints + calendar migration | 1–2 days |
+| Phase 4 | Agent migration + cleanup | 1 day |
+| **Total** | | **6–9 days** |
+
+Estimates assume one developer, familiar with the AIVA codebase. Includes basic testing but not Google OAuth app verification (see Risks).
+
+---
+
+## 9. Risks and Considerations
+
+### 9.1 Google OAuth App Verification
+- Apps requesting sensitive scopes (`gmail.modify`, `calendar`) require **Google verification**
+- Verification process: privacy policy, homepage, demo video — can take **1–4 weeks**
+- **Mitigation:** During development, app runs in "Testing" mode (limited to 100 test users, which is fine for our use case). If we stay under 100 users, verification may not be required. Can submit for verification later if needed.
+
+### 9.2 API Rate Limits
+- **Gmail API:** 250 quota units/second per user (inbox list = 5 units, send = 100 units)
+- **Calendar API:** 1,000,000 queries/day (effectively unlimited for our use)
+- **Mitigation:** Implement basic rate limiting on our endpoints; cache inbox listings briefly (30s TTL)
+
+### 9.3 Consent Screen Branding
+- Unverified apps show a "This app isn't verified" warning screen
+- Users must click "Advanced" → "Go to AIVA (unsafe)" to proceed
+- **Mitigation:** Acceptable for internal use. Submit for verification if it becomes user-facing beyond our team.
+
+### 9.4 Refresh Token Expiration
+- Google refresh tokens can expire if: unused for 6 months, user changes password, user revokes access, or app exceeds 50 refresh tokens per account
+- **Mitigation:** Proactive refresh keeps tokens active. Status endpoint surfaces auth issues. UI shows re-auth prompt when needed.
+
+### 9.5 Multi-Account Complexity
+- Users with both personal and Workspace accounts need clear UX to pick which account to use for sending
+- **Mitigation:** Default account setting + per-action account selector in email/calendar UI
+
+---
+
+## Approval
+
+**Decision needed from Brandon:**
+- [ ] Approve scope as written
+- [ ] Approve with modifications (note changes)
+- [ ] Defer (with reason)
+
+Once approved, begin Phase 1.

package/docs/settings-page-scope.md

@@ -0,0 +1,50 @@
+# Settings Page Changes — Scope Doc
+
+## Task
+Modify the AIVA app settings page and add a Getting Started page.
+
+## Changes Required
+
+### 1. Settings Page (`public/index.html`)
+**Location:** Lines ~2641-2650 in the settings view
+
+**Remove** the entire "Admin Tools" section:
+```html
+<div class="settings-section">
+  <h2>Admin Tools</h2>
+  <div class="settings-row">
+    <label>OpenClaw Dashboard</label>
+    <a href="https://brandons-mac-studio.tail61c982.ts.net/" target="_blank" class="btn btn-ghost">Open →</a>
+  </div>
+</div>
+```
+
+**Replace with:**
+```html
+<div class="settings-section">
+  <h2>Resources</h2>
+  <div class="settings-row">
+    <label>Getting Started with AIVA</label>
+    <a href="https://aivahelpme.com/getting-started" target="_blank" class="btn btn-ghost">Open →</a>
+  </div>
+</div>
+```
+
+### 2. Getting Started Page
+Create a new route `/getting-started` that serves the Getting Started content.
+
+**Content source:** `docs/getting-started.md`
+
+This should be a clean, public-facing page (no auth required) rendered from the markdown content. Style it nicely — clean typography, readable, mobile-friendly. Use the AIVA branding (dark theme matches the app).
+
+**Add route in `server.js`:**
+- `GET /getting-started` → serves rendered Getting Started page
+
+### 3. Updates Page (Future)
+Create a stub route `/updates` that we can populate later with changelog entries. For now, a simple page saying "Check back for the latest AIVA updates" is fine.
+
+## Important
+- NO emojis in the UI — use custom SVGs only (existing rule)
+- Wait — the markdown content has emojis for readability. The rendered HTML page should convert those to simple text labels or SVG icons instead.
+- Keep the page public (no auth) so the link works for anyone with the URL
+- Mobile-first responsive design

package/docs/xai-imagine-scope.md

@@ -0,0 +1,116 @@
+# xAI Grok Imagine Integration — Image & Video Generation
+
+## Goal
+Add Grok Imagine as a generation backend for images and videos in the AIVA app. When Brandon (or AIVA via the main agent) requests image/video generation, Grok Imagine should be available as a provider.
+
+## API Details
+
+### Image Generation
+- **Endpoint:** `POST https://api.x.ai/v1/images/generations`
+- **Model:** `grok-imagine-image`
+- **Auth:** `Authorization: Bearer <XAI_API_KEY>`
+- **Capabilities:** text-to-image, image editing (with source image), style transfer
+- **Request body:**
+```json
+{
+  "model": "grok-imagine-image",
+  "prompt": "description",
+  "n": 1,
+  "response_format": "url"
+}
+```
+- For image editing, add `"image_url": "<url or data:image/jpeg;base64,...>"`
+- **Response:** `{ "data": [{ "url": "..." }] }` (OpenAI-compatible format)
+
+### Video Generation  
+- **Endpoint:** `POST https://api.x.ai/v1/videos/generations`
+- **Model:** `grok-imagine-video`
+- **Async:** Returns `{ "request_id": "..." }` — must poll for completion
+- **Poll:** `GET https://api.x.ai/v1/videos/<request_id>`
+- **Status values:** `pending`, `done`, `expired`
+- **When done:** `{ "status": "done", "video": { "url": "...", "duration": N } }`
+- **Options:** `duration` (1-15 sec), `aspect_ratio` (16:9, 9:16, 1:1, etc.), `resolution` (480p, 720p)
+- For image-to-video, add `"image_url": "..."`
+- For video editing, add `"video_url": "..."` (max 8.7 sec input)
+
+### API Key
+Use env var `XAI_API_KEY` or fallback to hardcoded: `xai-Gn37fuJg5ty4gvWFG2rbth34AxNORUKH8r4vTXQDtjwMGUqKZ7nYy8u2YStosGUCVBEg7VMHSqQZcKS4`
+
+## What to Build
+
+### 1. Server module: `grok-imagine.js`
+Create a new module at `~/.openclaw/workspace/aiva-tasks/grok-imagine.js` with:
+
+```javascript
+// Functions:
+async function generateImage(prompt, options = {})
+// options: { imageUrl, n, aspectRatio, resolution }
+// Returns: { url: "...", ... }
+
+async function generateVideo(prompt, options = {})
+// options: { imageUrl, videoUrl, duration, aspectRatio, resolution }
+// Handles polling internally (poll every 5 sec, timeout 10 min)
+// Returns: { url: "...", duration: N }
+
+async function editImage(prompt, sourceImageUrl)
+// Convenience wrapper for image editing
+
+async function editVideo(prompt, sourceVideoUrl)
+// Convenience wrapper for video editing
+```
+
+### 2. Server route: `POST /api/generate`
+Add to `server.js`:
+```
+POST /api/generate
+Body: {
+  "type": "image" | "video",
+  "prompt": "...",
+  "options": { ... }  // optional: imageUrl, videoUrl, duration, aspectRatio, resolution
+}
+```
+- For images: call `generateImage()`, return URL immediately
+- For videos: call `generateVideo()`, which polls until done, return URL
+- Save generated media to chat history so it shows up in the media gallery
+- Send as an AIVA message in the chat (with imageUrl or videoUrl set)
+
+### 3. Voice call tool: `generate_media`
+Add to voice-call.js tools array:
+```json
+{
+  "type": "function",
+  "name": "generate_media",
+  "description": "Generate an image or video using AI. Use when Brandon asks you to create, generate, or make an image or video.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "type": { "type": "string", "enum": ["image", "video"], "description": "Type of media to generate" },
+      "prompt": { "type": "string", "description": "Description of what to generate" },
+      "duration": { "type": "number", "description": "Video duration in seconds (1-15, default 5)" },
+      "aspect_ratio": { "type": "string", "description": "Aspect ratio (16:9, 9:16, 1:1, 4:3, etc.)" }
+    },
+    "required": ["type", "prompt"]
+  }
+}
+```
+Implementation: call the `/api/generate` endpoint internally, return the URL to Grok so Ara can tell Brandon it's ready.
+
+### 4. Chat integration
+When AIVA (main agent) gets a request to generate images/videos, it can use this endpoint too. The generated media should:
+- Be saved as a chat message with the appropriate URL field (imageUrl/videoUrl)
+- Show up in the media gallery automatically
+- Include the prompt as the message caption
+
+## Files to Create/Modify
+1. **CREATE** `grok-imagine.js` — Generation module
+2. **MODIFY** `server.js` — Add `/api/generate` route + require grok-imagine
+3. **MODIFY** `voice-call.js` — Add `generate_media` tool to xAI session tools array + handler in executeTool
+
+## DO NOT TOUCH
+- Microphone icon
+- Media gallery (just built)
+- Audio streaming code
+- Any other existing features
+
+## After changes
+`pm2 restart aiva-app`

package/docs/xai-voice-integration-scope.md

@@ -0,0 +1,115 @@
+# xAI Voice Agent Integration — Scope Doc
+
+## Goal
+Replace the current phone icon voice call feature in the AIVA app with xAI's Voice Agent API using the **Ara** voice. The microphone icon (voice-to-text for chat) must NOT be touched.
+
+## Current Architecture
+- **Client:** `public/index.html` — phone icon button triggers `toggleVoiceCall()` → push-to-talk UI
+- **Server:** `voice-call.js` — Socket.IO events, Whisper STT → Claude → ElevenLabs TTS pipeline
+- **Flow:** Record audio → send blob via socket → server transcribes → Claude responds → ElevenLabs generates speech → send audio back
+
+## New Architecture
+Replace with xAI's real-time Voice Agent API (WebSocket-based, bidirectional audio streaming).
+
+### xAI Voice Agent API Details
+- **Endpoint:** `wss://api.x.ai/v1/realtime`
+- **API Key:** `xai-Gn37fuJg5ty4gvWFG2rbth34AxNORUKH8r4vTXQDtjwMGUqKZ7nYy8u2YStosGUCVBEg7VMHSqQZcKS4`
+- **Voice:** `Ara`
+- **Price:** $0.05/min
+- **Docs:** https://docs.x.ai/developers/model-capabilities/audio/voice-agent
+- **Compatible with OpenAI Realtime API spec**
+
+### Key Changes
+
+#### Server (`voice-call.js`)
+1. When a voice call starts, open a WebSocket to `wss://api.x.ai/v1/realtime`
+2. Authenticate with the API key
+3. Send `session.update` with:
+   - `voice: "Ara"`
+   - `instructions`: Use the same system prompt builder (`buildSystemPrompt`) but adapted for Grok context
+   - Any tools we want (web_search, etc. are optional)
+4. Stream client audio to xAI WebSocket (bidirectional)
+5. Stream xAI audio responses back to client
+6. Handle turn detection, interruption, etc.
+
+#### Client (`public/index.html`)
+1. Change from push-to-talk to **continuous streaming** (xAI handles VAD/turn detection)
+2. When call starts: get mic stream, connect via Socket.IO to server
+3. Server proxies audio to/from xAI WebSocket
+4. Play incoming audio in real-time (streaming, not waiting for full response)
+5. UI updates: remove "Hold mic to talk" — change to just "Listening..." / "Ara speaking..."
+6. Keep the call timer, end call button, transcript display
+
+#### Environment
+- Add `XAI_API_KEY` env var (or use the hardcoded key for now)
+- Keep all existing ElevenLabs/Whisper/Claude env vars (they're used by other features)
+
+## DO NOT TOUCH
+- The microphone icon and its voice-to-text functionality
+- Any other part of the app
+- The `sag` CLI or ElevenLabs integration used elsewhere
+
+## UI Changes
+- Phone icon behavior stays the same (tap to start/end call)
+- Remove push-to-talk mic button — conversation is now continuous/hands-free
+- Keep: call timer, end call button, transcript area, voice visualizer
+- Status text: "Connecting..." → "Listening..." → "Ara speaking..." → "Listening..."
+- NO emojis in any UI elements (use text or SVGs only)
+
+## Audio Format
+- xAI Realtime API uses PCM16 audio at 24kHz (same as OpenAI Realtime)
+- Client needs to capture mic audio and send as PCM16
+- Server receives PCM16 from xAI and sends to client for playback
+
+## AIVA Integration Hooks (CRITICAL)
+
+### 1. Pre-Call Context Injection
+When a call starts, BEFORE sending `session.update` to xAI:
+1. Fetch context from `http://localhost:3847/api/context/voice` (already exists in voice-call.js)
+2. Build a rich system prompt that includes:
+   - Recent AIVA app chat history (last 10 messages)
+   - Active tasks from the task board
+   - User info (Brandon's preferences, current projects)
+   - Today's calendar events (if available from context API)
+   - Memory/personality context
+3. Inject this as the `instructions` field in `session.update`
+4. This way Grok/Ara has full context about what Brandon is working on
+
+### 2. Post-Call Transcript Hook
+When a call ends:
+1. Collect the full transcript (all user + assistant turns) accumulated during the call
+2. Save transcript to `~/.openclaw/workspace/memory/call-logs/pending_ara_<timestamp>.json` with format:
+   ```json
+   {
+     "type": "ara-voice-call",
+     "timestamp": "<ISO>",
+     "duration": <seconds>,
+     "transcript": [
+       {"role": "user", "text": "..."},
+       {"role": "assistant", "text": "..."}
+     ]
+   }
+   ```
+3. Also fire a wake hook to notify AIVA main agent:
+   ```
+   POST http://localhost:3847/hooks/wake
+   x-aiva-internal: true
+   {"text": "[VOICE-CALL-COMPLETE] Ara voice call ended. Duration: Xm Xs. Transcript saved to memory/call-logs/pending_ara_<timestamp>.json. Process action items."}
+   ```
+
+This lets AIVA (Claude) review what was discussed and act on any tasks/requests.
+
+## Testing
+- Tap phone icon → should connect and start listening immediately
+- Speak naturally → Ara responds in real-time with her voice
+- Tap end call → cleanly disconnects
+- Microphone icon (chat voice-to-text) still works exactly as before
+
+## Files to Modify
+1. `voice-call.js` — Replace STT/Claude/TTS pipeline with xAI WebSocket proxy
+2. `public/index.html` — Update voice call UI (continuous mode, remove PTT)
+3. `package.json` — Add `ws` package if not already present (for WebSocket client)
+
+## Reference
+- xAI Voice Agent docs: https://docs.x.ai/developers/model-capabilities/audio/voice-agent
+- Compatible with OpenAI Realtime API format