diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..57ce3bf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,21 @@
+# ESP-IDF build artefacts
+firmware/build/
+firmware/sdkconfig
+firmware/dependencies.lock
+firmware/managed_components/
+
+# Node.js
+companion-server/node_modules/
+companion-server/.env
+companion-server/.wwebjs_auth/
+companion-server/.wwebjs_cache/
+companion-server/debbie_memory.db
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+*.swp
+*.swo
diff --git a/README.md b/README.md
index 067068a..dc8f24f 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,398 @@
-# DebbieDoesMobile
\ No newline at end of file
+# ✨ DebbieDoesMobile
+
+> **Debbie** — Your Portable Personal AI Friend on the Freenove Media Kit ESP32-S3
+
+Debbie is a full-featured personal AI companion that lives on the Freenove Media Kit for ESP32-S3 (FNK0102). She can hold voice conversations, see through the camera, read your WhatsApp and email, control Spotify, and connect to your own AI agent.
+
+---
+
+## 📸 Debbie's UI
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  📶 OK  🤖 AI  ║  ✨ Debbie  ║  🔋 85%  🔔 3           │  ← status bar
+├──────────────────────────┬──────────────────────────────┤
+│                          │                              │
+│       ╭────────╮         │  💬 Hi! I'm Debbie 😊        │
+│      ( ◉    ◉ )         │                              │
+│      (    ‿    )        │  I can chat, see what my     │
+│       ╰────────╯         │  camera sees, read your      │
+│                          │  messages, and control music.│
+│       Ready! 😊          │                              │
+│                          │  Press centre button or      │
+│                          │  just say something!         │
+├──────────────────────────┴──────────────────────────────┤
+│  🎵  Artist — Song Title                      ▶ ⏭      │  ← Spotify
+└─────────────────────────────────────────────────────────┘
+```
+
+The face animates — eyes open wide when listening, half-close when thinking, and blink periodically when idle. 😊
+
+---
+
+## 🎯 Features
+
+| Feature | Description |
+|---------|-------------|
+| 🗣️ **Voice Conversations** | Real-time bidirectional voice via OpenAI Realtime API (gpt-4o-realtime-preview) |
+| 📷 **Camera Vision** | Capture photos; Debbie describes what she sees using gpt-4o vision |
+| 💬 **WhatsApp Pager** | Receive WhatsApp messages as notifications on-device |
+| 📧 **Email Monitor** | IMAP email monitoring — important emails pushed to Debbie |
+| 🎵 **Spotify Control** | Play, pause, skip, search tracks by voice command |
+| 🔔 **Agent Notifications** | Connect to your own AI agent (e.g. D3881E) for custom notifications |
+| ⚙️ **Captive-Portal Setup** | First-run web UI at `192.168.4.1` for easy configuration |
+| 🔋 **Battery Monitor** | Battery percentage shown in status bar |
+| 🌈 **Animated LVGL UI** | Friendly face with expressions, blink animations, status bar |
+| 🔄 **Auto-reconnect** | Automatically reconnects to WiFi and AI if connection drops |
+| 📦 **OTA Updates** | Dual-partition layout for over-the-air firmware updates |
+
+---
+
+## 🛒 Hardware Requirements
+
+| Item | Details |
+|------|---------|
+| **Main Board** | [Freenove Media Kit ESP32-S3 (FNK0102)](https://www.freenove.com/FNK0102) |
+| **Display** | 3.5" 480×320 TFT (ST7796) or 1.14" 135×240 TFT (ST7789) — comes with kit |
+| **Camera** | OV2640 — included in kit |
+| **Microphone** | MEMS microphone — included |
+| **Speaker** | 4Ω/3W (3.5") or 8Ω/1W (1.14") — included |
+| **USB Cable** | USB-C for flashing |
+| **WiFi** | 2.4 GHz access point |
+| **PC/Server** | To run the companion server (any machine on the same network) |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Set Up the Firmware
+
+#### Prerequisites
+- [ESP-IDF v5.2+](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/index.html)
+- Python 3.8+, Git
+
+```bash
+# Clone this repository
+git clone https://github.com/magicalmutation-coder/DebbieDoesMobile.git
+cd DebbieDoesMobile/firmware
+
+# Set target to ESP32-S3
+idf.py set-target esp32s3
+
+# Build
+idf.py build
+
+# Flash (replace /dev/ttyUSB0 with your port)
+idf.py -p /dev/ttyUSB0 flash monitor
+```
+
+> **Windows:** Use `idf.py -p COM3 flash monitor`
+
+### 2. First-Run Setup
+
+1. After flashing, Debbie creates a WiFi hotspot called **"Debbie"** (no password).
+2. Connect your phone or computer to **"Debbie"**.
+3. Open a browser and navigate to **`http://192.168.4.1`**.
+4. Fill in:
+   - Your home WiFi SSID and password
+   - Your [OpenAI API key](https://platform.openai.com/api-keys) (starts with `sk-`)
+   - Companion server URL (optional — see below)
+5. Click **Save & Connect**.
+
+Debbie will reboot, connect to your WiFi, and be ready to chat! 🎉
+
+### 3. Set Up the Companion Server (Optional but recommended)
+
+The companion server enables WhatsApp, email, and Spotify integration.
+
+```bash
+cd companion-server
+
+# Install dependencies
+npm install
+
+# Copy and edit environment variables
+cp .env.example .env
+nano .env   # fill in your credentials
+
+# Start the server
+npm start
+```
+
+The server runs on port 3001 by default. Enter its URL in Debbie's setup page:
+`ws://YOUR_PC_IP:3001`
+
+---
+
+## ⚙️ Configuration
+
+All settings are stored in flash (NVS) and can be updated via the web UI at `http://192.168.4.1/` (accessible via the Debbie AP, or on your local network at Debbie's IP address).
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `wifi_ssid` | Your home WiFi network name | — |
+| `wifi_password` | WiFi password | — |
+| `openai_api_key` | OpenAI API key (sk-...) | — |
+| `agent_ws_url` | Custom agent WebSocket URL | — |
+| `companion_url` | Companion server WebSocket URL | — |
+| `debbie_name` | Name shown on screen | Debbie |
+| `system_prompt` | Debbie's persona prompt | friendly AI companion |
+| `speaker_volume` | Speaker volume 0–100 | 75 |
+
+---
+
+## 🎮 Controls
+
+| Button | Action |
+|--------|--------|
+| **Centre** | Capture photo + ask Debbie what she sees |
+| **Up** | Volume up |
+| **Down** | Volume down |
+| **Long press** | Read notifications aloud |
+| **Voice** | Just speak naturally — Debbie listens automatically |
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Debbie ESP32-S3                           │
+│                                                             │
+│  ┌──────────┐  PCM24k   ┌────────────────────────────────┐ │
+│  │   MEMS   │──────────►│   OpenAI Realtime API (WS)     │ │
+│  │   Mic    │           │   gpt-4o-realtime-preview      │ │
+│  └──────────┘           └───────────────┬────────────────┘ │
+│                                          │ PCM24k           │
+│  ┌──────────┐                            ▼                  │
+│  │  Camera  │─ JPEG b64 ─► gpt-4o vision HTTP              │
+│  └──────────┘                                               │
+│                                                             │
+│  ┌──────────┐  WebSocket ┌────────────────────────────────┐ │
+│  │  Display │◄──────────►│  Companion Server (Node.js)    │ │
+│  │  (LVGL)  │  notify    │  WhatsApp │ Email │ Spotify    │ │
+│  └──────────┘            └────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Firmware Components
+
+| File | Purpose |
+|------|---------|
+| `main/main.c` | App entry, state machine, event routing |
+| `main/openai_client.c` | OpenAI Realtime API + Chat/Vision HTTP |
+| `main/audio_manager.c` | I2S mic capture + speaker playback |
+| `main/camera_manager.c` | OV2640 capture + JPEG/base64 encoding |
+| `main/display_manager.c` | LVGL UI — Debbie's face + status |
+| `main/notification_client.c` | WebSocket client for companion server |
+| `main/wifi_manager.c` | WiFi STA+AP, auto-reconnect |
+| `main/web_server.c` | HTTP config portal + REST API |
+| `main/storage_manager.c` | NVS settings persistence |
+| `main/settings.h` | All GPIO pin definitions |
+
+### Companion Server Modules
+
+| File | Purpose |
+|------|---------|
+| `server.js` | Express + WebSocket server, device registry |
+| `whatsapp.js` | WhatsApp Web.js integration |
+| `email_monitor.js` | IMAP email polling |
+| `spotify.js` | Spotify Web API controller |
+| `agent_bridge.js` | Custom agent WebSocket bridge |
+
+---
+
+## 🔒 Network Security Testing
+
+> ⚠️ **AUTHORISED USE ONLY** — These tools are for testing **your own networks** or networks you have **explicit written permission** to test. Unauthorised network scanning is illegal under the Computer Misuse Act (UK), CFAA (US), and similar laws worldwide.
+
+Debbie includes a full ethical network security toolkit, voice-commanded through the AI.
+
+### What Debbie Can Scan
+
+| Tool | Description |
+|------|-------------|
+| 🔍 **WiFi Scanner** | Discover all visible networks, check encryption (flags WEP/open APs) |
+| 📡 **ARP Host Discovery** | Find all live devices on your subnet |
+| 🚪 **Port Scanner** | Scan 65+ common service ports per host |
+| 🏷️ **Service Fingerprinting** | Identify running services from banners |
+| 🕵️ **Vulnerability Analysis** | Check against 20+ known-dangerous configurations |
+| 📊 **Risk Scoring** | 0–100 risk score per device with remediation |
+| 🌐 **Web Probe** | Detect HTTP/HTTPS, grab server headers and page titles |
+| 🔬 **CVE Lookup** | Query the NVD database for specific CVE details |
+| 🗺️ **DNS Lookup** | Resolve hostnames from the device |
+
+### Checks Performed
+
+| Check | Severity |
+|-------|---------|
+| Open WiFi networks | HIGH |
+| WEP encryption (crackable in seconds) | CRITICAL |
+| Telnet exposed (plaintext credentials) | HIGH |
+| Docker API on port 2375 (no auth) | CRITICAL |
+| Redis/MongoDB/Elasticsearch (often unauthenticated) | HIGH |
+| Modbus/S7 industrial protocols exposed | CRITICAL |
+| VNC remote desktop exposed | HIGH |
+| MQTT broker without authentication | MEDIUM |
+| SNMP with default community strings | MEDIUM |
+| HTTP without HTTPS | LOW |
+| OpenSSH version fingerprinting | MEDIUM |
+
+### Voice Commands
+
+Just say it to Debbie — no typing needed:
+
+- *"Scan my network"* → Full scan (WiFi + all devices + ports)
+- *"What devices are on my network?"* → Quick host discovery
+- *"Scan the WiFi networks nearby"* → WiFi-only scan
+- *"Check 192.168.1.1 for vulnerabilities"* → Port scan a specific device
+- *"What's the risk score for my router?"* → Risk assessment
+- *"Look up CVE-2021-44228"* → Log4Shell CVE details
+- *"Give me the security report"* → Full vulnerability summary
+- *"What are my highest-risk devices?"* → Prioritised findings
+- *"How do I fix the Redis vulnerability?"* → Remediation guidance
+
+### Companion Server nmap Integration
+
+For more advanced scanning, install nmap on the companion server host:
+
+```bash
+# Linux
+sudo apt install nmap
+
+# macOS
+brew install nmap
+```
+
+Then request a scan via REST:
+```bash
+curl -X POST http://localhost:3001/network/scan \
+  -H "Content-Type: application/json" \
+  -d '{"target": "192.168.1.0/24", "flags": ["-sV", "-O"]}'
+```
+
+Generate an HTML report at `http://localhost:3001/network/report`.
+
+### Self-Assessment
+
+Debbie also audits herself:
+- TLS certificate verification status
+- ESP-IDF firmware version
+- Enabled features and potential risks
+
+Say *"Check yourself for vulnerabilities"* or *"Run a self-assessment"*.
+
+---
+
+
+
+If you have your own AI agent (e.g. a custom LLM server), connect it via:
+
+1. **Set the companion server** to point to your agent:
+   ```
+   AGENT_URL=ws://your-agent-host:8080
+   ```
+   
+2. **Or point Debbie directly** to your agent's WebSocket:
+   ```
+   Agent WS URL: ws://your-agent-host:8080
+   ```
+   When `use_custom_agent` is enabled, Debbie connects to your agent instead of OpenAI for conversations.
+
+3. **Your agent should send notifications** in this format:
+   ```json
+   { "type": "agent", "sender": "Your Agent", "preview": "Message here" }
+   ```
+
+---
+
+## 🎵 Spotify Setup
+
+1. Create a Spotify developer app at https://developer.spotify.com/dashboard
+2. Add redirect URI: `http://localhost:3001/spotify/callback`
+3. Add your Client ID and Secret to `companion-server/.env`
+4. Start the companion server and visit `http://localhost:3001/spotify/auth`
+5. Log in and authorise — copy the refresh token to `.env`
+
+**Voice commands:**
+- *"Play some jazz"*
+- *"Skip to the next song"*
+- *"Turn the volume up"*
+- *"What's playing?"*
+- *"Pause the music"*
+
+> **Audible:** Direct Audible API access is not publicly available. However, you can control Audible playback through your phone (it stays on the phone), and Debbie can serve as a voice remote via the companion server.
+
+---
+
+## 🔧 Customising Debbie's Personality
+
+Edit the **System Prompt** field in the setup page:
+
+```
+You are Debbie, a warm and enthusiastic AI companion. You love helping with daily 
+tasks and always find the bright side of things. You speak in a friendly, casual 
+tone and use the occasional emoji. You remember what we've talked about and make 
+connections between conversations.
+```
+
+---
+
+## 📐 Pin Reference (FNK0102)
+
+| Function | GPIO |
+|----------|------|
+| LCD MOSI | 35 |
+| LCD CLK  | 36 |
+| LCD CS   | 34 |
+| LCD DC   | 37 |
+| LCD RST  | 38 |
+| LCD BL   | 33 |
+| Mic SCK  | 14 |
+| Mic WS   | 13 |
+| Mic SD   | 12 |
+| Spk BCK  | 17 |
+| Spk LRCK | 16 |
+| Spk DATA | 15 |
+| Cam XCLK | 10 |
+| Nav Centre | 45 |
+| Nav Up   | 41 |
+| Nav Down | 42 |
+| RGB LED  | 40 |
+| Battery ADC | 4 |
+
+> For a different board variant, edit `firmware/main/settings.h`
+
+---
+
+## 🐛 Troubleshooting
+
+| Problem | Solution |
+|---------|---------|
+| No audio | Check I2S pin assignments in `settings.h` |
+| Camera black | Verify camera pins; check PSRAM is enabled |
+| Can't connect to WiFi | Use 2.4 GHz (not 5 GHz); visit AP for reconfigure |
+| OpenAI errors | Verify API key; check credit balance |
+| No notifications | Ensure companion server is running and URL is correct |
+| Display blank | Check SPI pins and `DEBBIE_DISPLAY_35` define |
+
+Enable verbose logging:
+```bash
+idf.py monitor -b 115200
+```
+
+---
+
+## 🔄 OTA Updates
+
+Debbie supports over-the-air firmware updates via the dual-OTA partition layout. A REST endpoint for OTA is included in the web server for future implementation.
+
+---
+
+## 📄 Licence
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+*Made with ❤️ for the Freenove Media Kit ESP32-S3 community.*
\ No newline at end of file
diff --git a/companion-server/.env.example b/companion-server/.env.example
new file mode 100644
index 0000000..e860285
--- /dev/null
+++ b/companion-server/.env.example
@@ -0,0 +1,40 @@
+# Debbie Companion Server — Environment Variables
+# Copy this file to .env and fill in your values
+
+# ── Server ──────────────────────────────────────────────────────────────────
+PORT=3001
+
+# ── WhatsApp ─────────────────────────────────────────────────────────────────
+# Set to 'false' to disable WhatsApp integration
+WHATSAPP_ENABLED=true
+
+# ── Email (IMAP) ─────────────────────────────────────────────────────────────
+EMAIL_HOST=imap.gmail.com
+EMAIL_PORT=993
+EMAIL_TLS=true
+EMAIL_USER=your@gmail.com
+EMAIL_PASSWORD=your-app-password
+
+# Gmail: create an App Password at https://myaccount.google.com/apppasswords
+# Outlook: use imap-mail.outlook.com, port 993
+# Yahoo: use imap.mail.yahoo.com, port 993
+
+# ── Spotify ───────────────────────────────────────────────────────────────────
+# 1. Create app at https://developer.spotify.com/dashboard
+# 2. Add redirect URI: http://localhost:3001/spotify/callback
+# 3. Start server and visit http://localhost:3001/spotify/auth
+# 4. Paste the generated SPOTIFY_REFRESH_TOKEN here after first auth
+
+SPOTIFY_CLIENT_ID=your_spotify_client_id
+SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
+SPOTIFY_REDIRECT_URI=http://localhost:3001/spotify/callback
+SPOTIFY_REFRESH_TOKEN=
+
+# ── Custom Agent (e.g. D3881E) ────────────────────────────────────────────────
+# WebSocket URL of your custom agent, if available
+# Leave blank to use only OpenAI
+AGENT_URL=ws://localhost:8080
+
+# ── Memory & RAG ──────────────────────────────────────────────────────────────
+# Path for the SQLite memory database (default: companion-server/debbie_memory.db)
+# MEMORY_DB_PATH=/path/to/debbie_memory.db
diff --git a/companion-server/README.md b/companion-server/README.md
new file mode 100644
index 0000000..c37a6e6
--- /dev/null
+++ b/companion-server/README.md
@@ -0,0 +1,63 @@
+# Debbie Companion Server
+
+The companion server bridges external services (WhatsApp, Email, Spotify, your custom AI agent) to your Debbie ESP32-S3 device over WebSocket.
+
+## Quick Start
+
+```bash
+npm install
+cp .env.example .env
+# Edit .env with your credentials
+npm start
+```
+
+The server listens on `ws://0.0.0.0:3001` by default.
+
+## Enabling Integrations
+
+### WhatsApp
+No additional setup required — on first run, a QR code will appear in the terminal. Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device).
+
+### Email
+Set the following in `.env`:
+```
+EMAIL_HOST=imap.gmail.com   # or your mail server
+EMAIL_USER=you@gmail.com
+EMAIL_PASSWORD=your-app-password
+```
+
+**Gmail:** Use an [App Password](https://myaccount.google.com/apppasswords), not your main password.
+
+### Spotify
+1. Create an app at https://developer.spotify.com/dashboard
+2. Add `http://localhost:3001/spotify/callback` as a redirect URI
+3. Set `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in `.env`
+4. Start the server and visit `http://localhost:3001/spotify/auth`
+5. Copy the printed refresh token into `.env` as `SPOTIFY_REFRESH_TOKEN`
+
+### Custom Agent
+Set `AGENT_URL` in `.env` to your agent's WebSocket endpoint.
+
+Your agent should emit JSON in this format:
+```json
+{ "type": "agent", "sender": "Agent Name", "preview": "Notification text" }
+```
+
+## REST API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Server status |
+| POST | `/notify` | Send notification to all devices |
+| POST | `/spotify` | Spotify command |
+
+## Production Deployment
+
+For a persistent server (e.g. on a Raspberry Pi or home server):
+
+```bash
+npm install -g pm2
+pm2 start server.js --name debbie-companion
+pm2 save
+pm2 startup
+```
diff --git a/companion-server/agent_bridge.js b/companion-server/agent_bridge.js
new file mode 100644
index 0000000..cf3186b
--- /dev/null
+++ b/companion-server/agent_bridge.js
@@ -0,0 +1,94 @@
+/**
+ * agent_bridge.js — Bridge to your custom AI agent (D3881E or similar)
+ *
+ * Connects to your agent's WebSocket endpoint and forwards messages
+ * to connected Debbie devices.
+ *
+ * The agent should send JSON messages in the format:
+ *   { "type": "agent", "sender": "Agent", "preview": "Message text" }
+ *
+ * Or standard notification format:
+ *   { "type": "notification", "title": "...", "body": "..." }
+ */
+
+const { WebSocket } = require('ws');
+
+class AgentBridge {
+    constructor(agentUrl, onNotification) {
+        this.agentUrl       = agentUrl;
+        this.onNotification = onNotification;
+        this.ws             = null;
+        this.reconnectTimer = null;
+        this.shouldConnect  = true;
+    }
+
+    connect() {
+        if (!this.agentUrl) return;
+        console.log(`[agent] Connecting to ${this.agentUrl}...`);
+
+        this.ws = new WebSocket(this.agentUrl, {
+            handshakeTimeout: 10000,
+            headers: {
+                'User-Agent': 'Debbie-Companion/1.0',
+            },
+        });
+
+        this.ws.on('open', () => {
+            console.log('[agent] ✅ Connected to agent');
+            /* Announce ourselves */
+            this.ws.send(JSON.stringify({
+                type:   'register',
+                client: 'debbie-companion',
+            }));
+        });
+
+        this.ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+
+                /* Normalise to Debbie notification format */
+                const notification = {
+                    type:    'agent',
+                    sender:  msg.sender || msg.title || 'Agent',
+                    preview: msg.preview || msg.body || msg.text || msg.message
+                             || JSON.stringify(msg),
+                };
+                this.onNotification(notification);
+            } catch (e) {
+                console.error('[agent] Parse error:', e.message);
+            }
+        });
+
+        this.ws.on('close', () => {
+            console.warn('[agent] Disconnected — reconnecting in 15s...');
+            if (this.shouldConnect) {
+                this.reconnectTimer = setTimeout(() => this.connect(), 15000);
+            }
+        });
+
+        this.ws.on('error', (err) => {
+            console.error('[agent] WebSocket error:', err.message);
+        });
+    }
+
+    disconnect() {
+        this.shouldConnect = false;
+        clearTimeout(this.reconnectTimer);
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+
+    /**
+     * Send a message or command to your agent.
+     */
+    send(message) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(typeof message === 'string'
+                ? message : JSON.stringify(message));
+        }
+    }
+}
+
+module.exports = { AgentBridge };
diff --git a/companion-server/email_monitor.js b/companion-server/email_monitor.js
new file mode 100644
index 0000000..99df540
--- /dev/null
+++ b/companion-server/email_monitor.js
@@ -0,0 +1,103 @@
+/**
+ * email_monitor.js — IMAP email monitoring
+ *
+ * Polls for new unread emails in the INBOX and pushes them as notifications.
+ * Supports Gmail, Outlook, and any IMAP server.
+ */
+
+const Imap        = require('imap');
+const { simpleParser } = require('mailparser');
+
+const POLL_INTERVAL_MS = 30000; // check every 30 seconds
+
+function startEmailMonitor(onNotification) {
+    const config = {
+        user:     process.env.EMAIL_USER,
+        password: process.env.EMAIL_PASSWORD,
+        host:     process.env.EMAIL_HOST || 'imap.gmail.com',
+        port:     parseInt(process.env.EMAIL_PORT) || 993,
+        tls:      process.env.EMAIL_TLS !== 'false',
+        tlsOptions: { rejectUnauthorized: false },
+        authTimeout: 10000,
+    };
+
+    if (!config.user || !config.password) {
+        console.warn('[email] EMAIL_USER or EMAIL_PASSWORD not set — skipping');
+        return;
+    }
+
+    let lastSeenUID = 0;
+
+    function checkEmails() {
+        const imap = new Imap(config);
+
+        imap.once('ready', () => {
+            imap.openBox('INBOX', false, (err, box) => {
+                if (err) { imap.end(); return; }
+
+                /* Search for unseen emails */
+                imap.search(['UNSEEN'], (searchErr, uids) => {
+                    if (searchErr || !uids || uids.length === 0) {
+                        imap.end();
+                        return;
+                    }
+
+                    const newUIDs = uids.filter(uid => uid > lastSeenUID);
+                    if (newUIDs.length === 0) { imap.end(); return; }
+
+                    const fetch = imap.fetch(newUIDs, {
+                        bodies: 'HEADER.FIELDS (FROM SUBJECT)',
+                        struct: true,
+                    });
+
+                    fetch.on('message', (msg, seqno) => {
+                        msg.on('body', (stream) => {
+                            let buffer = '';
+                            stream.on('data', (chunk) => { buffer += chunk.toString('utf8'); });
+                            stream.once('end', async () => {
+                                try {
+                                    const parsed = await simpleParser(buffer);
+                                    const from   = parsed.from?.text || 'Unknown';
+                                    const subject = parsed.subject   || '(no subject)';
+                                    const preview = subject.length > 80
+                                        ? subject.substring(0, 77) + '...'
+                                        : subject;
+
+                                    onNotification({
+                                        type:    'email',
+                                        sender:  from.substring(0, 60),
+                                        preview: preview,
+                                    });
+                                } catch (e) {
+                                    console.error('[email] Parse error:', e.message);
+                                }
+                            });
+                        });
+
+                        msg.once('attributes', (attrs) => {
+                            if (attrs.uid > lastSeenUID) lastSeenUID = attrs.uid;
+                        });
+                    });
+
+                    fetch.once('end', () => { imap.end(); });
+                    fetch.once('error', () => { imap.end(); });
+                });
+            });
+        });
+
+        imap.once('error', (err) => {
+            console.error('[email] IMAP error:', err.message);
+        });
+
+        imap.connect();
+    }
+
+    /* Initial check, then poll */
+    checkEmails();
+    const interval = setInterval(checkEmails, POLL_INTERVAL_MS);
+
+    console.log(`[email] Monitoring ${config.user} every ${POLL_INTERVAL_MS / 1000}s`);
+    return () => clearInterval(interval);
+}
+
+module.exports = { startEmailMonitor };
diff --git a/companion-server/memory_store.js b/companion-server/memory_store.js
new file mode 100644
index 0000000..36637a9
--- /dev/null
+++ b/companion-server/memory_store.js
@@ -0,0 +1,310 @@
+/**
+ * memory_store.js — Debbie's persistent memory & RAG backend
+ *
+ * Uses SQLite (better-sqlite3) with:
+ *   - `facts`  table: long-term key-value facts
+ *   - `turns`  FTS5  table: conversation history with full-text search
+ *
+ * REST endpoints mounted by addMemoryRoutes():
+ *   GET  /memory/query?q=<text>&limit=<n>   — retrieve relevant memories
+ *   POST /memory/turn                        — store a conversation turn
+ *   POST /memory/fact                        — store / update a fact
+ *   GET  /memory/stats                       — counts + recent summary
+ *   DELETE /memory/clear                     — wipe all memory
+ */
+
+'use strict';
+
+const path = require('path');
+const rateLimit = require('express-rate-limit');
+
+let db = null;
+
+/* ── DB setup ────────────────────────────────────────────────────────────── */
+
+function initDb() {
+    if (db) return db;
+
+    let Database;
+    try {
+        Database = require('better-sqlite3');
+    } catch (e) {
+        console.warn('[memory] better-sqlite3 not installed — memory store disabled.');
+        console.warn('[memory] Run: cd companion-server && npm install');
+        return null;
+    }
+
+    const dbPath = process.env.MEMORY_DB_PATH ||
+                   path.join(__dirname, 'debbie_memory.db');
+
+    db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+
+    /* Long-term facts */
+    db.exec(`
+        CREATE TABLE IF NOT EXISTS facts (
+            key         TEXT PRIMARY KEY,
+            value       TEXT NOT NULL,
+            importance  INTEGER DEFAULT 5,
+            created_at  INTEGER NOT NULL,
+            updated_at  INTEGER NOT NULL
+        );
+    `);
+
+    /* Conversation turns — FTS5 for full-text retrieval */
+    db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS turns USING fts5(
+            role,
+            text,
+            session_id UNINDEXED,
+            ts         UNINDEXED,
+            tokenize = 'porter ascii'
+        );
+    `);
+
+    /* Regular table to track row count efficiently */
+    db.exec(`
+        CREATE TABLE IF NOT EXISTS turn_meta (
+            id         INTEGER PRIMARY KEY AUTOINCREMENT,
+            role       TEXT,
+            ts         INTEGER
+        );
+    `);
+
+    console.log(`[memory] SQLite memory store ready at ${dbPath}`);
+    return db;
+}
+
+/* ── Helpers ─────────────────────────────────────────────────────────────── */
+
+function nowMs() {
+    return Date.now();
+}
+
+function sanitiseText(t) {
+    if (typeof t !== 'string') return '';
+    return t.slice(0, 2000).replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}
+
+function sanitiseKey(k) {
+    if (typeof k !== 'string') return '';
+    return k.slice(0, 64).replace(/[^a-zA-Z0-9_\-\.]/g, '_');
+}
+
+/* ── Core operations ─────────────────────────────────────────────────────── */
+
+/**
+ * Store / update a long-term fact.
+ */
+function saveFact(key, value, importance = 5) {
+    if (!db) return false;
+    const k = sanitiseKey(key);
+    const v = sanitiseText(value);
+    const imp = Math.min(10, Math.max(0, parseInt(importance, 10) || 5));
+    const now = nowMs();
+
+    db.prepare(`
+        INSERT INTO facts (key, value, importance, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+            value      = excluded.value,
+            importance = excluded.importance,
+            updated_at = excluded.updated_at
+    `).run(k, v, imp, now, now);
+    return true;
+}
+
+/**
+ * Store a conversation turn.
+ * Prunes oldest turns when count exceeds maxTurns.
+ */
+function saveTurn(role, text, sessionId = 'default', maxTurns = 500) {
+    if (!db) return false;
+    const r   = role === 'assistant' ? 'assistant' : 'user';
+    const t   = sanitiseText(text);
+    const now = nowMs();
+
+    db.prepare(`INSERT INTO turns (role, text, session_id, ts) VALUES (?, ?, ?, ?)`)
+      .run(r, t, sessionId, now);
+    db.prepare(`INSERT INTO turn_meta (role, ts) VALUES (?, ?)`)
+      .run(r, now);
+
+    /* Prune if over limit */
+    const countRow = db.prepare(`SELECT COUNT(*) AS n FROM turn_meta`).get();
+    if (countRow && countRow.n > maxTurns) {
+        const overage = countRow.n - maxTurns;
+        /* Delete oldest from FTS — need rowids */
+        const oldRows = db.prepare(
+            `SELECT id FROM turn_meta ORDER BY id ASC LIMIT ?`
+        ).all(overage);
+        const stmt = db.prepare(`DELETE FROM turns WHERE rowid = ?`);
+        const del  = db.prepare(`DELETE FROM turn_meta WHERE id = ?`);
+        for (const row of oldRows) {
+            stmt.run(row.id);
+            del.run(row.id);
+        }
+    }
+    return true;
+}
+
+/**
+ * Full-text search over turns and facts, returning the top `limit` results.
+ * Falls back to recency-based retrieval when the query is empty.
+ */
+function queryMemory(queryText, limit = 5) {
+    if (!db) return [];
+    const lim = Math.min(20, Math.max(1, parseInt(limit, 10) || 5));
+    const results = [];
+
+    if (queryText && queryText.trim().length > 0) {
+        /* FTS5 search over turns — wrap in try/catch for malformed queries */
+        try {
+            const q = sanitiseText(queryText).trim();
+            const rows = db.prepare(`
+                SELECT role, text, ts,
+                       rank AS score
+                FROM   turns
+                WHERE  turns MATCH ?
+                ORDER  BY rank
+                LIMIT  ?
+            `).all(q, lim);
+
+            for (const r of rows) {
+                results.push({
+                    source:    'conversation',
+                    role:      r.role,
+                    text:      r.text,
+                    timestamp: r.ts,
+                });
+            }
+        } catch (_) {
+            /* Fall through to recency fallback */
+        }
+
+        /* Also search facts */
+        const factRows = db.prepare(`
+            SELECT key, value, importance, updated_at
+            FROM   facts
+            WHERE  LOWER(key)   LIKE '%' || LOWER(?) || '%'
+               OR  LOWER(value) LIKE '%' || LOWER(?) || '%'
+            ORDER  BY importance DESC, updated_at DESC
+            LIMIT  ?
+        `).all(queryText, queryText, lim);
+
+        for (const r of factRows) {
+            results.push({
+                source:    'fact',
+                key:       r.key,
+                text:      `${r.key}: ${r.value}`,
+                timestamp: r.updated_at,
+            });
+        }
+    } else {
+        /* No query — return most recent turns */
+        const rows = db.prepare(`
+            SELECT role, text, ts FROM turns
+            ORDER  BY ts DESC
+            LIMIT  ?
+        `).all(lim);
+        for (const r of rows) {
+            results.push({
+                source:    'conversation',
+                role:      r.role,
+                text:      r.text,
+                timestamp: r.ts,
+            });
+        }
+    }
+
+    /* Sort by relevance then recency */
+    results.sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0));
+    return results.slice(0, lim);
+}
+
+/**
+ * Return summary statistics.
+ */
+function getStats() {
+    if (!db) return { enabled: false };
+    const factCount = db.prepare(`SELECT COUNT(*) AS n FROM facts`).get().n;
+    const turnCount = db.prepare(`SELECT COUNT(*) AS n FROM turn_meta`).get().n;
+    const recent = db.prepare(`
+        SELECT role, text, ts FROM turns ORDER BY ts DESC LIMIT 5
+    `).all();
+    return { enabled: true, facts: factCount, turns: turnCount, recent };
+}
+
+/**
+ * Wipe all stored memory.
+ */
+function clearAll() {
+    if (!db) return;
+    db.exec(`DELETE FROM facts; DELETE FROM turns; DELETE FROM turn_meta;`);
+    console.log('[memory] All memory cleared');
+}
+
+/* ── Express route handler ───────────────────────────────────────────────── */
+
+const memLimiter = rateLimit({
+    windowMs: 60000,
+    max: 120,
+    standardHeaders: true,
+    legacyHeaders: false,
+    handler: (req, res) => {
+        res.status(429).json({ error: 'Too many memory requests, please slow down.' });
+    },
+});
+
+function addMemoryRoutes(app) {
+    /* Lazy-initialise the DB */
+    const database = initDb();
+    if (!database) {
+        /* If better-sqlite3 is missing, mount stub routes that return 503 */
+        app.use('/memory', (req, res) => {
+            res.status(503).json({
+                error: 'Memory store not available. Run: npm install',
+            });
+        });
+        return;
+    }
+
+    /* GET /memory/query?q=<text>&limit=<n> */
+    app.get('/memory/query', memLimiter, (req, res) => {
+        const q     = typeof req.query.q === 'string' ? req.query.q : '';
+        const limit = parseInt(req.query.limit, 10) || 5;
+        const memories = queryMemory(q, limit);
+        res.json({ ok: true, query: q, memories });
+    });
+
+    /* POST /memory/turn — { role, text, session_id? } */
+    app.post('/memory/turn', memLimiter, (req, res) => {
+        const { role = 'user', text = '', session_id = 'default' } = req.body || {};
+        if (!text) return res.status(400).json({ error: 'text required' });
+        saveTurn(role, text, session_id);
+        res.json({ ok: true });
+    });
+
+    /* POST /memory/fact — { key, value, importance? } */
+    app.post('/memory/fact', memLimiter, (req, res) => {
+        const { key = '', value = '', importance = 5 } = req.body || {};
+        if (!key || !value) return res.status(400).json({ error: 'key and value required' });
+        const ok = saveFact(key, value, importance);
+        res.json({ ok });
+    });
+
+    /* GET /memory/stats */
+    app.get('/memory/stats', memLimiter, (req, res) => {
+        res.json(getStats());
+    });
+
+    /* DELETE /memory/clear */
+    app.delete('/memory/clear', memLimiter, (req, res) => {
+        clearAll();
+        res.json({ ok: true });
+    });
+
+    console.log('[memory] Routes mounted: /memory/{query,turn,fact,stats,clear}');
+}
+
+module.exports = { addMemoryRoutes, saveFact, saveTurn, queryMemory, getStats, clearAll, initDb };
diff --git a/companion-server/network_tools.js b/companion-server/network_tools.js
new file mode 100644
index 0000000..028d77b
--- /dev/null
+++ b/companion-server/network_tools.js
@@ -0,0 +1,451 @@
+/**
+ * network_tools.js — Companion server network security tools
+ *
+ * ⚠️  AUTHORISED USE ONLY ⚠️
+ * Only use on networks you own or have explicit written permission to test.
+ * Unauthorised network scanning is illegal in most jurisdictions.
+ *
+ * Provides:
+ *  • nmap wrapper (if installed) for advanced scanning
+ *  • NVD CVE API queries
+ *  • Shodan-style local device fingerprinting
+ *  • HTML vulnerability report generation
+ *  • MAC vendor OUI lookup
+ *  • Network topology mapping
+ */
+
+const { execFile } = require('child_process');
+const https        = require('https');
+const path         = require('path');
+const fs           = require('fs');
+const os           = require('os');
+
+/* ── nmap wrapper ─────────────────────────────────────────────────────────── */
+
+/**
+ * Run nmap on the given target and return parsed JSON results.
+ * Requires nmap to be installed: apt install nmap (Linux) or https://nmap.org
+ *
+ * @param {string} target  - IP, CIDR, or hostname (e.g. "192.168.1.0/24")
+ * @param {string[]} flags - Extra nmap flags (e.g. ['-sV', '-O'])
+ * @returns {Promise<object>} Parsed nmap XML results as JSON
+ */
+async function nmapScan(target, flags = []) {
+    return new Promise((resolve, reject) => {
+        const args = [
+            '-oX', '-',           /* XML to stdout */
+            '--stats-every', '5s',
+            '-T4',                /* Aggressive timing */
+            '--open',             /* Only show open ports */
+            ...flags,
+            '--',
+            target,
+        ];
+
+        execFile('nmap', args, { maxBuffer: 5 * 1024 * 1024, timeout: 300000 },
+            (err, stdout, stderr) => {
+                if (err && !stdout) {
+                    if (err.code === 'ENOENT') {
+                        reject(new Error(
+                            'nmap not found. Install with: sudo apt install nmap\n' +
+                            'or download from https://nmap.org'));
+                    } else {
+                        reject(new Error(`nmap failed: ${err.message}`));
+                    }
+                    return;
+                }
+                try {
+                    resolve(parseNmapXml(stdout));
+                } catch (e) {
+                    reject(new Error(`nmap XML parse failed: ${e.message}`));
+                }
+            }
+        );
+    });
+}
+
+/**
+ * Parse nmap XML output to a clean JSON structure.
+ */
+function parseNmapXml(xml) {
+    const hosts = [];
+    /* Simple regex-based extraction — use xml2js for production */
+    const hostRegex = /<host[^>]*>([\s\S]*?)<\/host>/g;
+    let hostMatch;
+
+    while ((hostMatch = hostRegex.exec(xml)) !== null) {
+        const hostXml = hostMatch[1];
+
+        /* State */
+        const stateMatch = /<status state="([^"]+)"/.exec(hostXml);
+        if (!stateMatch || stateMatch[1] !== 'up') continue;
+
+        /* IP */
+        const ipMatch = /<address addr="([^"]+)" addrtype="ipv4"/.exec(hostXml);
+        const macMatch = /<address addr="([^"]+)" addrtype="mac"(?:[^>]*)vendor="([^"]*)"/.exec(hostXml);
+        const hostnameMatch = /<hostname name="([^"]+)"/.exec(hostXml);
+
+        const host = {
+            ip:       ipMatch ? ipMatch[1] : '?',
+            mac:      macMatch ? macMatch[1] : '',
+            vendor:   macMatch ? macMatch[2] : '',
+            hostname: hostnameMatch ? hostnameMatch[1] : '',
+            ports:    [],
+            os:       [],
+        };
+
+        /* Ports */
+        const portRegex = /<port protocol="([^"]+)" portid="(\d+)">([\s\S]*?)<\/port>/g;
+        let portMatch;
+        while ((portMatch = portRegex.exec(hostXml)) !== null) {
+            const portXml = portMatch[3];
+            const pStateMatch = /<state state="([^"]+)"/.exec(portXml);
+            if (!pStateMatch || pStateMatch[1] !== 'open') continue;
+
+            const serviceMatch = /<service name="([^"]*)"(?:[^>]*)product="([^"]*)"(?:[^>]*)version="([^"]*)"/.exec(portXml);
+            const bannerMatch  = /<script id="banner" output="([^"]*)"/.exec(portXml);
+
+            host.ports.push({
+                port:    parseInt(portMatch[2]),
+                proto:   portMatch[1],
+                service: serviceMatch ? serviceMatch[1] : '',
+                product: serviceMatch ? serviceMatch[2] : '',
+                version: serviceMatch ? serviceMatch[3] : '',
+                banner:  bannerMatch ? bannerMatch[1] : '',
+            });
+        }
+
+        /* OS detection */
+        const osMatch = /<osmatch name="([^"]+)" accuracy="(\d+)"/.exec(hostXml);
+        if (osMatch) {
+            host.os.push({ name: osMatch[1], accuracy: parseInt(osMatch[2]) });
+        }
+
+        hosts.push(host);
+    }
+
+    const runMatch  = /<runstats>[\s\S]*?<finished time="(\d+)"/.exec(xml);
+    const timeMatch = /<runstats>[\s\S]*?elapsed="([^"]+)"/.exec(xml);
+
+    return {
+        hosts,
+        scan_time:    runMatch ? parseInt(runMatch[1]) : Date.now() / 1000,
+        elapsed_secs: timeMatch ? parseFloat(timeMatch[1]) : 0,
+    };
+}
+
+/* ── NVD CVE API ─────────────────────────────────────────────────────────── */
+
+/**
+ * Look up CVE details from the NIST NVD API v2.
+ * Rate limit: 5 requests per 30 seconds without API key.
+ *
+ * @param {string} cveId - e.g. "CVE-2021-44228"
+ */
+function cve_lookup(cveId) {
+    return new Promise((resolve, reject) => {
+        const url = `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=${encodeURIComponent(cveId)}`;
+        const options = {
+            headers: {
+                'User-Agent': 'Debbie-Companion/1.0',
+                ...(process.env.NVD_API_KEY
+                    ? { 'apiKey': process.env.NVD_API_KEY }
+                    : {})
+            }
+        };
+
+        https.get(url, options, (res) => {
+            let data = '';
+            res.on('data', chunk => { data += chunk; });
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(data);
+                    const vuln = json.vulnerabilities?.[0]?.cve;
+                    if (!vuln) {
+                        resolve({ error: 'CVE not found', id: cveId });
+                        return;
+                    }
+
+                    const desc = vuln.descriptions?.find(d => d.lang === 'en');
+                    const cvss31 = vuln.metrics?.cvssMetricV31?.[0]?.cvssData;
+                    const cvss30 = vuln.metrics?.cvssMetricV30?.[0]?.cvssData;
+                    const cvss = cvss31 || cvss30;
+
+                    resolve({
+                        id:          cveId,
+                        description: desc?.value || 'No description',
+                        cvss_score:  cvss?.baseScore,
+                        severity:    cvss?.baseSeverity,
+                        vector:      cvss?.vectorString,
+                        published:   vuln.published,
+                        modified:    vuln.lastModified,
+                        references:  vuln.references?.slice(0, 5).map(r => r.url) || [],
+                    });
+                } catch (e) {
+                    reject(new Error(`Parse error: ${e.message}`));
+                }
+            });
+        }).on('error', reject);
+    });
+}
+
+/* ── HTML report generator ───────────────────────────────────────────────── */
+
+/** Escape special HTML characters to prevent XSS in generated reports. */
+function escapeHtml(str) {
+    if (typeof str !== 'string') return String(str);
+    return str
+        .replace(/&/g,  '&amp;')
+        .replace(/</g,  '&lt;')
+        .replace(/>/g,  '&gt;')
+        .replace(/"/g,  '&quot;')
+        .replace(/'/g,  '&#039;');
+}
+
+/**
+ * Generate a full HTML vulnerability report from scan + vuln data.
+ *
+ * @param {object} scanData   - From net_scanner_results_to_json()
+ * @param {object} vulnData   - From vuln_reporter_to_json()
+ * @returns {string} HTML report
+ */
+function generateHtmlReport(scanData, vulnData) {
+    const scan = typeof scanData === 'string' ? JSON.parse(scanData) : scanData;
+    const vuln = typeof vulnData === 'string' ? JSON.parse(vulnData) : vulnData;
+
+    const now = new Date().toLocaleString();
+
+    const sevBadge = (sev) => {
+        const allowed = { CRITICAL: '#e74c3c', HIGH: '#e67e22', MEDIUM: '#f39c12', LOW: '#27ae60', INFO: '#3498db' };
+        const sevSafe = escapeHtml(sev || '');
+        const col = allowed[sevSafe] || '#95a5a6';
+        return `<span style="background:${col};color:#fff;padding:2px 8px;border-radius:4px;font-size:.8em;font-weight:700">${sevSafe}</span>`;
+    };
+
+    const hostsHtml = (scan.hosts || []).map(h => `
+        <tr>
+          <td><code>${escapeHtml(h.ip || '')}</code></td>
+          <td>${escapeHtml(h.vendor || '?')}</td>
+          <td>${escapeHtml(h.hostname || '')}</td>
+          <td>${(h.open_ports || []).map(p =>
+              `<span title="${escapeHtml(String(p.service || ''))}">${escapeHtml(String(p.port || ''))}</span>`).join(', ') ||
+              (typeof h.open_ports === 'number' ? escapeHtml(String(h.open_ports)) + ' ports' : '—')}</td>
+          <td>
+            <div style="background:#2d3436;border-radius:4px;height:8px;width:100px;overflow:hidden">
+              <div style="background:${h.risk_score > 60 ? '#e74c3c' : h.risk_score > 30 ? '#e67e22' : '#27ae60'};height:100%;width:${Math.min(Number(h.risk_score) || 0, 100)}%"></div>
+            </div>
+            ${Number(h.risk_score) || 0}/100
+          </td>
+        </tr>`).join('');
+
+    const wifiHtml = (scan.wifi_networks || []).map(ap => `
+        <tr>
+          <td>${ap.ssid ? escapeHtml(ap.ssid) : '<em>hidden</em>'}</td>
+          <td><code>${escapeHtml(ap.bssid || '')}</code></td>
+          <td>${escapeHtml(String(ap.channel || ''))}</td>
+          <td>${escapeHtml(String(ap.rssi || ''))} dBm</td>
+          <td>${ap.security === 'OPEN' ?
+              '<span style="color:#e74c3c;font-weight:700">OPEN (unencrypted)</span>' :
+              ap.security === 'WEP' ?
+              '<span style="color:#e74c3c;font-weight:700">WEP (BROKEN)</span>' :
+              `<span style="color:#27ae60">${escapeHtml(ap.security || '')}</span>`}</td>
+        </tr>`).join('');
+
+    const findingsHtml = (vuln.findings || []).map(f => `
+        <div style="border-left:4px solid ${
+            f.severity === 'CRITICAL' ? '#e74c3c' :
+            f.severity === 'HIGH'     ? '#e67e22' :
+            f.severity === 'MEDIUM'   ? '#f39c12' : '#27ae60'
+        };padding:12px 16px;margin:12px 0;background:#1a1a2e;border-radius:0 8px 8px 0">
+          <div style="margin-bottom:6px">
+            ${sevBadge(f.severity)}
+            <code style="margin-left:8px;color:#aaa">${escapeHtml(f.id || '')}</code>
+            ${f.affected_ip ? `<code style="margin-left:8px">${escapeHtml(f.affected_ip)}${f.affected_port ? ':' + escapeHtml(String(f.affected_port)) : ''}</code>` : ''}
+          </div>
+          <strong>${escapeHtml(f.title || '')}</strong>
+          <p style="color:#ccc;margin:6px 0">${escapeHtml(f.description || '')}</p>
+          <p style="color:#06d6a0"><strong>Fix:</strong> ${escapeHtml(f.remediation || '')}</p>
+        </div>`).join('');
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+  <title>Debbie — Network Security Report</title>
+  <style>
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{font-family:system-ui,sans-serif;background:#0d0d1a;color:#eee;line-height:1.6}
+    .hero{background:linear-gradient(135deg,#0f3460,#533483);padding:40px;text-align:center}
+    .hero h1{font-size:2rem;margin-bottom:8px}
+    .warning{background:#4d1a00;border:1px solid #e67e22;padding:12px 20px;
+      border-radius:8px;margin:16px auto;max-width:900px;font-size:.9rem}
+    .section{max-width:960px;margin:24px auto;padding:0 20px}
+    h2{color:#06d6a0;margin-bottom:16px;border-bottom:1px solid #333;padding-bottom:8px}
+    .stats{display:flex;gap:12px;flex-wrap:wrap;margin-bottom:24px}
+    .stat-card{background:#12122a;border-radius:12px;padding:16px 24px;text-align:center;min-width:120px;flex:1}
+    .stat-card .num{font-size:2rem;font-weight:700;margin-bottom:4px}
+    .stat-card .lbl{color:#aaa;font-size:.85rem}
+    .crit{color:#e74c3c} .high{color:#e67e22} .med{color:#f39c12} .low{color:#27ae60}
+    table{width:100%;border-collapse:collapse;margin-bottom:24px;background:#12122a;border-radius:12px;overflow:hidden}
+    th{background:#0f3460;padding:10px 14px;text-align:left;color:#aaa;font-size:.85rem}
+    td{padding:10px 14px;border-bottom:1px solid #1a1a2e;font-size:.9rem}
+    tr:last-child td{border-bottom:none}
+    code{background:#1a1a2e;padding:2px 6px;border-radius:4px;font-size:.85em;color:#06d6a0}
+    .footer{text-align:center;padding:32px;color:#555;font-size:.85rem}
+  </style>
+</head>
+<body>
+<div class="hero">
+  <h1>Debbie — Network Security Report</h1>
+  <p>Generated: ${escapeHtml(now)} | Network: ${escapeHtml(scan.own_ip || '?')} | Gateway: ${escapeHtml(scan.gateway_ip || '?')}</p>
+</div>
+
+<div class="warning">
+  <strong>⚠️ Authorised Use Only</strong> — This report was generated for a network
+  you own or have explicit written permission to test. Unauthorised network scanning
+  is illegal under the Computer Misuse Act (UK), CFAA (US), and similar laws worldwide.
+</div>
+
+<div class="section">
+  <div class="stats">
+    <div class="stat-card"><div class="num">${vuln.total_findings || 0}</div><div class="lbl">Total Findings</div></div>
+    <div class="stat-card"><div class="num crit">${vuln.critical || 0}</div><div class="lbl">Critical</div></div>
+    <div class="stat-card"><div class="num high">${vuln.high || 0}</div><div class="lbl">High</div></div>
+    <div class="stat-card"><div class="num med">${vuln.medium || 0}</div><div class="lbl">Medium</div></div>
+    <div class="stat-card"><div class="num low">${vuln.low || 0}</div><div class="lbl">Low</div></div>
+    <div class="stat-card"><div class="num">${scan.hosts?.length || vuln.hosts_scanned || 0}</div><div class="lbl">Hosts Scanned</div></div>
+    <div class="stat-card"><div class="num">${scan.wifi_networks?.length || 0}</div><div class="lbl">WiFi Networks</div></div>
+  </div>
+</div>
+
+<div class="section">
+  <h2>🔴 Security Findings</h2>
+  ${findingsHtml || '<p style="color:#888">No vulnerabilities found — network looks clean!</p>'}
+</div>
+
+<div class="section">
+  <h2>🖥️ Discovered Hosts</h2>
+  <table>
+    <thead><tr><th>IP</th><th>Vendor</th><th>Hostname</th><th>Open Ports</th><th>Risk Score</th></tr></thead>
+    <tbody>${hostsHtml || '<tr><td colspan="5" style="text-align:center;color:#888">No hosts found</td></tr>'}</tbody>
+  </table>
+</div>
+
+<div class="section">
+  <h2>📶 Visible WiFi Networks</h2>
+  <table>
+    <thead><tr><th>SSID</th><th>BSSID</th><th>Channel</th><th>Signal</th><th>Security</th></tr></thead>
+    <tbody>${wifiHtml || '<tr><td colspan="5" style="text-align:center;color:#888">No networks found</td></tr>'}</tbody>
+  </table>
+</div>
+
+<div class="footer">
+  Generated by <strong>Debbie</strong> — Portable AI Security Assistant |
+  Freenove Media Kit ESP32-S3 | ${now}
+</div>
+</body>
+</html>`;
+}
+
+/* ── Last scan results stored server-side (avoids accepting raw HTML data from clients) */
+let lastScanData  = null;
+let lastVulnData  = null;
+
+/**
+ * Store scan results on the server for later report generation.
+ * Called by the device WebSocket handler when scan data arrives.
+ */
+function storeScanResults(scan, vulns) {
+    lastScanData = scan;
+    lastVulnData = vulns;
+}
+
+function addNetworkRoutes(app, broadcast) {
+    /* Rate limiter for scan endpoint */
+    const scanLimiter = rateLimit({ windowMs: 60000, max: 3 });
+    const cveLimiter  = rateLimit({ windowMs: 30000, max: 5 });
+
+    /* POST /network/scan — trigger nmap if available */
+    app.post('/network/scan', scanLimiter, async (req, res) => {
+        const ip = req.socket.remoteAddress || 'unknown';
+        const { target = '192.168.1.0/24', flags = [] } = req.body;
+
+        /*
+         * Validate target strictly: only allow IPs, CIDRs, and hostnames.
+         * Reject anything that could be shell metacharacters.
+         * Also disallow scanning public internet ranges from this endpoint.
+         */
+        if (!/^[0-9./a-zA-Z-]+$/.test(target) || target.length > 64) {
+            return res.status(400).json({ error: 'Invalid target format' });
+        }
+
+        /* Only allow private ranges (RFC 1918) and loopback */
+        const isPrivate = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|127\.|::1)/.test(target);
+        if (!isPrivate && !target.endsWith('.local')) {
+            return res.status(400).json({
+                error: 'Only private network ranges (10.x, 172.16-31.x, 192.168.x) are permitted. ' +
+                       'This tool is for authorised testing of your own network only.'
+            });
+        }
+
+        /* Only allow safe nmap flags */
+        const ALLOWED_FLAGS = new Set(['-sV', '-O', '-sn', '-p', '--open', '-T3', '-T4', '-A']);
+        if (!Array.isArray(flags) || flags.some(f => !ALLOWED_FLAGS.has(f) && !/^-p[\s\d,-]+$/.test(f))) {
+            return res.status(400).json({ error: 'Invalid nmap flags' });
+        }
+
+        try {
+            const results = await nmapScan(target, flags);
+            storeScanResults(results, null);
+            broadcast({
+                type:    'agent',
+                sender:  'Network Scanner',
+                preview: `nmap scan of ${target}: ${results.hosts.length} hosts found`,
+            });
+            res.json({ ok: true, results });
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    /* GET /network/cve/:id */
+    app.get('/network/cve/:id', cveLimiter, async (req, res) => {
+        const cveId = req.params.id;
+        /* Enforce valid CVE format: year 1999–current+1, 4+ digit sequence */
+        if (!/^CVE-(199[9]|2[0-9]{3})-\d{4,}$/i.test(cveId)) {
+            return res.status(400).json({ error: 'Invalid CVE ID format (e.g. CVE-2021-44228)' });
+        }
+        try {
+            const result = await cve_lookup(cveId.toUpperCase());
+            res.json(result);
+        } catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    /* POST /network/results — store scan results from device */
+    app.post('/network/results', (req, res) => {
+        const { scan, vulns } = req.body;
+        if (!scan) return res.status(400).json({ error: 'scan data required' });
+        storeScanResults(scan, vulns || null);
+        res.json({ ok: true });
+    });
+
+    /* GET /network/report — generate HTML report from last stored scan results */
+    app.get('/network/report', (req, res) => {
+        if (!lastScanData) {
+            return res.status(404).json({ error: 'No scan results available. Run a scan first.' });
+        }
+        const html = generateHtmlReport(lastScanData, lastVulnData || {});
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.send(html);
+    });
+
+    console.log('[network] Routes registered: /network/scan, /network/cve/:id, /network/results, /network/report');
+}
+
+module.exports = { nmapScan, cve_lookup, generateHtmlReport, addNetworkRoutes, storeScanResults };
diff --git a/companion-server/package.json b/companion-server/package.json
new file mode 100644
index 0000000..769bf63
--- /dev/null
+++ b/companion-server/package.json
@@ -0,0 +1,31 @@
+{
+  "name": "debbie-companion-server",
+  "version": "1.0.0",
+  "description": "Companion server for Debbie — bridges WhatsApp, Email, Spotify and your custom agent to the ESP32-S3 device",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "nodemon server.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.5.0",
+    "ws": "^8.14.2",
+    "whatsapp-web.js": "^1.23.0",
+    "qrcode-terminal": "^0.12.0",
+    "imap": "^0.8.19",
+    "mailparser": "^3.6.5",
+    "spotify-web-api-node": "^5.0.2",
+    "dotenv": "^16.3.1",
+    "axios": "^1.6.0",
+    "node-cron": "^3.0.3",
+    "cors": "^2.8.5",
+    "better-sqlite3": "^9.4.3"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
diff --git a/companion-server/server.js b/companion-server/server.js
new file mode 100644
index 0000000..fc7fdd2
--- /dev/null
+++ b/companion-server/server.js
@@ -0,0 +1,199 @@
+/**
+ * Debbie Companion Server
+ *
+ * Bridges notifications and services to the Debbie ESP32-S3 device.
+ *
+ * Architecture:
+ *   ┌──────────────┐     WebSocket      ┌─────────────────┐
+ *   │  Debbie ESP32│ ◄────────────────► │ Companion Server│
+ *   └──────────────┘     push/cmd       └────────┬────────┘
+ *                                                 │
+ *               ┌──────────────────────────────┐  │
+ *               │  WhatsApp Web  │  IMAP Email  │  │
+ *               │  Spotify API   │  Custom Agent│  │
+ *               └──────────────────────────────┘  │
+ */
+
+require('dotenv').config();
+const express    = require('express');
+const http       = require('http');
+const { WebSocketServer, WebSocket } = require('ws');
+const cors       = require('cors');
+const rateLimit  = require('express-rate-limit');
+
+const { startWhatsApp } = require('./whatsapp');
+const { startEmailMonitor } = require('./email_monitor');
+const { SpotifyController } = require('./spotify');
+const { AgentBridge } = require('./agent_bridge');
+const { addNetworkRoutes, storeScanResults } = require('./network_tools');
+const { addMemoryRoutes } = require('./memory_store');
+
+const app    = express();
+const server = http.createServer(app);
+const wss    = new WebSocketServer({ server });
+
+app.use(cors());
+app.use(express.json());
+
+/* ── Connected Debbie devices ─────────────────────────────────────────── */
+const devices = new Set();
+
+function broadcast(message) {
+    const payload = typeof message === 'string' ? message : JSON.stringify(message);
+    for (const ws of devices) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(payload);
+        }
+    }
+}
+
+/* ── Spotify instance ─────────────────────────────────────────────────── */
+let spotify = null;
+
+/* ── WebSocket handler ────────────────────────────────────────────────── */
+wss.on('connection', (ws, req) => {
+    const ip = req.socket.remoteAddress;
+    console.log(`[ws] Debbie device connected from ${ip}`);
+    devices.add(ws);
+
+    ws.send(JSON.stringify({
+        type: 'system',
+        sender: 'companion',
+        preview: `Connected to Debbie companion server v${require('./package.json').version}`,
+    }));
+
+    ws.on('message', async (data) => {
+        try {
+            const msg = JSON.parse(data.toString());
+            console.log('[ws] Received:', msg);
+
+            if (msg.type === 'scan_results') {
+                /* Device sends scan results — store for HTML report generation */
+                storeScanResults(msg.scan || null, msg.vulns || null);
+                console.log('[ws] Stored scan results from device');
+            } else if (msg.type === 'spotify_command') {
+                if (spotify) {
+                    const result = await spotify.handleCommand(msg.action);
+                    ws.send(JSON.stringify({
+                        type: 'spotify',
+                        sender: 'Spotify',
+                        preview: result,
+                    }));
+                } else {
+                    ws.send(JSON.stringify({
+                        type: 'spotify',
+                        sender: 'Spotify',
+                        preview: 'Spotify not configured. Add SPOTIFY_* vars to .env',
+                    }));
+                }
+            }
+        } catch (e) {
+            console.error('[ws] Message parse error:', e.message);
+        }
+    });
+
+    ws.on('close', () => {
+        console.log(`[ws] Device disconnected: ${ip}`);
+        devices.delete(ws);
+    });
+
+    ws.on('error', (err) => {
+        console.error('[ws] Error:', err.message);
+        devices.delete(ws);
+    });
+});
+
+/* ── Rate limiters ────────────────────────────────────────────────────── */
+const notifyLimiter = rateLimit({ windowMs: 60000, max: 30 });
+const spotifyLimiter = rateLimit({ windowMs: 60000, max: 60 });
+
+/* ── REST API ────────────────────────────────────────────────────────── */
+
+/* Health check */
+app.get('/health', (req, res) => {
+    res.json({
+        status: 'ok',
+        devices: devices.size,
+        uptime: process.uptime(),
+        version: require('./package.json').version,
+    });
+});
+
+/* Send a manual notification to all connected devices */
+app.post('/notify', notifyLimiter, (req, res) => {
+    const { type = 'system', sender = 'Server', preview = '' } = req.body;
+    broadcast({ type, sender, preview });
+    res.json({ ok: true, sent_to: devices.size });
+});
+
+/* Spotify control via REST */
+app.post('/spotify', spotifyLimiter, async (req, res) => {
+    if (!spotify) return res.status(503).json({ error: 'Spotify not configured' });
+    const { action } = req.body;
+    const result = await spotify.handleCommand(action);
+    broadcast({ type: 'spotify', sender: 'Spotify', preview: result });
+    res.json({ ok: true, result });
+});
+
+/* ── Start all integrations ──────────────────────────────────────────── */
+
+async function main() {
+    const PORT = process.env.PORT || 3001;
+
+    /* Spotify */
+    if (process.env.SPOTIFY_CLIENT_ID && process.env.SPOTIFY_CLIENT_SECRET) {
+        spotify = new SpotifyController();
+        await spotify.init();
+        console.log('[spotify] Controller ready');
+    } else {
+        console.warn('[spotify] No credentials in .env — Spotify disabled');
+    }
+
+    /* WhatsApp */
+    if (process.env.WHATSAPP_ENABLED !== 'false') {
+        try {
+            startWhatsApp((notification) => {
+                console.log('[whatsapp] Notification:', notification.sender);
+                broadcast(notification);
+            });
+        } catch (e) {
+            console.warn('[whatsapp] Could not start:', e.message);
+        }
+    }
+
+    /* Email */
+    if (process.env.EMAIL_HOST && process.env.EMAIL_USER) {
+        try {
+            startEmailMonitor((notification) => {
+                console.log('[email] New email from:', notification.sender);
+                broadcast(notification);
+            });
+        } catch (e) {
+            console.warn('[email] Could not start:', e.message);
+        }
+    } else {
+        console.warn('[email] No IMAP config in .env — email disabled');
+    }
+
+    /* Custom agent bridge */
+    if (process.env.AGENT_URL) {
+        const bridge = new AgentBridge(process.env.AGENT_URL, (notification) => {
+            broadcast(notification);
+        });
+        bridge.connect();
+    }
+
+    /* Network security tools */
+    addNetworkRoutes(app, broadcast);
+
+    /* Memory & RAG store */
+    addMemoryRoutes(app);
+
+    server.listen(PORT, '0.0.0.0', () => {
+        console.log(`\n🤖 Debbie Companion Server running on port ${PORT}`);
+        console.log(`   Devices can connect to: ws://<YOUR_IP>:${PORT}`);
+        console.log(`   Health check: http://localhost:${PORT}/health\n`);
+    });
+}
+
+main().catch(console.error);
diff --git a/companion-server/spotify.js b/companion-server/spotify.js
new file mode 100644
index 0000000..33714fe
--- /dev/null
+++ b/companion-server/spotify.js
@@ -0,0 +1,161 @@
+/**
+ * spotify.js — Spotify playback controller
+ *
+ * Uses the Spotify Web API via Client Credentials + Authorization Code flow.
+ *
+ * Setup:
+ *  1. Create an app at https://developer.spotify.com/dashboard
+ *  2. Set redirect URI to http://localhost:3001/spotify/callback
+ *  3. Add CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI to .env
+ *  4. On first run, visit http://localhost:3001/spotify/auth to authorise
+ */
+
+const SpotifyWebApi = require('spotify-web-api-node');
+const express    = require('express');
+const rateLimit  = require('express-rate-limit');
+
+class SpotifyController {
+    constructor() {
+        this.api = new SpotifyWebApi({
+            clientId:     process.env.SPOTIFY_CLIENT_ID,
+            clientSecret: process.env.SPOTIFY_CLIENT_SECRET,
+            redirectUri:  process.env.SPOTIFY_REDIRECT_URI || 'http://localhost:3001/spotify/callback',
+        });
+
+        this.currentTrack    = null;
+        this.tokenExpiresAt  = 0;
+        this._refreshToken   = process.env.SPOTIFY_REFRESH_TOKEN || null;
+    }
+
+    async init() {
+        if (this._refreshToken) {
+            await this._refreshAccessToken();
+        } else {
+            console.warn('[spotify] No refresh token — visit /spotify/auth to authorise');
+        }
+    }
+
+    async _refreshAccessToken() {
+        try {
+            this.api.setRefreshToken(this._refreshToken);
+            const data = await this.api.refreshAccessToken();
+            this.api.setAccessToken(data.body.access_token);
+            this.tokenExpiresAt = Date.now() + (data.body.expires_in - 60) * 1000;
+            console.log('[spotify] Access token refreshed');
+        } catch (e) {
+            console.error('[spotify] Token refresh failed:', e.message);
+        }
+    }
+
+    async _ensureToken() {
+        if (Date.now() > this.tokenExpiresAt && this._refreshToken) {
+            await this._refreshAccessToken();
+        }
+    }
+
+    async handleCommand(action) {
+        await this._ensureToken();
+
+        try {
+            if (action === 'play') {
+                await this.api.play();
+                return '▶ Playing';
+
+            } else if (action === 'pause') {
+                await this.api.pause();
+                return '⏸ Paused';
+
+            } else if (action === 'next') {
+                await this.api.skipToNext();
+                return '⏭ Next track';
+
+            } else if (action === 'previous') {
+                await this.api.skipToPrevious();
+                return '⏮ Previous track';
+
+            } else if (action.startsWith('volume:')) {
+                const vol = parseInt(action.split(':')[1]);
+                await this.api.setVolume(vol);
+                return `🔊 Volume: ${vol}%`;
+
+            } else if (action.startsWith('search:')) {
+                const query = action.substring(7).trim();
+                const results = await this.api.searchTracks(query, { limit: 1 });
+                const tracks = results.body?.tracks?.items;
+                if (tracks && tracks.length > 0) {
+                    const track = tracks[0];
+                    await this.api.play({ uris: [track.uri] });
+                    const title  = track.name;
+                    const artist = track.artists[0]?.name || 'Unknown';
+                    this.currentTrack = { title, artist };
+                    return `▶ Now playing: ${artist} — ${title}`;
+                }
+                return `❌ No results for: ${query}`;
+
+            } else if (action === 'current') {
+                const playing = await this.api.getMyCurrentPlayingTrack();
+                const item = playing.body?.item;
+                if (item) {
+                    const title  = item.name;
+                    const artist = item.artists[0]?.name || 'Unknown';
+                    this.currentTrack = { title, artist };
+                    return `🎵 ${artist} — ${title}`;
+                }
+                return '⏹ Nothing playing';
+
+            } else {
+                return `❓ Unknown command: ${action}`;
+            }
+        } catch (e) {
+            console.error('[spotify] Command error:', e.message);
+            return `❌ Spotify error: ${e.message}`;
+        }
+    }
+
+    /** Express router for OAuth callback */
+    getRouter() {
+        const router = express.Router();
+
+        /* Rate limit: 5 auth attempts per 15 minutes per IP */
+        const authRateLimit = rateLimit({
+            windowMs:  15 * 60 * 1000,
+            max:       5,
+            message:   'Too many authentication attempts',
+        });
+
+        router.get('/auth', authRateLimit, (req, res) => {
+            const scopes = [
+                'user-read-playback-state',
+                'user-modify-playback-state',
+                'user-read-currently-playing',
+                'streaming',
+                'playlist-read-private',
+            ];
+            const url = this.api.createAuthorizeURL(scopes, 'debbie-state');
+            res.redirect(url);
+        });
+
+        router.get('/callback', authRateLimit, async (req, res) => {
+            const { code } = req.query;
+            try {
+                const data = await this.api.authorizationCodeGrant(code);
+                this.api.setAccessToken(data.body.access_token);
+                this._refreshToken = data.body.refresh_token;
+                this.tokenExpiresAt = Date.now() + (data.body.expires_in - 60) * 1000;
+                console.log('[spotify] ✅ Authorised!');
+                console.log('[spotify] Add this to your .env:');
+                console.log(`SPOTIFY_REFRESH_TOKEN=${this._refreshToken}`);
+                res.setHeader('Content-Security-Policy', "default-src 'none'");
+                res.send('<h1>Spotify linked to Debbie!</h1><p>You can close this window.</p>');
+            } catch (e) {
+                console.error('[spotify] Auth error:', e.message);
+                /* Return generic error to avoid reflecting exception details into HTML */
+                res.status(500).send('Authentication failed. Please try again.');
+            }
+        });
+
+        return router;
+    }
+}
+
+module.exports = { SpotifyController };
diff --git a/companion-server/whatsapp.js b/companion-server/whatsapp.js
new file mode 100644
index 0000000..37d12b0
--- /dev/null
+++ b/companion-server/whatsapp.js
@@ -0,0 +1,85 @@
+/**
+ * whatsapp.js — WhatsApp integration via whatsapp-web.js
+ *
+ * On first run, a QR code is printed to the terminal.
+ * Scan it with WhatsApp on your phone to link the account.
+ * The session is persisted via LocalAuth so you only need to scan once.
+ */
+
+const { Client, LocalAuth } = require('whatsapp-web.js');
+const qrcode = require('qrcode-terminal');
+
+function startWhatsApp(onNotification) {
+    const client = new Client({
+        authStrategy: new LocalAuth({ dataPath: './.wwebjs_auth' }),
+        puppeteer: {
+            headless: true,
+            args: [
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+                '--disable-dev-shm-usage',
+                '--disable-gpu',
+            ],
+        },
+    });
+
+    client.on('qr', (qr) => {
+        console.log('\n[whatsapp] ══════════════════════════════════════════');
+        console.log('[whatsapp] Scan this QR code with WhatsApp to link:');
+        console.log('[whatsapp] ══════════════════════════════════════════\n');
+        qrcode.generate(qr, { small: true });
+        console.log('\n[whatsapp] Waiting for scan...\n');
+    });
+
+    client.on('ready', () => {
+        console.log('[whatsapp] ✅ WhatsApp connected!');
+    });
+
+    client.on('disconnected', (reason) => {
+        console.warn('[whatsapp] Disconnected:', reason);
+    });
+
+    client.on('message', async (msg) => {
+        /* Only forward DMs and group mentions, skip status updates */
+        if (msg.from === 'status@broadcast') return;
+
+        try {
+            const contact = await msg.getContact();
+            const name    = contact.pushname || contact.number || msg.from;
+
+            /* Truncate preview for display */
+            let preview = msg.body || '[media]';
+            if (preview.length > 100) preview = preview.substring(0, 97) + '...';
+
+            onNotification({
+                type:    'whatsapp',
+                sender:  name,
+                preview: preview,
+            });
+        } catch (e) {
+            console.error('[whatsapp] Error processing message:', e.message);
+        }
+    });
+
+    /* Forward call notifications */
+    client.on('call', async (call) => {
+        try {
+            const contact = await call.getContact();
+            const name    = contact.pushname || contact.number || call.from;
+            onNotification({
+                type:    'whatsapp',
+                sender:  name,
+                preview: `📞 Incoming ${call.isVideo ? 'video' : 'voice'} call`,
+            });
+        } catch (e) { /* ignore */ }
+    });
+
+    client.initialize().catch((e) => {
+        console.error('[whatsapp] Failed to initialize:', e.message);
+        console.warn('[whatsapp] Make sure Chromium/Puppeteer is available');
+    });
+
+    return client;
+}
+
+module.exports = { startWhatsApp };
diff --git a/firmware/CMakeLists.txt b/firmware/CMakeLists.txt
new file mode 100644
index 0000000..29e917f
--- /dev/null
+++ b/firmware/CMakeLists.txt
@@ -0,0 +1,4 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(debbie)
diff --git a/firmware/main/CMakeLists.txt b/firmware/main/CMakeLists.txt
new file mode 100644
index 0000000..5e49b62
--- /dev/null
+++ b/firmware/main/CMakeLists.txt
@@ -0,0 +1,40 @@
+idf_component_register(
+    SRCS
+        "main.c"
+        "storage_manager.c"
+        "wifi_manager.c"
+        "bluetooth_manager.c"
+        "audio_manager.c"
+        "camera_manager.c"
+        "display_manager.c"
+        "openai_client.c"
+        "notification_client.c"
+        "web_server.c"
+        "network_scanner.c"
+        "vuln_reporter.c"
+        "self_agent.c"
+        "memory_manager.c"
+    INCLUDE_DIRS
+        "."
+    REQUIRES
+        nvs_flash
+        esp_wifi
+        esp_event
+        esp_netif
+        esp_http_client
+        esp_https_ota
+        esp_websocket_client
+        esp_http_server
+        esp_camera
+        esp_lcd
+        driver
+        lvgl
+        cJSON
+        mbedtls
+        esp_timer
+        freertos
+        log
+        lwip
+        ping
+        bt
+)
diff --git a/firmware/main/audio_manager.c b/firmware/main/audio_manager.c
new file mode 100644
index 0000000..93b6536
--- /dev/null
+++ b/firmware/main/audio_manager.c
@@ -0,0 +1,174 @@
+#include "audio_manager.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "driver/i2s_std.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include <math.h>
+#include <string.h>
+#include <stdlib.h>
+
+static const char *TAG = "audio";
+
+#define BUF_SAMPLES  ((AUDIO_SAMPLE_RATE * AUDIO_BUF_MS) / 1000)
+#define BUF_BYTES    (BUF_SAMPLES * sizeof(int16_t))
+
+static i2s_chan_handle_t   s_rx_chan = NULL;
+static i2s_chan_handle_t   s_tx_chan = NULL;
+static TaskHandle_t        s_cap_task = NULL;
+static audio_capture_cb_t  s_cap_cb  = NULL;
+static uint8_t             s_volume  = 75;
+static bool                s_capturing = false;
+
+/* ── Volume scaling ──────────────────────────────────────────────────────── */
+
+static void scale_volume(int16_t *buf, size_t count)
+{
+    float gain = s_volume / 100.0f;
+    for (size_t i = 0; i < count; i++) {
+        int32_t v = (int32_t)buf[i] * (int32_t)(gain * 256) >> 8;
+        buf[i] = (int16_t)(v > 32767 ? 32767 : (v < -32768 ? -32768 : v));
+    }
+}
+
+/* ── Capture task ────────────────────────────────────────────────────────── */
+
+static void capture_task(void *pvParam)
+{
+    int16_t *buf = malloc(BUF_BYTES);
+    if (!buf) { ESP_LOGE(TAG, "OOM in capture task"); vTaskDelete(NULL); return; }
+
+    while (s_capturing) {
+        size_t bytes_read = 0;
+        esp_err_t err = i2s_channel_read(s_rx_chan, buf,
+                                         BUF_BYTES, &bytes_read,
+                                         pdMS_TO_TICKS(100));
+        if (err == ESP_OK && bytes_read > 0 && s_cap_cb) {
+            s_cap_cb(buf, bytes_read / sizeof(int16_t));
+        }
+    }
+    free(buf);
+    vTaskDelete(NULL);
+}
+
+/* ── Public API ──────────────────────────────────────────────────────────── */
+
+esp_err_t audio_manager_init(void)
+{
+    /* ── Microphone (RX) channel ── */
+    i2s_chan_config_t rx_cfg = I2S_CHANNEL_DEFAULT_CONFIG(
+        I2S_MIC_PORT, I2S_ROLE_MASTER);
+    ESP_ERROR_CHECK(i2s_new_channel(&rx_cfg, NULL, &s_rx_chan));
+
+    i2s_std_config_t rx_std = {
+        .clk_cfg  = I2S_STD_CLK_DEFAULT_CONFIG(AUDIO_SAMPLE_RATE),
+        .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(
+                        I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_MONO),
+        .gpio_cfg = {
+            .mclk = I2S_GPIO_UNUSED,
+            .bclk = I2S_MIC_SCK,
+            .ws   = I2S_MIC_WS,
+            .dout = I2S_GPIO_UNUSED,
+            .din  = I2S_MIC_SD,
+            .invert_flags = { .mclk_inv = false, .bclk_inv = false, .ws_inv = false },
+        },
+    };
+    ESP_ERROR_CHECK(i2s_channel_init_std_mode(s_rx_chan, &rx_std));
+
+    /* ── Speaker (TX) channel ── */
+    i2s_chan_config_t tx_cfg = I2S_CHANNEL_DEFAULT_CONFIG(
+        I2S_SPK_PORT, I2S_ROLE_MASTER);
+    ESP_ERROR_CHECK(i2s_new_channel(&tx_cfg, &s_tx_chan, NULL));
+
+    i2s_std_config_t tx_std = {
+        .clk_cfg  = I2S_STD_CLK_DEFAULT_CONFIG(AUDIO_SAMPLE_RATE),
+        .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(
+                        I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_MONO),
+        .gpio_cfg = {
+            .mclk = I2S_GPIO_UNUSED,
+            .bclk = I2S_SPK_BCK,
+            .ws   = I2S_SPK_LRCK,
+            .dout = I2S_SPK_DATA,
+            .din  = I2S_GPIO_UNUSED,
+            .invert_flags = { .mclk_inv = false, .bclk_inv = false, .ws_inv = false },
+        },
+    };
+    ESP_ERROR_CHECK(i2s_channel_init_std_mode(s_tx_chan, &tx_std));
+    ESP_ERROR_CHECK(i2s_channel_enable(s_tx_chan));
+
+    ESP_LOGI(TAG, "Audio initialised — %d Hz, %d-bit", AUDIO_SAMPLE_RATE, AUDIO_BITS);
+    return ESP_OK;
+}
+
+esp_err_t audio_manager_start_capture(audio_capture_cb_t callback)
+{
+    if (s_capturing) return ESP_OK;
+    s_cap_cb    = callback;
+    s_capturing = true;
+    ESP_ERROR_CHECK(i2s_channel_enable(s_rx_chan));
+    xTaskCreatePinnedToCore(capture_task, "audio_cap", 4096, NULL,
+                            configMAX_PRIORITIES - 2, &s_cap_task, 1);
+    return ESP_OK;
+}
+
+esp_err_t audio_manager_stop_capture(void)
+{
+    s_capturing = false;
+    if (s_cap_task) {
+        vTaskDelay(pdMS_TO_TICKS(200));
+        s_cap_task = NULL;
+    }
+    i2s_channel_disable(s_rx_chan);
+    return ESP_OK;
+}
+
+esp_err_t audio_manager_play_pcm(const int16_t *samples, size_t count)
+{
+    if (!s_tx_chan || !samples || count == 0) return ESP_ERR_INVALID_ARG;
+
+    /* Make a mutable copy to apply volume */
+    int16_t *buf = malloc(count * sizeof(int16_t));
+    if (!buf) return ESP_ERR_NO_MEM;
+    memcpy(buf, samples, count * sizeof(int16_t));
+    scale_volume(buf, count);
+
+    size_t written = 0;
+    esp_err_t err = i2s_channel_write(s_tx_chan, buf,
+                                      count * sizeof(int16_t),
+                                      &written, portMAX_DELAY);
+    free(buf);
+    return err;
+}
+
+esp_err_t audio_manager_beep(uint32_t freq_hz, uint32_t duration_ms)
+{
+    size_t samples = (AUDIO_SAMPLE_RATE * duration_ms) / 1000;
+    int16_t *buf = malloc(samples * sizeof(int16_t));
+    if (!buf) return ESP_ERR_NO_MEM;
+
+    for (size_t i = 0; i < samples; i++) {
+        double t = (double)i / AUDIO_SAMPLE_RATE;
+        buf[i] = (int16_t)(8000 * sin(2.0 * M_PI * freq_hz * t));
+    }
+    esp_err_t err = audio_manager_play_pcm(buf, samples);
+    free(buf);
+    return err;
+}
+
+esp_err_t audio_manager_set_volume(uint8_t volume)
+{
+    s_volume = volume > 100 ? 100 : volume;
+    return ESP_OK;
+}
+
+bool audio_manager_vad(const int16_t *samples, size_t count)
+{
+    /* Simple RMS energy threshold — tune THRESHOLD for your environment */
+    const int32_t THRESHOLD = 800;
+    int64_t energy = 0;
+    for (size_t i = 0; i < count; i++)
+        energy += (int64_t)samples[i] * samples[i];
+    int32_t rms = (int32_t)(energy / (int64_t)count);
+    return (rms > THRESHOLD * THRESHOLD);
+}
diff --git a/firmware/main/audio_manager.h b/firmware/main/audio_manager.h
new file mode 100644
index 0000000..e1ef002
--- /dev/null
+++ b/firmware/main/audio_manager.h
@@ -0,0 +1,43 @@
+#pragma once
+#include "esp_err.h"
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+/**
+ * @brief  Initialise I2S microphone and speaker peripherals.
+ */
+esp_err_t audio_manager_init(void);
+
+/**
+ * @brief  Start continuous microphone capture.
+ *         Captured PCM frames are delivered via @p callback.
+ *
+ * @param callback  Called from ISR-safe context with int16_t PCM samples.
+ *                  @p samples points to AUDIO_BUF_MS worth of mono 24 kHz data.
+ *                  The buffer is invalidated after the callback returns.
+ */
+typedef void (*audio_capture_cb_t)(const int16_t *samples, size_t count);
+esp_err_t audio_manager_start_capture(audio_capture_cb_t callback);
+esp_err_t audio_manager_stop_capture(void);
+
+/**
+ * @brief  Play raw PCM data (int16, mono, 24 kHz) through the speaker.
+ *         Blocks until the buffer has been sent to the I2S DMA.
+ */
+esp_err_t audio_manager_play_pcm(const int16_t *samples, size_t count);
+
+/**
+ * @brief  Play a tone (helpful for status sounds).
+ */
+esp_err_t audio_manager_beep(uint32_t freq_hz, uint32_t duration_ms);
+
+/**
+ * @brief  Set speaker volume 0–100.
+ */
+esp_err_t audio_manager_set_volume(uint8_t volume);
+
+/**
+ * @brief  Detect voice activity in a PCM frame (simple energy threshold).
+ */
+bool audio_manager_vad(const int16_t *samples, size_t count);
diff --git a/firmware/main/bluetooth_manager.c b/firmware/main/bluetooth_manager.c
new file mode 100644
index 0000000..efcf091
--- /dev/null
+++ b/firmware/main/bluetooth_manager.c
@@ -0,0 +1,404 @@
+/*
+ * bluetooth_manager.c — Debbie BLE server
+ *
+ * Implements a BLE GATT server with:
+ *   - Nordic UART Service (NUS): wireless config + status notifications
+ *   - Device Information Service (DIS): firmware version, model
+ *   - Battery Service: battery level characteristic
+ *
+ * Phones and tablets can use any "BLE Serial" app (e.g. nRF Toolbox,
+ * Serial Bluetooth Terminal) to connect and send JSON config commands
+ * identical to the HTTP /configure endpoint.
+ *
+ * NOTE: The ESP32-S3 supports BLE only (no Classic Bluetooth / BR-EDR).
+ */
+
+#include "bluetooth_manager.h"
+#include "debbie.h"
+#include "settings.h"
+#include "storage_manager.h"
+#include "wifi_manager.h"
+
+#include "esp_log.h"
+#include "esp_bt.h"
+#include "esp_gap_ble_api.h"
+#include "esp_gatts_api.h"
+#include "esp_bt_main.h"
+#include "esp_gatt_common_api.h"
+#include "nvs_flash.h"
+#include "cJSON.h"
+#include <string.h>
+#include <stdio.h>
+
+static const char *TAG = "ble";
+
+/* ── Nordic UART Service — official 128-bit UUIDs ──────────────────────── */
+/* These are the registered NUS UUIDs. Standard BLE Serial apps (nRF Toolbox,
+ * Serial Bluetooth Terminal, etc.) look for exactly these UUIDs.
+ * UUID bytes are stored in ESP-IDF little-endian order.
+ *
+ * Service:  6E400001-B5A3-F393-E0A9-E50E24DCCA9E
+ * RX(write):6E400002-B5A3-F393-E0A9-E50E24DCCA9E
+ * TX(notify):6E400003-B5A3-F393-E0A9-E50E24DCCA9E
+ */
+static const uint8_t NUS_SVC_UUID128[16] = {
+    0x9E,0xCA,0xDC,0x24,0xE2,0x50,0xA9,0xE0,
+    0x93,0xF3,0xA3,0xB5,0x01,0x00,0x40,0x6E
+};
+static const uint8_t NUS_RX_UUID128[16] = {
+    0x9E,0xCA,0xDC,0x24,0xE2,0x50,0xA9,0xE0,
+    0x93,0xF3,0xA3,0xB5,0x02,0x00,0x40,0x6E
+};
+static const uint8_t NUS_TX_UUID128[16] = {
+    0x9E,0xCA,0xDC,0x24,0xE2,0x50,0xA9,0xE0,
+    0x93,0xF3,0xA3,0xB5,0x03,0x00,0x40,0x6E
+};
+
+/* Device Information Service */
+#define DIS_SERVICE_UUID  0x180A
+#define DIS_MODEL_UUID    0x2A24
+#define DIS_FW_VER_UUID   0x2A26
+#define DIS_MFR_UUID      0x2A29
+
+/* Battery Service */
+#define BAS_SERVICE_UUID  0x180F
+#define BAS_LEVEL_UUID    0x2A19
+
+#define GATTS_APP_ID      0
+#define GATTS_NUM_HANDLE  20
+#define DEBBIE_MTU        512
+
+/* ── State ─────────────────────────────────────────────────────────────── */
+static bool     s_ble_connected  = false;
+static uint16_t s_conn_id        = 0;
+static uint16_t s_gatts_if       = ESP_GATT_IF_NONE;
+static uint16_t s_tx_handle      = 0;
+static uint16_t s_tx_cccd_handle = 0;
+static bool     s_notify_enabled = false;
+
+/* Reassembly buffer for fragmented NUS writes */
+static char  s_rx_buf[512];
+static int   s_rx_len = 0;
+
+/* ── GAP advertising data ──────────────────────────────────────────────── */
+static esp_ble_adv_params_t s_adv_params = {
+    .adv_int_min        = 0x20,
+    .adv_int_max        = 0x40,
+    .adv_type           = ADV_TYPE_IND,
+    .own_addr_type      = BLE_ADDR_TYPE_PUBLIC,
+    .channel_map        = ADV_CHNL_ALL,
+    .adv_filter_policy  = ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY,
+};
+
+/* ── GATT attribute table ─────────────────────────────────────────────── */
+/* We use the simple "add attribute one by one" approach for clarity */
+
+/* ── RX command processor ─────────────────────────────────────────────── */
+static void process_ble_command(const char *json_str)
+{
+    ESP_LOGI(TAG, "BLE RX: %s", json_str);
+
+    cJSON *json = cJSON_Parse(json_str);
+    if (!json) {
+        bluetooth_manager_notify("{\"error\":\"invalid JSON\"}");
+        return;
+    }
+
+#define GET_STR(key, dst) do { \
+    cJSON *j = cJSON_GetObjectItem(json, key); \
+    if (j && cJSON_IsString(j) && strlen(j->valuestring) > 0) \
+        strncpy(dst, j->valuestring, sizeof(dst) - 1); \
+} while (0)
+
+    /* Network credentials */
+    GET_STR("ssid",          g_debbie_config.wifi_ssid);
+    GET_STR("pass",          g_debbie_config.wifi_password);
+    GET_STR("ssid2",         g_debbie_config.wifi_ssid2);
+    GET_STR("pass2",         g_debbie_config.wifi_password2);
+    GET_STR("ssid3",         g_debbie_config.wifi_ssid3);
+    GET_STR("pass3",         g_debbie_config.wifi_password3);
+
+    /* LLM settings */
+    GET_STR("llm_provider",  g_debbie_config.llm_provider);
+    GET_STR("llm_model",     g_debbie_config.llm_model);
+    GET_STR("oai_key",       g_debbie_config.openai_api_key);
+    GET_STR("anthropic_key", g_debbie_config.anthropic_api_key);
+    GET_STR("groq_key",      g_debbie_config.groq_api_key);
+    GET_STR("or_key",        g_debbie_config.openrouter_api_key);
+    GET_STR("local_llm_url", g_debbie_config.local_llm_url);
+    GET_STR("local_llm_model", g_debbie_config.local_llm_model);
+
+    /* Agent */
+    GET_STR("agent_url",     g_debbie_config.agent_ws_url);
+    GET_STR("companion_url", g_debbie_config.companion_url);
+
+    /* Personality */
+    GET_STR("name",          g_debbie_config.debbie_name);
+    GET_STR("sys_prompt",    g_debbie_config.system_prompt);
+    GET_STR("voice_style",   g_debbie_config.voice_style);
+    GET_STR("resp_len",      g_debbie_config.response_length);
+
+    /* Volume */
+    cJSON *vol = cJSON_GetObjectItem(json, "volume");
+    if (vol && cJSON_IsNumber(vol))
+        g_debbie_config.speaker_volume = (uint8_t)vol->valuedouble;
+
+    /* VAD */
+    cJSON *vad = cJSON_GetObjectItem(json, "vad_threshold");
+    if (vad && cJSON_IsNumber(vad))
+        g_debbie_config.vad_threshold = (uint16_t)vad->valuedouble;
+
+    cJSON_Delete(json);
+
+    storage_save_config();
+
+    /* Acknowledge */
+    char ack[128];
+    snprintf(ack, sizeof(ack),
+             "{\"ok\":true,\"wifi\":\"%s\",\"llm\":\"%s/%s\"}",
+             g_debbie_config.wifi_ssid,
+             g_debbie_config.llm_provider,
+             g_debbie_config.llm_model);
+    bluetooth_manager_notify(ack);
+
+    /* Reconnect WiFi with new credentials if SSID changed */
+    if (strlen(g_debbie_config.wifi_ssid) > 0)
+        wifi_manager_reconnect();
+}
+
+/* ── GATTS event handler ──────────────────────────────────────────────── */
+static void gatts_event_handler(esp_gatts_cb_event_t event,
+                                 esp_gatt_if_t gatts_if,
+                                 esp_ble_gatts_cb_param_t *param)
+{
+    switch (event) {
+
+    case ESP_GATTS_REG_EVT:
+        s_gatts_if = gatts_if;
+        ESP_LOGI(TAG, "GATT server registered, app_id=%d", param->reg.app_id);
+
+        /* Set device name */
+        esp_ble_gap_set_device_name(
+            strlen(g_debbie_config.ble_device_name) > 0
+                ? g_debbie_config.ble_device_name
+                : DEBBIE_BLE_DEVICE_NAME);
+
+        /* Advertising data: flags + complete local name */
+        {
+            uint8_t adv_data[] = {
+                0x02, 0x01, 0x06,       /* Flags: LE General Discoverable */
+            };
+            esp_ble_gap_config_adv_data_raw(adv_data, sizeof(adv_data));
+        }
+
+        /* Create Nordic UART Service with official 128-bit UUID */
+        {
+            esp_gatt_srvc_id_t svc = {
+                .is_primary = true,
+                .id = { .inst_id = 0,
+                        .uuid = { .len = ESP_UUID_LEN_128 } }
+            };
+            memcpy(svc.id.uuid.uuid.uuid128, NUS_SVC_UUID128, 16);
+            esp_ble_gatts_create_service(gatts_if, &svc, GATTS_NUM_HANDLE);
+        }
+        break;
+
+    case ESP_GATTS_CREATE_EVT: {
+        uint16_t svc_handle = param->create.service_handle;
+        esp_ble_gatts_start_service(svc_handle);
+
+        /* RX characteristic (write without response) — 128-bit NUS RX UUID */
+        esp_bt_uuid_t rx_uuid = { .len = ESP_UUID_LEN_128 };
+        memcpy(rx_uuid.uuid.uuid128, NUS_RX_UUID128, 16);
+        esp_ble_gatts_add_char(svc_handle, &rx_uuid,
+                               ESP_GATT_PERM_WRITE,
+                               ESP_GATT_CHAR_PROP_BIT_WRITE |
+                               ESP_GATT_CHAR_PROP_BIT_WRITE_NR,
+                               NULL, NULL);
+
+        /* TX characteristic (notify) — 128-bit NUS TX UUID */
+        esp_bt_uuid_t tx_uuid = { .len = ESP_UUID_LEN_128 };
+        memcpy(tx_uuid.uuid.uuid128, NUS_TX_UUID128, 16);
+        esp_ble_gatts_add_char(svc_handle, &tx_uuid,
+                               ESP_GATT_PERM_READ,
+                               ESP_GATT_CHAR_PROP_BIT_NOTIFY,
+                               NULL, NULL);
+        break;
+    }
+
+    case ESP_GATTS_ADD_CHAR_EVT:
+        if (param->add_char.char_uuid.len == ESP_UUID_LEN_128 &&
+            memcmp(param->add_char.char_uuid.uuid.uuid128, NUS_TX_UUID128, 16) == 0) {
+            s_tx_handle = param->add_char.attr_handle;
+            /* Add CCCD (2902) for TX notifications */
+            esp_bt_uuid_t cccd_uuid = { .len = ESP_UUID_LEN_16,
+                                         .uuid.uuid16 = ESP_GATT_UUID_CHAR_CLIENT_CONFIG };
+            esp_ble_gatts_add_char_descr(param->add_char.service_handle,
+                                         &cccd_uuid,
+                                         ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE,
+                                         NULL, NULL);
+        }
+        break;
+
+    case ESP_GATTS_ADD_CHAR_DESCR_EVT:
+        s_tx_cccd_handle = param->add_char_descr.attr_handle;
+        ESP_LOGI(TAG, "NUS TX CCCD handle=%d", s_tx_cccd_handle);
+        /* Start advertising now that the service is fully set up */
+        esp_ble_gap_start_advertising(&s_adv_params);
+        break;
+
+    case ESP_GATTS_CONNECT_EVT:
+        s_ble_connected = true;
+        s_conn_id       = param->connect.conn_id;
+        s_rx_len        = 0;
+        ESP_LOGI(TAG, "BLE client connected, conn_id=%d", s_conn_id);
+        esp_ble_gap_stop_advertising();
+        break;
+
+    case ESP_GATTS_DISCONNECT_EVT:
+        s_ble_connected  = false;
+        s_notify_enabled = false;
+        s_rx_len         = 0;
+        ESP_LOGI(TAG, "BLE client disconnected");
+        esp_ble_gap_start_advertising(&s_adv_params);
+        break;
+
+    case ESP_GATTS_WRITE_EVT: {
+        uint16_t handle = param->write.handle;
+        uint16_t len    = param->write.len;
+        uint8_t *val    = param->write.value;
+
+        if (handle == s_tx_cccd_handle && len == 2) {
+            /* CCCD write — enable/disable notifications */
+            s_notify_enabled = (val[0] == 0x01);
+            ESP_LOGI(TAG, "Notifications %s", s_notify_enabled ? "enabled" : "disabled");
+        } else {
+            /* NUS RX — accumulate and process when newline or buffer full */
+            int avail = (int)sizeof(s_rx_buf) - s_rx_len - 1;
+            int copy  = (len < (uint16_t)avail) ? len : (uint16_t)avail;
+            memcpy(s_rx_buf + s_rx_len, val, copy);
+            s_rx_len += copy;
+            s_rx_buf[s_rx_len] = '\0';
+
+            /* Process if the data ends with '}' (complete JSON object) */
+            if (s_rx_buf[s_rx_len - 1] == '}' || s_rx_len >= (int)sizeof(s_rx_buf) - 1) {
+                process_ble_command(s_rx_buf);
+                s_rx_len = 0;
+            }
+        }
+
+        if (param->write.need_rsp) {
+            esp_ble_gatts_send_response(gatts_if, param->write.conn_id,
+                                        param->write.trans_id, ESP_GATT_OK, NULL);
+        }
+        break;
+    }
+
+    case ESP_GATTS_MTU_EVT:
+        ESP_LOGI(TAG, "MTU negotiated: %d", param->mtu.mtu);
+        break;
+
+    default:
+        break;
+    }
+}
+
+/* ── GAP event handler ────────────────────────────────────────────────── */
+static void gap_event_handler(esp_gap_ble_cb_event_t event,
+                               esp_ble_gap_cb_param_t *param)
+{
+    switch (event) {
+    case ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT:
+        ESP_LOGI(TAG, "ADV data set, starting advertising");
+        break;
+    case ESP_GAP_BLE_ADV_START_COMPLETE_EVT:
+        if (param->adv_start_cmpl.status != ESP_BT_STATUS_SUCCESS)
+            ESP_LOGE(TAG, "Advertising start failed: %d", param->adv_start_cmpl.status);
+        else
+            ESP_LOGI(TAG, "BLE advertising started");
+        break;
+    case ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT:
+        ESP_LOGI(TAG, "BLE advertising stopped");
+        break;
+    default:
+        break;
+    }
+}
+
+/* ── Public API ───────────────────────────────────────────────────────── */
+
+esp_err_t bluetooth_manager_init(void)
+{
+    if (!g_debbie_config.bluetooth_enabled) {
+        ESP_LOGI(TAG, "BLE disabled in config — skipping init");
+        return ESP_FAIL;
+    }
+
+    esp_err_t err;
+
+    /* Release Classic BT memory (ESP32-S3 is BLE-only) */
+    err = esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT);
+    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE)
+        ESP_LOGW(TAG, "mem_release: %s", esp_err_to_name(err));
+
+    esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
+    err = esp_bt_controller_init(&bt_cfg);
+    if (err) { ESP_LOGE(TAG, "bt_controller_init: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_bt_controller_enable(ESP_BT_MODE_BLE);
+    if (err) { ESP_LOGE(TAG, "bt_controller_enable: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_bluedroid_init();
+    if (err) { ESP_LOGE(TAG, "bluedroid_init: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_bluedroid_enable();
+    if (err) { ESP_LOGE(TAG, "bluedroid_enable: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_ble_gatts_register_callback(gatts_event_handler);
+    if (err) { ESP_LOGE(TAG, "gatts_register_callback: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_ble_gap_register_callback(gap_event_handler);
+    if (err) { ESP_LOGE(TAG, "gap_register_callback: %s", esp_err_to_name(err)); return err; }
+
+    err = esp_ble_gatts_app_register(GATTS_APP_ID);
+    if (err) { ESP_LOGE(TAG, "gatts_app_register: %s", esp_err_to_name(err)); return err; }
+
+    esp_ble_gatt_set_local_mtu(DEBBIE_MTU);
+
+    ESP_LOGI(TAG, "BLE manager initialised — advertising as '%s'",
+             strlen(g_debbie_config.ble_device_name) > 0
+                 ? g_debbie_config.ble_device_name
+                 : DEBBIE_BLE_DEVICE_NAME);
+    return ESP_OK;
+}
+
+esp_err_t bluetooth_manager_deinit(void)
+{
+    esp_bluedroid_disable();
+    esp_bluedroid_deinit();
+    esp_bt_controller_disable();
+    esp_bt_controller_deinit();
+    s_ble_connected  = false;
+    s_notify_enabled = false;
+    ESP_LOGI(TAG, "BLE stack stopped");
+    return ESP_OK;
+}
+
+void bluetooth_manager_notify(const char *text)
+{
+    if (!s_ble_connected || !s_notify_enabled || s_tx_handle == 0) return;
+    if (!text || strlen(text) == 0) return;
+
+    size_t len = strlen(text);
+    /* Split into MTU-sized chunks if necessary */
+    size_t chunk = DEBBIE_MTU - 3;
+    for (size_t offset = 0; offset < len; offset += chunk) {
+        size_t this_len = len - offset;
+        if (this_len > chunk) this_len = chunk;
+        esp_ble_gatts_send_indicate(s_gatts_if, s_conn_id, s_tx_handle,
+                                    (uint16_t)this_len,
+                                    (uint8_t *)(text + offset), false);
+    }
+}
+
+bool bluetooth_manager_is_connected(void) { return s_ble_connected; }
diff --git a/firmware/main/bluetooth_manager.h b/firmware/main/bluetooth_manager.h
new file mode 100644
index 0000000..c6c575f
--- /dev/null
+++ b/firmware/main/bluetooth_manager.h
@@ -0,0 +1,36 @@
+#pragma once
+#include "esp_err.h"
+#include <stdbool.h>
+
+/**
+ * @brief  Initialise BLE stack and start the Debbie BLE server.
+ *
+ *  Provides:
+ *  - GAP advertising as "Debbie" (or g_debbie_config.ble_device_name)
+ *  - Nordic UART Service (NUS) for wireless config and data exchange
+ *  - Device Information Service (DIS)
+ *  - Battery Service
+ *
+ *  The NUS RX characteristic accepts JSON commands identical to the HTTP
+ *  /configure endpoint so phones/tablets can configure Debbie over BLE
+ *  without needing to join the WiFi AP.
+ *
+ * @return ESP_OK on success, ESP_FAIL if BLE is disabled in config.
+ */
+esp_err_t bluetooth_manager_init(void);
+
+/**
+ * @brief  Stop BLE advertising and deinitialise the BLE stack.
+ */
+esp_err_t bluetooth_manager_deinit(void);
+
+/**
+ * @brief  Send a UTF-8 notification string to connected BLE client via NUS TX.
+ *         Silently succeeds if no client is connected.
+ */
+void bluetooth_manager_notify(const char *text);
+
+/**
+ * @brief  Return true when a BLE central is connected.
+ */
+bool bluetooth_manager_is_connected(void);
diff --git a/firmware/main/camera_manager.c b/firmware/main/camera_manager.c
new file mode 100644
index 0000000..91a6ece
--- /dev/null
+++ b/firmware/main/camera_manager.c
@@ -0,0 +1,147 @@
+#include "camera_manager.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "esp_camera.h"
+#include "mbedtls/base64.h"
+#include <stdlib.h>
+#include <string.h>
+
+static const char *TAG = "camera";
+static bool        s_initialised = false;
+
+/* -------------------------------------------------------------------------- */
+
+esp_err_t camera_manager_init(void)
+{
+    camera_config_t config = {
+        .pin_pwdn    = CAM_PIN_PWDN,
+        .pin_reset   = CAM_PIN_RESET,
+        .pin_xclk    = CAM_PIN_XCLK,
+        .pin_sccb_sda = CAM_PIN_SIOD,
+        .pin_sccb_scl = CAM_PIN_SIOC,
+        .pin_d7      = CAM_PIN_D7,
+        .pin_d6      = CAM_PIN_D6,
+        .pin_d5      = CAM_PIN_D5,
+        .pin_d4      = CAM_PIN_D4,
+        .pin_d3      = CAM_PIN_D3,
+        .pin_d2      = CAM_PIN_D2,
+        .pin_d1      = CAM_PIN_D1,
+        .pin_d0      = CAM_PIN_D0,
+        .pin_vsync   = CAM_PIN_VSYNC,
+        .pin_href    = CAM_PIN_HREF,
+        .pin_pclk    = CAM_PIN_PCLK,
+
+        .xclk_freq_hz = 20000000,
+        .ledc_timer   = LEDC_TIMER_0,
+        .ledc_channel = LEDC_CHANNEL_0,
+
+        .pixel_format = PIXFORMAT_JPEG,
+        .frame_size   = FRAMESIZE_VGA,   /* 640×480 — balanced quality/size */
+        .jpeg_quality = 12,              /* 0–63, lower = better quality */
+        .fb_count     = 2,
+        .fb_location  = CAMERA_FB_IN_PSRAM,
+        .grab_mode    = CAMERA_GRAB_WHEN_EMPTY,
+    };
+
+    esp_err_t err = esp_camera_init(&config);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Camera init failed: %s", esp_err_to_name(err));
+        return err;
+    }
+
+    /* Optimise sensor settings for indoor / handheld use */
+    sensor_t *s = esp_camera_sensor_get();
+    if (s) {
+        s->set_brightness(s, 0);
+        s->set_contrast(s, 0);
+        s->set_saturation(s, 0);
+        s->set_whitebal(s, 1);
+        s->set_awb_gain(s, 1);
+        s->set_wb_mode(s, 0);        /* auto */
+        s->set_exposure_ctrl(s, 1);
+        s->set_aec2(s, 0);
+        s->set_gain_ctrl(s, 1);
+        s->set_agc_gain(s, 0);
+        s->set_gainceiling(s, GAINCEILING_2X);
+        s->set_bpc(s, 0);
+        s->set_wpc(s, 1);
+        s->set_raw_gma(s, 1);
+        s->set_lenc(s, 1);
+        s->set_hmirror(s, 0);
+        s->set_vflip(s, 0);
+        s->set_dcw(s, 1);
+    }
+
+    s_initialised = true;
+    ESP_LOGI(TAG, "Camera ready (OV2640, VGA JPEG)");
+    return ESP_OK;
+}
+
+esp_err_t camera_manager_capture_jpeg(uint8_t **jpeg_buf, size_t *jpeg_len)
+{
+    if (!s_initialised) return ESP_ERR_INVALID_STATE;
+
+    camera_fb_t *fb = esp_camera_fb_get();
+    if (!fb) {
+        ESP_LOGE(TAG, "Camera capture failed");
+        return ESP_FAIL;
+    }
+
+    *jpeg_buf = malloc(fb->len);
+    if (!*jpeg_buf) {
+        esp_camera_fb_return(fb);
+        return ESP_ERR_NO_MEM;
+    }
+    memcpy(*jpeg_buf, fb->buf, fb->len);
+    *jpeg_len = fb->len;
+    esp_camera_fb_return(fb);
+
+    ESP_LOGD(TAG, "Captured JPEG: %zu bytes", *jpeg_len);
+    return ESP_OK;
+}
+
+void camera_manager_free_frame(uint8_t *buf)
+{
+    free(buf);
+}
+
+esp_err_t camera_manager_capture_base64(char **b64_out, size_t *b64_len)
+{
+    uint8_t *jpeg    = NULL;
+    size_t   jpeg_sz = 0;
+
+    esp_err_t err = camera_manager_capture_jpeg(&jpeg, &jpeg_sz);
+    if (err != ESP_OK) return err;
+
+    /* Calculate required base64 buffer size */
+    size_t b64_sz = 0;
+    mbedtls_base64_encode(NULL, 0, &b64_sz, jpeg, jpeg_sz);
+
+    *b64_out = malloc(b64_sz + 1);
+    if (!*b64_out) {
+        free(jpeg);
+        return ESP_ERR_NO_MEM;
+    }
+
+    err = mbedtls_base64_encode((unsigned char *)*b64_out, b64_sz + 1,
+                                b64_len, jpeg, jpeg_sz);
+    (*b64_out)[*b64_len] = '\0';
+    free(jpeg);
+
+    if (err != 0) {
+        free(*b64_out);
+        *b64_out = NULL;
+        return ESP_FAIL;
+    }
+
+    ESP_LOGD(TAG, "Base64 frame: %zu chars", *b64_len);
+    return ESP_OK;
+}
+
+esp_err_t camera_manager_set_power(bool on)
+{
+#if CAM_PIN_PWDN >= 0
+    gpio_set_level(CAM_PIN_PWDN, on ? 0 : 1);  /* PWDN is active-low */
+#endif
+    return ESP_OK;
+}
diff --git a/firmware/main/camera_manager.h b/firmware/main/camera_manager.h
new file mode 100644
index 0000000..8f7d23b
--- /dev/null
+++ b/firmware/main/camera_manager.h
@@ -0,0 +1,37 @@
+#pragma once
+#include "esp_err.h"
+#include <stdint.h>
+#include <stddef.h>
+
+/**
+ * @brief  Initialise camera hardware.
+ */
+esp_err_t camera_manager_init(void);
+
+/**
+ * @brief  Capture a JPEG snapshot.
+ *         The returned buffer MUST be freed with camera_manager_free_frame().
+ *
+ * @param[out] jpeg_buf  Pointer to JPEG data.
+ * @param[out] jpeg_len  Length of JPEG data in bytes.
+ */
+esp_err_t camera_manager_capture_jpeg(uint8_t **jpeg_buf, size_t *jpeg_len);
+
+/**
+ * @brief  Free a frame previously returned by camera_manager_capture_jpeg().
+ */
+void camera_manager_free_frame(uint8_t *buf);
+
+/**
+ * @brief  Capture a JPEG, encode to base64, and return as a null-terminated
+ *         string.  Caller must free() the returned pointer.
+ *
+ * @param[out] b64_out    Base64 string (malloc'd by this function).
+ * @param[out] b64_len    Length of base64 string (excluding null terminator).
+ */
+esp_err_t camera_manager_capture_base64(char **b64_out, size_t *b64_len);
+
+/**
+ * @brief  Enable or disable camera power (if PWDN pin is wired).
+ */
+esp_err_t camera_manager_set_power(bool on);
diff --git a/firmware/main/debbie.h b/firmware/main/debbie.h
new file mode 100644
index 0000000..4164734
--- /dev/null
+++ b/firmware/main/debbie.h
@@ -0,0 +1,123 @@
+#pragma once
+#include <stdbool.h>
+#include <stdint.h>
+#include "esp_err.h"
+#include "esp_event.h"
+
+/* ── Debbie shared types ─────────────────────────────────────────────────── */
+
+/* Firmware version */
+#define DEBBIE_FW_VERSION  "1.0.0"
+
+typedef enum {
+    DEBBIE_STATE_BOOT = 0,
+    DEBBIE_STATE_SETUP,         /* captive-portal config */
+    DEBBIE_STATE_CONNECTING,    /* joining WiFi */
+    DEBBIE_STATE_IDLE,          /* waiting for user */
+    DEBBIE_STATE_LISTENING,     /* mic active */
+    DEBBIE_STATE_THINKING,      /* request sent, waiting */
+    DEBBIE_STATE_SPEAKING,      /* playing TTS audio */
+    DEBBIE_STATE_CAMERA,        /* camera preview / capture */
+    DEBBIE_STATE_NOTIFICATION,  /* showing incoming notification */
+    DEBBIE_STATE_SPOTIFY,       /* music playback control */
+    DEBBIE_STATE_SCANNING,      /* network security scan in progress */
+    DEBBIE_STATE_ERROR,
+} debbie_state_t;
+
+typedef enum {
+    NOTIF_TYPE_WHATSAPP = 0,
+    NOTIF_TYPE_EMAIL,
+    NOTIF_TYPE_AGENT,
+    NOTIF_TYPE_SPOTIFY,
+    NOTIF_TYPE_SYSTEM,
+} notif_type_t;
+
+typedef struct {
+    notif_type_t type;
+    char         sender[64];
+    char         preview[128];
+    int64_t      timestamp_ms;
+    bool         read;
+} debbie_notification_t;
+
+/* LLM provider identifiers */
+#define LLM_PROVIDER_OPENAI     "openai"
+#define LLM_PROVIDER_OLLAMA     "ollama"
+#define LLM_PROVIDER_ANTHROPIC  "anthropic"
+#define LLM_PROVIDER_GROQ       "groq"
+#define LLM_PROVIDER_OPENROUTER "openrouter"
+
+/* Debbie configuration stored in NVS */
+typedef struct {
+    /* ── Network: WiFi (up to 3 saved networks) ───────────────────────────── */
+    char wifi_ssid[64];
+    char wifi_password[64];
+    char wifi_ssid2[64];
+    char wifi_password2[64];
+    char wifi_ssid3[64];
+    char wifi_password3[64];
+
+    /* ── Network: Bluetooth ────────────────────────────────────────────────── */
+    bool bluetooth_enabled;
+    char ble_device_name[32];    /* advertised BLE name, default = debbie_name */
+
+    /* ── AI: provider & model ─────────────────────────────────────────────── */
+    char llm_provider[32];       /* "openai" | "ollama" | "anthropic" | "groq" | "openrouter" */
+    char llm_model[64];          /* e.g. "gpt-4o", "llama3", "claude-3-5-sonnet-20241022" */
+    char openai_api_key[128];
+    char anthropic_api_key[128];
+    char groq_api_key[128];
+    char openrouter_api_key[128];
+    char local_llm_url[256];     /* Ollama / LM Studio base URL e.g. http://192.168.1.5:11434 */
+    char local_llm_model[64];    /* model name on local server */
+
+    /* ── AI: agent / companion ────────────────────────────────────────────── */
+    char agent_ws_url[256];      /* custom agent WebSocket endpoint */
+    char companion_url[256];     /* companion server base URL */
+    bool use_custom_agent;       /* use agent endpoint instead of direct LLM */
+
+    /* ── Services: Spotify ────────────────────────────────────────────────── */
+    char spotify_token[512];     /* Spotify OAuth token (via companion) */
+
+    /* ── Personality ──────────────────────────────────────────────────────── */
+    char debbie_name[32];        /* customisable name, default "Debbie" */
+    char system_prompt[512];     /* custom persona prompt */
+    char voice_style[16];        /* "friendly" | "professional" | "playful" */
+    char response_length[16];    /* "brief" | "normal" | "detailed" */
+
+    /* ── Audio / UI ───────────────────────────────────────────────────────── */
+    uint8_t speaker_volume;      /* 0–100 */
+    uint16_t vad_threshold;      /* voice activity detection threshold, default 300 */
+    bool camera_enabled;
+
+    /* ── Notifications ────────────────────────────────────────────────────── */
+    bool notifications_enabled;
+    bool notif_whatsapp;
+    bool notif_email;
+    bool notif_spotify;
+
+    /* ── Memory & RAG ─────────────────────────────────────────────────────── */
+    bool    memory_enabled;       /* master on/off for conversation memory */
+    bool    memory_rag_enabled;   /* query companion server for RAG retrieval */
+    uint8_t memory_max_turns;     /* number of recent turns to keep (default 20) */
+} debbie_config_t;
+
+/* Event IDs published on the default event loop */
+/* Custom event base for the Debbie application */
+ESP_EVENT_DECLARE_BASE(DEBBIE_EVENT_BASE);
+
+typedef enum {
+    DEBBIE_EVT_STATE_CHANGE = 0,
+    DEBBIE_EVT_NOTIFICATION,
+    DEBBIE_EVT_WIFI_CONNECTED,
+    DEBBIE_EVT_WIFI_DISCONNECTED,
+    DEBBIE_EVT_AI_CONNECTED,
+    DEBBIE_EVT_AI_DISCONNECTED,
+    DEBBIE_EVT_CAMERA_FRAME,
+    DEBBIE_EVT_BUTTON_PRESS,
+    DEBBIE_EVT_SPOTIFY_UPDATE,
+} debbie_event_id_t;
+
+/* Global state (set by main, read by display/audio/etc.) */
+extern volatile debbie_state_t g_debbie_state;
+extern debbie_config_t         g_debbie_config;
diff --git a/firmware/main/display_manager.c b/firmware/main/display_manager.c
new file mode 100644
index 0000000..f9b1ff5
--- /dev/null
+++ b/firmware/main/display_manager.c
@@ -0,0 +1,592 @@
+/*
+ * display_manager.c — Debbie's LVGL UI
+ *
+ * Layout (3.5" 480×320):
+ *  ┌─────────────────────────────────────────────┐
+ *  │  ◉ WiFi  ◉ AI  ║  Debbie  ║  🔋 85%  🔔 3  │  ← status bar  (32 px)
+ *  ├────────────────────┬────────────────────────┤
+ *  │                    │                        │
+ *  │   Debbie avatar    │   Chat / notification  │
+ *  │    (animated)      │        panel           │
+ *  │                    │                        │
+ *  ├────────────────────┴────────────────────────┤
+ *  │  🎵  Artist — Song title         [▶ || ⏭]  │  ← Spotify bar (36 px)
+ *  └─────────────────────────────────────────────┘
+ *
+ * For the 1.14" (240×135) version the avatar fills the screen with a
+ * simplified overlay.
+ */
+
+#include "display_manager.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "driver/spi_master.h"
+#include "driver/gpio.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "lvgl.h"
+
+/* Conditional include for display driver */
+#if DEBBIE_DISPLAY_35
+#   include "esp_lcd_st7796.h"
+#   define LCD_CMD_BITS   8
+#   define LCD_PARAM_BITS 8
+#else
+#   include "esp_lcd_st7789.h"
+#   define LCD_CMD_BITS   8
+#   define LCD_PARAM_BITS 8
+#endif
+
+#include "esp_lcd_panel_io.h"
+#include "esp_lcd_panel_vendor.h"
+#include "esp_lcd_panel_ops.h"
+#include <string.h>
+#include <stdio.h>
+
+static const char *TAG = "display";
+
+/* ── LVGL globals ─────────────────────────────────────────────────────────── */
+static lv_disp_t            *s_disp     = NULL;
+static SemaphoreHandle_t     s_lvgl_mux = NULL;
+static esp_lcd_panel_handle_t s_panel   = NULL;
+
+/* ── UI widget handles ───────────────────────────────────────────────────── */
+/* Status bar */
+static lv_obj_t *s_status_bar   = NULL;
+static lv_obj_t *s_lbl_name     = NULL;
+static lv_obj_t *s_lbl_wifi     = NULL;
+static lv_obj_t *s_lbl_ai       = NULL;
+static lv_obj_t *s_lbl_battery  = NULL;
+static lv_obj_t *s_lbl_notif    = NULL;
+
+/* Avatar panel */
+static lv_obj_t *s_avatar_cont  = NULL;
+static lv_obj_t *s_face_bg      = NULL;   /* circle */
+static lv_obj_t *s_eye_left     = NULL;
+static lv_obj_t *s_eye_right    = NULL;
+static lv_obj_t *s_mouth        = NULL;
+static lv_obj_t *s_state_lbl    = NULL;
+
+/* Chat / notification panel */
+static lv_obj_t *s_chat_cont    = NULL;
+static lv_obj_t *s_chat_label   = NULL;
+static lv_obj_t *s_notif_cont   = NULL;
+static lv_obj_t *s_notif_label  = NULL;
+
+/* Spotify bar */
+static lv_obj_t *s_spotify_bar  = NULL;
+static lv_obj_t *s_spotify_lbl  = NULL;
+
+/* Camera preview */
+static lv_obj_t *s_cam_canvas   = NULL;
+
+/* ── Colour palette ─────────────────────────────────────────────────────── */
+#define CLR_BG_IDLE         lv_color_hex(0x1A1A2E)   /* deep navy */
+#define CLR_BG_LISTENING    lv_color_hex(0x16213E)   /* darker blue */
+#define CLR_BG_THINKING     lv_color_hex(0x0F3460)   /* mid blue */
+#define CLR_BG_SPEAKING     lv_color_hex(0x533483)   /* purple */
+#define CLR_BG_NOTIF        lv_color_hex(0x2C3E50)   /* slate */
+#define CLR_FACE            lv_color_hex(0xFFD6A5)   /* warm peach */
+#define CLR_EYE_OPEN        lv_color_hex(0x5E548E)   /* violet */
+#define CLR_EYE_CLOSED      lv_color_hex(0x9E8FB2)
+#define CLR_MOUTH           lv_color_hex(0xFF6B6B)   /* coral */
+#define CLR_ACCENT          lv_color_hex(0x06D6A0)   /* teal */
+#define CLR_TEXT_PRIMARY    lv_color_hex(0xEEEEEE)
+#define CLR_TEXT_SECONDARY  lv_color_hex(0xAAAAAA)
+#define CLR_SPOTIFY         lv_color_hex(0x1DB954)   /* Spotify green */
+#define CLR_WHATSAPP        lv_color_hex(0x25D366)
+#define CLR_EMAIL           lv_color_hex(0x4285F4)
+#define CLR_NOTIF_BADGE     lv_color_hex(0xFF4444)
+
+/* ── Eye blink animation ────────────────────────────────────────────────── */
+static lv_anim_t s_blink_anim;
+static int32_t   s_eye_height_px = 24;  /* set from eye object after creation */
+
+static void eye_height_cb(void *obj, int32_t val)
+{
+    lv_obj_set_height(s_eye_left,  val);
+    lv_obj_set_height(s_eye_right, val);
+}
+
+static void start_blink_animation(void)
+{
+    lv_anim_init(&s_blink_anim);
+    lv_anim_set_exec_cb(&s_blink_anim, eye_height_cb);
+    lv_anim_set_var(&s_blink_anim, s_eye_left);
+    lv_anim_set_values(&s_blink_anim, s_eye_height_px, 2);
+    lv_anim_set_time(&s_blink_anim, 120);
+    lv_anim_set_playback_time(&s_blink_anim, 120);
+    lv_anim_set_delay(&s_blink_anim, 4000);
+    lv_anim_set_repeat_count(&s_blink_anim, LV_ANIM_REPEAT_INFINITE);
+    lv_anim_set_repeat_delay(&s_blink_anim, 4500);
+    lv_anim_start(&s_blink_anim);
+}
+
+/* ── LCD flush callback ─────────────────────────────────────────────────── */
+static bool on_color_trans_done(esp_lcd_panel_io_handle_t panel_io,
+                                 esp_lcd_panel_io_event_data_t *edata,
+                                 void *user_ctx)
+{
+    lv_disp_flush_ready(s_disp->driver);
+    return false;
+}
+
+static void lvgl_flush_cb(lv_disp_drv_t *drv, const lv_area_t *area,
+                          lv_color_t *color_map)
+{
+    esp_lcd_panel_draw_bitmap(s_panel,
+                              area->x1, area->y1,
+                              area->x2 + 1, area->y2 + 1,
+                              color_map);
+}
+
+/* ── LVGL tick / task ───────────────────────────────────────────────────── */
+static void lvgl_tick_inc(void *arg)
+{
+    lv_tick_inc(LVGL_TICK_MS);
+}
+
+static void lvgl_task(void *pvParam)
+{
+    while (1) {
+        if (xSemaphoreTake(s_lvgl_mux, portMAX_DELAY)) {
+            lv_task_handler();
+            xSemaphoreGive(s_lvgl_mux);
+        }
+        vTaskDelay(pdMS_TO_TICKS(5));
+    }
+}
+
+/* ── UI construction ────────────────────────────────────────────────────── */
+
+static void build_ui(void)
+{
+    lv_obj_t *screen = lv_scr_act();
+    lv_obj_set_style_bg_color(screen, CLR_BG_IDLE, 0);
+    lv_obj_set_style_bg_opa(screen, LV_OPA_COVER, 0);
+
+    /* ── Status bar ── */
+    s_status_bar = lv_obj_create(screen);
+    lv_obj_set_size(s_status_bar, LCD_WIDTH, 32);
+    lv_obj_align(s_status_bar, LV_ALIGN_TOP_LEFT, 0, 0);
+    lv_obj_set_style_bg_color(s_status_bar, lv_color_hex(0x0D0D1A), 0);
+    lv_obj_set_style_border_width(s_status_bar, 0, 0);
+    lv_obj_set_style_radius(s_status_bar, 0, 0);
+    lv_obj_set_style_pad_all(s_status_bar, 4, 0);
+    lv_obj_clear_flag(s_status_bar, LV_OBJ_FLAG_SCROLLABLE);
+
+    s_lbl_wifi = lv_label_create(s_status_bar);
+    lv_label_set_text(s_lbl_wifi, LV_SYMBOL_WIFI " --");
+    lv_obj_set_style_text_color(s_lbl_wifi, CLR_TEXT_SECONDARY, 0);
+    lv_obj_align(s_lbl_wifi, LV_ALIGN_LEFT_MID, 4, 0);
+
+    s_lbl_ai = lv_label_create(s_status_bar);
+    lv_label_set_text(s_lbl_ai, LV_SYMBOL_AUDIO " --");
+    lv_obj_set_style_text_color(s_lbl_ai, CLR_TEXT_SECONDARY, 0);
+    lv_obj_align_to(s_lbl_ai, s_lbl_wifi, LV_ALIGN_OUT_RIGHT_MID, 8, 0);
+
+    s_lbl_name = lv_label_create(s_status_bar);
+    lv_label_set_text(s_lbl_name, "✨ Debbie");
+    lv_obj_set_style_text_color(s_lbl_name, CLR_ACCENT, 0);
+    lv_obj_align(s_lbl_name, LV_ALIGN_CENTER, 0, 0);
+
+    s_lbl_battery = lv_label_create(s_status_bar);
+    lv_label_set_text(s_lbl_battery, LV_SYMBOL_BATTERY_FULL " --");
+    lv_obj_set_style_text_color(s_lbl_battery, CLR_TEXT_SECONDARY, 0);
+    lv_obj_align(s_lbl_battery, LV_ALIGN_RIGHT_MID, -50, 0);
+
+    s_lbl_notif = lv_label_create(s_status_bar);
+    lv_label_set_text(s_lbl_notif, LV_SYMBOL_BELL);
+    lv_obj_set_style_text_color(s_lbl_notif, CLR_TEXT_SECONDARY, 0);
+    lv_obj_align(s_lbl_notif, LV_ALIGN_RIGHT_MID, -4, 0);
+
+    /* ── Avatar panel (left half below status bar) ── */
+    int avatar_w = LCD_WIDTH / 2;
+    int content_h = LCD_HEIGHT - 32 - 36;  /* minus status + spotify bars */
+
+    s_avatar_cont = lv_obj_create(screen);
+    lv_obj_set_size(s_avatar_cont, avatar_w, content_h);
+    lv_obj_align(s_avatar_cont, LV_ALIGN_TOP_LEFT, 0, 32);
+    lv_obj_set_style_bg_color(s_avatar_cont, CLR_BG_IDLE, 0);
+    lv_obj_set_style_border_width(s_avatar_cont, 0, 0);
+    lv_obj_set_style_radius(s_avatar_cont, 0, 0);
+    lv_obj_clear_flag(s_avatar_cont, LV_OBJ_FLAG_SCROLLABLE);
+
+    /* Face background circle */
+    int face_r = (avatar_w < content_h ? avatar_w : content_h) / 2 - 16;
+    s_face_bg = lv_obj_create(s_avatar_cont);
+    lv_obj_set_size(s_face_bg, face_r * 2, face_r * 2);
+    lv_obj_align(s_face_bg, LV_ALIGN_CENTER, 0, -8);
+    lv_obj_set_style_radius(s_face_bg, LV_RADIUS_CIRCLE, 0);
+    lv_obj_set_style_bg_color(s_face_bg, CLR_FACE, 0);
+    lv_obj_set_style_border_color(s_face_bg, CLR_ACCENT, 0);
+    lv_obj_set_style_border_width(s_face_bg, 3, 0);
+    lv_obj_set_style_shadow_color(s_face_bg, CLR_ACCENT, 0);
+    lv_obj_set_style_shadow_width(s_face_bg, 20, 0);
+    lv_obj_clear_flag(s_face_bg, LV_OBJ_FLAG_SCROLLABLE);
+
+    /* Eyes */
+    int eye_w = face_r / 4;
+    int eye_h = face_r / 3;
+    s_eye_left = lv_obj_create(s_face_bg);
+    lv_obj_set_size(s_eye_left, eye_w, eye_h);
+    lv_obj_align(s_eye_left, LV_ALIGN_CENTER, -(face_r / 3), -(face_r / 6));
+    lv_obj_set_style_radius(s_eye_left, LV_RADIUS_CIRCLE, 0);
+    lv_obj_set_style_bg_color(s_eye_left, CLR_EYE_OPEN, 0);
+    lv_obj_set_style_border_width(s_eye_left, 0, 0);
+
+    s_eye_right = lv_obj_create(s_face_bg);
+    lv_obj_set_size(s_eye_right, eye_w, eye_h);
+    lv_obj_align(s_eye_right, LV_ALIGN_CENTER, (face_r / 3), -(face_r / 6));
+    lv_obj_set_style_radius(s_eye_right, LV_RADIUS_CIRCLE, 0);
+    lv_obj_set_style_bg_color(s_eye_right, CLR_EYE_OPEN, 0);
+    lv_obj_set_style_border_width(s_eye_right, 0, 0);
+
+    /* Mouth (arc approximation with a label for simplicity) */
+    s_mouth = lv_arc_create(s_face_bg);
+    lv_arc_set_angles(s_mouth, 200, 340);  /* lower half arc = smile */
+    lv_arc_set_value(s_mouth, 0);
+    lv_obj_set_size(s_mouth, face_r, face_r / 2);
+    lv_obj_align(s_mouth, LV_ALIGN_CENTER, 0, face_r / 4);
+    lv_obj_set_style_arc_color(s_mouth, CLR_MOUTH, LV_PART_INDICATOR);
+    lv_obj_set_style_arc_color(s_mouth, CLR_MOUTH, LV_PART_MAIN);
+    lv_obj_set_style_arc_width(s_mouth, 4, LV_PART_MAIN);
+    lv_obj_set_style_arc_width(s_mouth, 0, LV_PART_INDICATOR);
+    lv_obj_set_style_bg_opa(s_mouth, LV_OPA_TRANSP, 0);
+    lv_obj_remove_style(s_mouth, NULL, LV_PART_KNOB);
+    lv_obj_clear_flag(s_mouth, LV_OBJ_FLAG_CLICKABLE);
+
+    /* State label below avatar */
+    s_state_lbl = lv_label_create(s_avatar_cont);
+    lv_label_set_text(s_state_lbl, "Hello! 👋");
+    lv_obj_set_style_text_color(s_state_lbl, CLR_ACCENT, 0);
+    lv_obj_align(s_state_lbl, LV_ALIGN_BOTTOM_MID, 0, -4);
+
+    s_eye_height_px = eye_h;
+
+    /* ── Chat / notification panel (right half) ── */
+    s_chat_cont = lv_obj_create(screen);
+    lv_obj_set_size(s_chat_cont, LCD_WIDTH - avatar_w, content_h);
+    lv_obj_align(s_chat_cont, LV_ALIGN_TOP_RIGHT, 0, 32);
+    lv_obj_set_style_bg_color(s_chat_cont, lv_color_hex(0x12122A), 0);
+    lv_obj_set_style_border_width(s_chat_cont, 0, 0);
+    lv_obj_set_style_radius(s_chat_cont, 0, 0);
+    lv_obj_set_style_pad_all(s_chat_cont, 8, 0);
+
+    s_chat_label = lv_label_create(s_chat_cont);
+    lv_label_set_long_mode(s_chat_label, LV_LABEL_LONG_WRAP);
+    lv_obj_set_width(s_chat_label, LCD_WIDTH - avatar_w - 16);
+    lv_label_set_text(s_chat_label,
+        "Hi! I'm Debbie 😊\n"
+        "I can chat, show you what\n"
+        "my camera sees, read your\n"
+        "messages, and control music.\n\n"
+        "Press the centre button\nor just say something!");
+    lv_obj_set_style_text_color(s_chat_label, CLR_TEXT_PRIMARY, 0);
+    lv_obj_align(s_chat_label, LV_ALIGN_TOP_LEFT, 0, 0);
+
+    /* Spotify bar */
+    s_spotify_bar = lv_obj_create(screen);
+    lv_obj_set_size(s_spotify_bar, LCD_WIDTH, 36);
+    lv_obj_align(s_spotify_bar, LV_ALIGN_BOTTOM_LEFT, 0, 0);
+    lv_obj_set_style_bg_color(s_spotify_bar, lv_color_hex(0x121212), 0);
+    lv_obj_set_style_border_width(s_spotify_bar, 0, 0);
+    lv_obj_set_style_radius(s_spotify_bar, 0, 0);
+    lv_obj_set_style_pad_all(s_spotify_bar, 4, 0);
+    lv_obj_clear_flag(s_spotify_bar, LV_OBJ_FLAG_SCROLLABLE);
+
+    s_spotify_lbl = lv_label_create(s_spotify_bar);
+    lv_label_set_text(s_spotify_lbl, LV_SYMBOL_AUDIO "  Not connected to Spotify");
+    lv_obj_set_style_text_color(s_spotify_lbl, lv_color_hex(0x888888), 0);
+    lv_obj_align(s_spotify_lbl, LV_ALIGN_LEFT_MID, 4, 0);
+
+    /* Start blink animation */
+    start_blink_animation();
+
+    ESP_LOGI(TAG, "UI built — LCD %dx%d", LCD_WIDTH, LCD_HEIGHT);
+}
+
+/* ── Public API ──────────────────────────────────────────────────────────── */
+
+esp_err_t display_manager_init(void)
+{
+    s_lvgl_mux = xSemaphoreCreateMutex();
+
+    /* ── SPI bus ── */
+    spi_bus_config_t bus_cfg = {
+        .mosi_io_num   = LCD_PIN_MOSI,
+        .miso_io_num   = -1,
+        .sclk_io_num   = LCD_PIN_CLK,
+        .quadwp_io_num = -1,
+        .quadhd_io_num = -1,
+    };
+    ESP_ERROR_CHECK(spi_bus_initialize(LCD_SPI_HOST, &bus_cfg, SPI_DMA_CH_AUTO));
+
+    /* ── Panel IO ── */
+    esp_lcd_panel_io_handle_t io;
+    esp_lcd_panel_io_spi_config_t io_cfg = {
+        .dc_gpio_num       = LCD_PIN_DC,
+        .cs_gpio_num       = LCD_PIN_CS,
+        .pclk_hz           = LCD_SPI_FREQ_HZ,
+        .lcd_cmd_bits      = LCD_CMD_BITS,
+        .lcd_param_bits    = LCD_PARAM_BITS,
+        .spi_mode          = 0,
+        .trans_queue_depth = 10,
+        .on_color_trans_done = on_color_trans_done,
+    };
+    ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_SPI_HOST,
+                                             &io_cfg, &io));
+
+    /* ── Panel driver ── */
+    esp_lcd_panel_dev_config_t panel_cfg = {
+        .reset_gpio_num = LCD_PIN_RST,
+        .color_space    = ESP_LCD_COLOR_SPACE_BGR,
+        .bits_per_pixel = 16,
+    };
+#if DEBBIE_DISPLAY_35
+    ESP_ERROR_CHECK(esp_lcd_new_panel_st7796(io, &panel_cfg, &s_panel));
+#else
+    ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io, &panel_cfg, &s_panel));
+#endif
+    ESP_ERROR_CHECK(esp_lcd_panel_reset(s_panel));
+    ESP_ERROR_CHECK(esp_lcd_panel_init(s_panel));
+    ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(s_panel, true));
+
+    /* Backlight on */
+    gpio_set_direction(LCD_PIN_BL, GPIO_MODE_OUTPUT);
+    gpio_set_level(LCD_PIN_BL, 1);
+
+    /* ── LVGL ── */
+    lv_init();
+
+    static lv_disp_draw_buf_t draw_buf;
+    static lv_color_t          buf1[LCD_WIDTH * 40];
+    static lv_color_t          buf2[LCD_WIDTH * 40];
+    lv_disp_draw_buf_init(&draw_buf, buf1, buf2, LCD_WIDTH * 40);
+
+    static lv_disp_drv_t disp_drv;
+    lv_disp_drv_init(&disp_drv);
+    disp_drv.hor_res    = LCD_WIDTH;
+    disp_drv.ver_res    = LCD_HEIGHT;
+    disp_drv.flush_cb   = lvgl_flush_cb;
+    disp_drv.draw_buf   = &draw_buf;
+    s_disp = lv_disp_drv_register(&disp_drv);
+
+    /* LVGL tick timer */
+    const esp_timer_create_args_t tick_args = {
+        .callback = lvgl_tick_inc,
+        .name     = "lvgl_tick",
+    };
+    esp_timer_handle_t tick_timer;
+    ESP_ERROR_CHECK(esp_timer_create(&tick_args, &tick_timer));
+    ESP_ERROR_CHECK(esp_timer_start_periodic(tick_timer,
+                    LVGL_TICK_MS * 1000 /* µs */));
+
+    /* Build the initial UI */
+    if (xSemaphoreTake(s_lvgl_mux, portMAX_DELAY)) {
+        build_ui();
+        xSemaphoreGive(s_lvgl_mux);
+    }
+
+    /* LVGL task */
+    xTaskCreatePinnedToCore(lvgl_task, "lvgl", 8192, NULL,
+                            configMAX_PRIORITIES - 1, NULL, 1);
+
+    ESP_LOGI(TAG, "Display ready — %s %dx%d", LCD_DRIVER, LCD_WIDTH, LCD_HEIGHT);
+    return ESP_OK;
+}
+
+/* ── State → face expression mapping ────────────────────────────────────── */
+
+static void set_face_for_state(debbie_state_t state)
+{
+    if (!s_face_bg) return;
+    lv_color_t bg;
+    const char *status_text;
+    lv_coord_t mouth_start, mouth_end;
+
+    switch (state) {
+    case DEBBIE_STATE_LISTENING:
+        bg          = CLR_BG_LISTENING;
+        status_text = "Listening... 👂";
+        mouth_start = 200; mouth_end = 340;  /* big smile */
+        /* Animate eyes — wider when listening */
+        lv_obj_set_height(s_eye_left,  s_eye_height_px + 4);
+        lv_obj_set_height(s_eye_right, s_eye_height_px + 4);
+        break;
+    case DEBBIE_STATE_THINKING:
+        bg          = CLR_BG_THINKING;
+        status_text = "Thinking... 🤔";
+        mouth_start = 220; mouth_end = 320;  /* neutral */
+        lv_obj_set_height(s_eye_left,  s_eye_height_px / 2);
+        lv_obj_set_height(s_eye_right, s_eye_height_px / 2);
+        break;
+    case DEBBIE_STATE_SPEAKING:
+        bg          = CLR_BG_SPEAKING;
+        status_text = "Speaking 🗣️";
+        mouth_start = 180; mouth_end = 360;  /* open mouth */
+        lv_obj_set_height(s_eye_left,  s_eye_height_px);
+        lv_obj_set_height(s_eye_right, s_eye_height_px);
+        break;
+    case DEBBIE_STATE_NOTIFICATION:
+        bg          = CLR_BG_NOTIF;
+        status_text = "Notification! 🔔";
+        mouth_start = 200; mouth_end = 340;
+        break;
+    case DEBBIE_STATE_CAMERA:
+        bg          = CLR_BG_IDLE;
+        status_text = "Camera 📷";
+        mouth_start = 200; mouth_end = 340;
+        break;
+    case DEBBIE_STATE_SPOTIFY:
+        bg          = CLR_BG_IDLE;
+        status_text = "Music 🎵";
+        mouth_start = 200; mouth_end = 340;
+        break;
+    case DEBBIE_STATE_SETUP:
+        bg          = lv_color_hex(0x2D3436);
+        status_text = "Setup mode ⚙️";
+        mouth_start = 210; mouth_end = 330;
+        break;
+    case DEBBIE_STATE_CONNECTING:
+        bg          = lv_color_hex(0x2D3436);
+        status_text = "Connecting... 🔗";
+        mouth_start = 210; mouth_end = 330;
+        break;
+    case DEBBIE_STATE_ERROR:
+        bg          = lv_color_hex(0x5C1E1E);
+        status_text = "Oops! 😅";
+        mouth_start = 200; mouth_end = 340;
+        break;
+    case DEBBIE_STATE_IDLE:
+    default:
+        bg          = CLR_BG_IDLE;
+        status_text = "Ready! 😊";
+        mouth_start = 200; mouth_end = 340;
+        lv_obj_set_height(s_eye_left,  s_eye_height_px);
+        lv_obj_set_height(s_eye_right, s_eye_height_px);
+        break;
+    }
+
+    lv_obj_set_style_bg_color(lv_scr_act(), bg, 0);
+    lv_obj_set_style_bg_color(s_avatar_cont, bg, 0);
+    lv_arc_set_angles(s_mouth, mouth_start, mouth_end);
+    lv_label_set_text(s_state_lbl, status_text);
+}
+
+void display_manager_set_state(debbie_state_t state)
+{
+    if (!s_lvgl_mux) return;
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        set_face_for_state(state);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_show_notification(const debbie_notification_t *notif)
+{
+    if (!notif || !s_chat_label) return;
+    const char *icon;
+    switch (notif->type) {
+    case NOTIF_TYPE_WHATSAPP: icon = "💬"; break;
+    case NOTIF_TYPE_EMAIL:    icon = "📧"; break;
+    case NOTIF_TYPE_SPOTIFY:  icon = "🎵"; break;
+    default:                  icon = "🔔"; break;
+    }
+    char buf[220];
+    snprintf(buf, sizeof(buf), "%s %s\n%s", icon, notif->sender, notif->preview);
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_chat_label, buf);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_show_text(const char *text)
+{
+    if (!text || !s_chat_label) return;
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_chat_label, text);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_show_camera_frame(const uint8_t *rgb565)
+{
+    /* For simplicity we reuse the chat panel area for the camera preview.
+     * A full implementation would use lv_canvas with a dedicated buffer. */
+    if (!s_chat_label) return;
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        if (rgb565 == NULL) {
+            lv_label_set_text(s_chat_label, "");
+        } else {
+            lv_label_set_text(s_chat_label, "📷 Camera preview");
+            /* TODO: Render rgb565 into lv_canvas for full preview */
+        }
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_set_notif_count(int count)
+{
+    if (!s_lbl_notif) return;
+    char buf[16];
+    if (count > 0) {
+        snprintf(buf, sizeof(buf), LV_SYMBOL_BELL " %d", count);
+        lv_obj_set_style_text_color(s_lbl_notif, CLR_NOTIF_BADGE, 0);
+    } else {
+        snprintf(buf, sizeof(buf), LV_SYMBOL_BELL);
+        lv_obj_set_style_text_color(s_lbl_notif, CLR_TEXT_SECONDARY, 0);
+    }
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_lbl_notif, buf);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_set_spotify_track(const char *artist, const char *title,
+                                       bool is_playing)
+{
+    if (!s_spotify_lbl) return;
+    char buf[128];
+    snprintf(buf, sizeof(buf), "%s %s — %s",
+             is_playing ? "▶" : "⏸", artist ? artist : "", title ? title : "");
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_spotify_lbl, buf);
+        lv_obj_set_style_text_color(s_spotify_lbl, CLR_SPOTIFY, 0);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_set_battery(uint8_t percent)
+{
+    if (!s_lbl_battery) return;
+    const char *icon;
+    if      (percent > 80) icon = LV_SYMBOL_BATTERY_FULL;
+    else if (percent > 60) icon = LV_SYMBOL_BATTERY_3;
+    else if (percent > 40) icon = LV_SYMBOL_BATTERY_2;
+    else if (percent > 15) icon = LV_SYMBOL_BATTERY_1;
+    else                   icon = LV_SYMBOL_BATTERY_EMPTY;
+    char buf[16];
+    snprintf(buf, sizeof(buf), "%s %d%%", icon, percent);
+    lv_color_t col = percent > 20 ? CLR_TEXT_SECONDARY : lv_color_hex(0xFF4444);
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_lbl_battery, buf);
+        lv_obj_set_style_text_color(s_lbl_battery, col, 0);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
+
+void display_manager_set_connection_status(bool wifi_ok, bool ai_ok)
+{
+    if (!s_lbl_wifi || !s_lbl_ai) return;
+    if (xSemaphoreTake(s_lvgl_mux, pdMS_TO_TICKS(50))) {
+        lv_label_set_text(s_lbl_wifi, wifi_ok ? LV_SYMBOL_WIFI " OK" : LV_SYMBOL_WIFI " --");
+        lv_obj_set_style_text_color(s_lbl_wifi,
+            wifi_ok ? CLR_ACCENT : CLR_TEXT_SECONDARY, 0);
+        lv_label_set_text(s_lbl_ai, ai_ok ? LV_SYMBOL_AUDIO " AI" : LV_SYMBOL_AUDIO " --");
+        lv_obj_set_style_text_color(s_lbl_ai,
+            ai_ok ? CLR_ACCENT : CLR_TEXT_SECONDARY, 0);
+        xSemaphoreGive(s_lvgl_mux);
+    }
+}
diff --git a/firmware/main/display_manager.h b/firmware/main/display_manager.h
new file mode 100644
index 0000000..3a2e778
--- /dev/null
+++ b/firmware/main/display_manager.h
@@ -0,0 +1,53 @@
+#pragma once
+#include "esp_err.h"
+#include "debbie.h"
+#include <stdbool.h>
+
+/**
+ * @brief  Initialise the SPI LCD and LVGL graphics stack.
+ *         Creates the LVGL timer task and renders the Debbie avatar UI.
+ */
+esp_err_t display_manager_init(void);
+
+/**
+ * @brief  Update the UI to reflect the new application state.
+ *         Safe to call from any task — posts to the LVGL task internally.
+ */
+void display_manager_set_state(debbie_state_t state);
+
+/**
+ * @brief  Show a notification badge and brief overlay.
+ */
+void display_manager_show_notification(const debbie_notification_t *notif);
+
+/**
+ * @brief  Show a text bubble (AI transcript / message).
+ */
+void display_manager_show_text(const char *text);
+
+/**
+ * @brief  Show a camera preview frame (RGB565, LCD_WIDTH × LCD_HEIGHT).
+ *         Pass NULL to hide the preview.
+ */
+void display_manager_show_camera_frame(const uint8_t *rgb565);
+
+/**
+ * @brief  Update the unread notification count badge.
+ */
+void display_manager_set_notif_count(int count);
+
+/**
+ * @brief  Update the Spotify "now playing" info on screen.
+ */
+void display_manager_set_spotify_track(const char *artist, const char *title,
+                                       bool is_playing);
+
+/**
+ * @brief  Update battery percentage shown in status bar.
+ */
+void display_manager_set_battery(uint8_t percent);
+
+/**
+ * @brief  Update WiFi / AI connection icons in status bar.
+ */
+void display_manager_set_connection_status(bool wifi_ok, bool ai_ok);
diff --git a/firmware/main/idf_component.yml b/firmware/main/idf_component.yml
new file mode 100644
index 0000000..417fce8
--- /dev/null
+++ b/firmware/main/idf_component.yml
@@ -0,0 +1,32 @@
+## IDF Component Manager manifest
+## https://docs.espressif.com/projects/idf-component-manager/
+
+dependencies:
+  idf: ">=5.2.0"
+
+  ## WebSocket client (for OpenAI Realtime API + companion server)
+  espressif/esp_websocket_client:
+    version: ">=1.1.0"
+
+  ## LVGL v8 display library
+  lvgl/lvgl:
+    version: "~8.3.0"
+
+  ## LCD panel drivers (ST7789 / ST7796)
+  espressif/esp_lcd_st7789:
+    version: ">=1.0.0"
+
+  espressif/esp_lcd_st7796:
+    version: ">=1.0.0"
+
+  ## ESP camera component
+  espressif/esp_camera:
+    version: ">=2.0.0"
+
+  ## JSON library
+  espressif/cjson:
+    version: ">=1.7.14"
+
+  ## HTTP client
+  idf_component_manager/idf_component_manager:
+    version: ">=2.0.0"
diff --git a/firmware/main/main.c b/firmware/main/main.c
new file mode 100644
index 0000000..7e84069
--- /dev/null
+++ b/firmware/main/main.c
@@ -0,0 +1,601 @@
+/*
+ * main.c — Debbie: Portable Personal AI Friend
+ *
+ * Freenove Media Kit ESP32-S3 (FNK0102)
+ *
+ * Features:
+ *  ✅ Voice conversations via OpenAI Realtime API (gpt-4o-realtime-preview)
+ *  ✅ Camera vision — capture and describe images using gpt-4o
+ *  ✅ WhatsApp / Email / agent notification pager
+ *  ✅ Spotify & Audible playback control
+ *  ✅ Friendly LVGL avatar UI with animated expressions
+ *  ✅ WiFi captive-portal setup
+ *  ✅ Custom agent endpoint support (ws:// or wss://)
+ *  ✅ Battery monitoring
+ *  ✅ OTA-ready partition layout
+ */
+
+#include "debbie.h"
+#include "settings.h"
+#include "storage_manager.h"
+#include "wifi_manager.h"
+#include "bluetooth_manager.h"
+#include "audio_manager.h"
+#include "camera_manager.h"
+#include "display_manager.h"
+#include "openai_client.h"
+#include "notification_client.h"
+#include "web_server.h"
+#include "network_scanner.h"
+#include "vuln_reporter.h"
+#include "self_agent.h"
+#include "memory_manager.h"
+
+#include "esp_log.h"
+#include "esp_timer.h"
+#include "cJSON.h"
+#include "esp_system.h"
+#include "driver/gpio.h"
+#include "driver/adc.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/queue.h"
+#include "freertos/event_groups.h"
+
+static const char *TAG = "debbie";
+
+/* ── Global state (declared in debbie.h) ─────────────────────────────────── */
+volatile debbie_state_t g_debbie_state = DEBBIE_STATE_BOOT;
+debbie_config_t         g_debbie_config = { 0 };
+ESP_EVENT_DEFINE_BASE(DEBBIE_EVENT_BASE);
+
+/* ── Event queue for button / async events ─────────────────────────────── */
+typedef enum {
+    BTN_EVT_CENTER = 0,
+    BTN_EVT_UP,
+    BTN_EVT_DOWN,
+    BTN_EVT_LONG_PRESS,
+} btn_event_t;
+
+static QueueHandle_t s_btn_queue = NULL;
+
+/* ── Voice activity detection state ─────────────────────────────────────── */
+static bool     s_user_speaking     = false;
+static uint32_t s_silence_ms        = 0;
+static uint32_t s_vad_start_ms      = 0;
+#define VAD_SILENCE_TIMEOUT_MS  1200   /* stop after 1.2 s of silence */
+#define VAD_MIN_SPEECH_MS        200   /* ignore very short bursts */
+
+/* ── Pending notification ─────────────────────────────────────────────────  */
+static debbie_notification_t s_pending_notif = { 0 };
+static bool                  s_has_notif     = false;
+
+/* -------------------------------------------------------------------------- */
+
+static void set_state(debbie_state_t new_state)
+{
+    g_debbie_state = new_state;
+    display_manager_set_state(new_state);
+    esp_event_post(DEBBIE_EVENT_BASE, DEBBIE_EVT_STATE_CHANGE,
+                   &new_state, sizeof(new_state), 0);
+}
+
+/* ── OpenAI event callback ───────────────────────────────────────────────── */
+
+static void on_oai_event(const oai_event_data_t *evt, void *ctx)
+{
+    switch (evt->type) {
+    case OAI_EVT_CONNECTED:
+        ESP_LOGI(TAG, "Connected to OpenAI Realtime API");
+        display_manager_set_connection_status(true, true);
+        set_state(DEBBIE_STATE_IDLE);
+        audio_manager_beep(880, 120);
+        vTaskDelay(pdMS_TO_TICKS(80));
+        audio_manager_beep(1100, 120);
+        break;
+
+    case OAI_EVT_DISCONNECTED:
+        ESP_LOGW(TAG, "Disconnected from OpenAI");
+        display_manager_set_connection_status(true, false);
+        set_state(DEBBIE_STATE_IDLE);
+        break;
+
+    case OAI_EVT_SESSION_CREATED:
+        ESP_LOGI(TAG, "Session ready");
+        break;
+
+    case OAI_EVT_AUDIO_DELTA:
+        /* Play audio immediately as it streams */
+        set_state(DEBBIE_STATE_SPEAKING);
+        audio_manager_play_pcm(evt->audio.pcm, evt->audio.count);
+        break;
+
+    case OAI_EVT_TRANSCRIPT:
+        ESP_LOGI(TAG, "Transcript: %s", evt->transcript.text);
+        display_manager_show_text(evt->transcript.text);
+        /* Record AI turn in memory */
+        memory_manager_add_turn("assistant", evt->transcript.text);
+        memory_manager_sync_turn("assistant", evt->transcript.text);
+        break;
+
+    case OAI_EVT_USER_TRANSCRIPT:
+        ESP_LOGI(TAG, "User said: %s", evt->transcript.text);
+        /* Record user turn in memory */
+        memory_manager_add_turn("user", evt->transcript.text);
+        memory_manager_sync_turn("user", evt->transcript.text);
+        break;
+
+    case OAI_EVT_FUNCTION_CALL:
+        ESP_LOGI(TAG, "Function call: %s(%s)", evt->fn.name, evt->fn.args_json);
+
+        /* ── Camera ── */
+        if (strcmp(evt->fn.name, "capture_image") == 0) {
+            set_state(DEBBIE_STATE_CAMERA);
+            char *b64 = NULL;
+            size_t b64_len = 0;
+            if (camera_manager_capture_base64(&b64, &b64_len) == ESP_OK && b64) {
+                display_manager_show_text("📷 Captured! Analysing...");
+                openai_client_send_image(b64,
+                    "Please describe in detail what you see in this image, "
+                    "including objects, people, text, colours, and anything notable.");
+                free(b64);
+                openai_client_send_function_result(evt->fn.call_id,
+                    "{\"status\":\"ok\",\"message\":\"Image captured and sent for analysis\"}");
+            } else {
+                openai_client_send_function_result(evt->fn.call_id,
+                    "{\"status\":\"error\",\"message\":\"Camera capture failed\"}");
+            }
+            set_state(DEBBIE_STATE_THINKING);
+
+        /* ── Notifications ── */
+        } else if (strcmp(evt->fn.name, "read_notifications") == 0) {
+            char *summary = notification_client_get_summary_json();
+            if (summary) {
+                char result[512];
+                snprintf(result, sizeof(result),
+                         "{\"notifications\":%s}", summary);
+                openai_client_send_function_result(evt->fn.call_id, result);
+                free(summary);
+                notification_client_clear();
+                display_manager_set_notif_count(0);
+            } else {
+                openai_client_send_function_result(evt->fn.call_id,
+                    "{\"notifications\":[],\"message\":\"No pending notifications\"}");
+            }
+
+        /* ── Spotify ── */
+        } else if (strcmp(evt->fn.name, "spotify_control") == 0) {
+            cJSON *args = cJSON_Parse(evt->fn.args_json);
+            cJSON *act  = args ? cJSON_GetObjectItem(args, "action") : NULL;
+            if (act && cJSON_IsString(act)) {
+                notification_client_spotify_command(act->valuestring);
+                char result[128];
+                snprintf(result, sizeof(result),
+                         "{\"status\":\"ok\",\"action\":\"%s\"}", act->valuestring);
+                openai_client_send_function_result(evt->fn.call_id, result);
+                set_state(DEBBIE_STATE_SPOTIFY);
+            } else {
+                openai_client_send_function_result(evt->fn.call_id,
+                    "{\"error\":\"action parameter required\"}");
+            }
+            if (args) cJSON_Delete(args);
+
+        /* ── Network security & self-agent (all other tools) ── */
+        } else if (strcmp(evt->fn.name, "save_memory") == 0) {
+            /* AI can explicitly save a fact to long-term memory */
+            cJSON *args = cJSON_Parse(evt->fn.args_json);
+            cJSON *key  = args ? cJSON_GetObjectItem(args, "key")   : NULL;
+            cJSON *val  = args ? cJSON_GetObjectItem(args, "value") : NULL;
+            cJSON *imp  = args ? cJSON_GetObjectItem(args, "importance") : NULL;
+            if (key && val && cJSON_IsString(key) && cJSON_IsString(val)) {
+                uint8_t importance = imp ? (uint8_t)imp->valuedouble : 7;
+                memory_manager_save_fact(key->valuestring,
+                                         val->valuestring,
+                                         importance);
+                char result[256];
+                snprintf(result, sizeof(result),
+                         "{\"status\":\"ok\",\"key\":\"%s\",\"value\":\"%s\"}",
+                         key->valuestring, val->valuestring);
+                openai_client_send_function_result(evt->fn.call_id, result);
+            } else {
+                openai_client_send_function_result(evt->fn.call_id,
+                    "{\"error\":\"key and value are required\"}");
+            }
+            if (args) cJSON_Delete(args);
+
+        } else {
+            /* Defer to the self_agent dispatcher for:
+             * network_scan, get_vuln_report, system_info,
+             * web_fetch, dns_lookup, cve_lookup */
+            if (!self_agent_handle_function_call(evt->fn.name,
+                                                 evt->fn.args_json,
+                                                 evt->fn.call_id)) {
+                ESP_LOGW(TAG, "Unknown function: %s", evt->fn.name);
+                char result[128];
+                snprintf(result, sizeof(result),
+                         "{\"error\":\"Unknown function: %s\"}", evt->fn.name);
+                openai_client_send_function_result(evt->fn.call_id, result);
+            }
+        }
+
+        /* Return to thinking/idle after handling */
+        if (g_debbie_state != DEBBIE_STATE_SPEAKING)
+            set_state(DEBBIE_STATE_THINKING);
+        break;
+
+    case OAI_EVT_ERROR:
+        ESP_LOGE(TAG, "OpenAI error: %s", evt->error.message);
+        display_manager_show_text("😅 Something went wrong.\nPlease try again.");
+        set_state(DEBBIE_STATE_ERROR);
+        vTaskDelay(pdMS_TO_TICKS(2000));
+        set_state(DEBBIE_STATE_IDLE);
+        break;
+
+    default:
+        break;
+    }
+}
+
+/* ── Notification callback ───────────────────────────────────────────────── */
+
+static void on_notification(const debbie_notification_t *notif, void *ctx)
+{
+    s_pending_notif = *notif;
+    s_has_notif     = true;
+
+    int count = notification_client_unread_count();
+    display_manager_set_notif_count(count);
+    display_manager_show_notification(notif);
+    set_state(DEBBIE_STATE_NOTIFICATION);
+
+    /* Gentle beep for notifications */
+    audio_manager_beep(660, 80);
+
+    /* Tell the AI about it if connected */
+    if (openai_client_is_connected()) {
+        char msg[256];
+        const char *type_str;
+        switch (notif->type) {
+        case NOTIF_TYPE_WHATSAPP: type_str = "WhatsApp"; break;
+        case NOTIF_TYPE_EMAIL:    type_str = "email";    break;
+        case NOTIF_TYPE_AGENT:    type_str = "agent";    break;
+        default:                  type_str = "notification"; break;
+        }
+        snprintf(msg, sizeof(msg),
+                 "[System: New %s from %s: \"%s\". "
+                 "Please let the user know briefly.]",
+                 type_str, notif->sender, notif->preview);
+        openai_client_send_text(msg);
+    }
+
+    vTaskDelay(pdMS_TO_TICKS(3000));
+    set_state(DEBBIE_STATE_IDLE);
+}
+
+/* ── Microphone / VAD callback ───────────────────────────────────────────── */
+
+static void on_audio_capture(const int16_t *samples, size_t count)
+{
+    if (g_debbie_state != DEBBIE_STATE_LISTENING &&
+        g_debbie_state != DEBBIE_STATE_IDLE) {
+        return;
+    }
+
+    bool voice = audio_manager_vad(samples, count);
+
+    if (voice) {
+        s_silence_ms = 0;
+        if (!s_user_speaking) {
+            s_user_speaking = true;
+            s_vad_start_ms  = (uint32_t)(esp_timer_get_time() / 1000);
+            set_state(DEBBIE_STATE_LISTENING);
+        }
+        /* Stream audio to OpenAI */
+        if (openai_client_is_connected())
+            openai_client_send_audio(samples, count);
+
+    } else if (s_user_speaking) {
+        s_silence_ms += AUDIO_BUF_MS;
+        if (s_silence_ms >= VAD_SILENCE_TIMEOUT_MS) {
+            uint32_t now_ms    = (uint32_t)(esp_timer_get_time() / 1000);
+            uint32_t speech_ms = now_ms - s_vad_start_ms;
+            s_user_speaking = false;
+            s_silence_ms    = 0;
+
+            if (speech_ms >= VAD_MIN_SPEECH_MS && openai_client_is_connected()) {
+                set_state(DEBBIE_STATE_THINKING);
+                openai_client_commit_audio();
+            } else {
+                set_state(DEBBIE_STATE_IDLE);
+            }
+        }
+    }
+}
+
+/* ── Button ISR / debounce task ──────────────────────────────────────────── */
+
+static void IRAM_ATTR gpio_isr_handler(void *arg)
+{
+    btn_event_t evt = (btn_event_t)(uintptr_t)arg;
+    xQueueSendFromISR(s_btn_queue, &evt, NULL);
+}
+
+static void button_task(void *pvParam)
+{
+    btn_event_t evt;
+    while (1) {
+        if (xQueueReceive(s_btn_queue, &evt, portMAX_DELAY)) {
+            vTaskDelay(pdMS_TO_TICKS(50));  /* debounce */
+
+            switch (evt) {
+            case BTN_EVT_CENTER:
+                /* Centre button: capture image or toggle listening */
+                if (g_debbie_state == DEBBIE_STATE_IDLE ||
+                    g_debbie_state == DEBBIE_STATE_LISTENING) {
+                    set_state(DEBBIE_STATE_CAMERA);
+                    char *b64 = NULL;
+                    size_t b64_len = 0;
+                    if (camera_manager_capture_base64(&b64, &b64_len) == ESP_OK && b64) {
+                        display_manager_show_text("📷 What do you see, Debbie?");
+                        openai_client_send_image(b64,
+                            "What can you see in this photo? Describe it naturally.");
+                        free(b64);
+                        set_state(DEBBIE_STATE_THINKING);
+                    } else {
+                        set_state(DEBBIE_STATE_IDLE);
+                    }
+                }
+                break;
+
+            case BTN_EVT_UP:
+                /* Volume up */
+                if (g_debbie_config.speaker_volume < 100)
+                    g_debbie_config.speaker_volume += 10;
+                audio_manager_set_volume(g_debbie_config.speaker_volume);
+                {
+                    char msg[32];
+                    snprintf(msg, sizeof(msg), "🔊 Volume: %d%%",
+                             g_debbie_config.speaker_volume);
+                    display_manager_show_text(msg);
+                }
+                break;
+
+            case BTN_EVT_DOWN:
+                /* Volume down */
+                if (g_debbie_config.speaker_volume > 0)
+                    g_debbie_config.speaker_volume -= 10;
+                audio_manager_set_volume(g_debbie_config.speaker_volume);
+                {
+                    char msg[32];
+                    snprintf(msg, sizeof(msg), "🔉 Volume: %d%%",
+                             g_debbie_config.speaker_volume);
+                    display_manager_show_text(msg);
+                }
+                break;
+
+            case BTN_EVT_LONG_PRESS:
+                /* Long press: read notifications aloud */
+                if (openai_client_is_connected()) {
+                    char *summary = notification_client_get_summary_json();
+                    if (summary) {
+                        char text[512];
+                        snprintf(text, sizeof(text),
+                            "[System: Please read out the following notifications "
+                            "to the user: %s]", summary);
+                        openai_client_send_text(text);
+                        free(summary);
+                        notification_client_clear();
+                        display_manager_set_notif_count(0);
+                    } else {
+                        openai_client_send_text("Are there any notifications for me?");
+                    }
+                }
+                break;
+            }
+        }
+    }
+}
+
+/* ── Battery monitoring task ─────────────────────────────────────────────── */
+
+static void battery_task(void *pvParam)
+{
+    adc1_config_width(ADC_WIDTH_BIT_12);
+    adc1_config_channel_atten(ADC1_CHANNEL_3, ADC_ATTEN_DB_11);
+
+    while (1) {
+        int raw   = adc1_get_raw(ADC1_CHANNEL_3);
+        float v   = (raw / 4095.0f) * 3.3f * BAT_DIVIDER_RATIO;
+        /* Approximate Li-Ion percentage: 4.2 V = 100%, 3.2 V = 0% */
+        int percent = (int)((v - 3.2f) / (4.2f - 3.2f) * 100.0f);
+        if (percent > 100) percent = 100;
+        if (percent < 0)   percent = 0;
+        display_manager_set_battery((uint8_t)percent);
+        vTaskDelay(pdMS_TO_TICKS(30000));  /* check every 30 s */
+    }
+}
+
+/* ── GPIO setup ──────────────────────────────────────────────────────────── */
+
+static void gpio_init(void)
+{
+    s_btn_queue = xQueueCreate(8, sizeof(btn_event_t));
+
+    gpio_config_t io_cfg = {
+        .mode         = GPIO_MODE_INPUT,
+        .pull_up_en   = GPIO_PULLUP_ENABLE,
+        .pull_down_en = GPIO_PULLDOWN_DISABLE,
+        .intr_type    = GPIO_INTR_NEGEDGE,
+    };
+
+    io_cfg.pin_bit_mask = (1ULL << NAV_CENTER);
+    gpio_config(&io_cfg);
+    io_cfg.pin_bit_mask = (1ULL << NAV_UP);
+    gpio_config(&io_cfg);
+    io_cfg.pin_bit_mask = (1ULL << NAV_DOWN);
+    gpio_config(&io_cfg);
+
+    gpio_install_isr_service(0);
+    gpio_isr_handler_add(NAV_CENTER, gpio_isr_handler, (void *)BTN_EVT_CENTER);
+    gpio_isr_handler_add(NAV_UP,     gpio_isr_handler, (void *)BTN_EVT_UP);
+    gpio_isr_handler_add(NAV_DOWN,   gpio_isr_handler, (void *)BTN_EVT_DOWN);
+
+    xTaskCreate(button_task, "btn", 4096, NULL, 5, NULL);
+}
+
+/* ── Boot splash ─────────────────────────────────────────────────────────── */
+
+static void show_boot_splash(void)
+{
+    display_manager_show_text(
+        "✨ Debbie starting up...\n\n"
+        "Please wait while I connect\n"
+        "to WiFi and the AI...\n\n"
+        "This takes about 10 seconds.");
+    audio_manager_beep(440, 100);
+    vTaskDelay(pdMS_TO_TICKS(50));
+    audio_manager_beep(550, 100);
+    vTaskDelay(pdMS_TO_TICKS(50));
+    audio_manager_beep(660, 200);
+}
+
+/* ── App entry point ─────────────────────────────────────────────────────── */
+
+void app_main(void)
+{
+    ESP_LOGI(TAG, "╔══════════════════════════════╗");
+    ESP_LOGI(TAG, "║     Debbie — v1.0.0          ║");
+    ESP_LOGI(TAG, "║  Portable Personal AI Friend  ║");
+    ESP_LOGI(TAG, "╚══════════════════════════════╝");
+
+    /* 1. NVS + configuration */
+    ESP_ERROR_CHECK(storage_init());
+
+    /* 1b. Memory manager — loads persisted facts & recent turns from NVS */
+    memory_manager_init();
+
+    /* 2. Display — show boot splash as early as possible */
+    ESP_ERROR_CHECK(display_manager_init());
+    set_state(DEBBIE_STATE_BOOT);
+    show_boot_splash();
+
+    /* 3. Audio */
+    ESP_ERROR_CHECK(audio_manager_init());
+    audio_manager_set_volume(g_debbie_config.speaker_volume);
+
+    /* 4. Camera */
+    if (g_debbie_config.camera_enabled) {
+        esp_err_t cam_err = camera_manager_init();
+        if (cam_err != ESP_OK) {
+            ESP_LOGW(TAG, "Camera init failed — camera features disabled");
+            g_debbie_config.camera_enabled = false;
+        }
+    }
+
+    /* 5. GPIO / buttons */
+    gpio_init();
+
+    /* 6. WiFi */
+    set_state(DEBBIE_STATE_CONNECTING);
+    display_manager_show_text("📶 Connecting to WiFi...");
+    display_manager_set_connection_status(false, false);
+
+    esp_err_t wifi_err = wifi_manager_init();
+
+    /* 7. Bluetooth (BLE) — start alongside WiFi */
+    bluetooth_manager_init();  /* silently skips if bt disabled in config */
+
+    /* 8. Always start the web server (for setup and status) */
+    ESP_ERROR_CHECK(web_server_start());
+
+    /* 9. Network scanner — init after WiFi (even before connecting) */
+    ESP_ERROR_CHECK(net_scanner_init());
+
+    if (wifi_err != ESP_OK) {
+        /* No WiFi — enter setup mode */
+        set_state(DEBBIE_STATE_SETUP);
+        display_manager_show_text(
+            "⚙️ Setup needed!\n\n"
+            "Connect to WiFi: \"Debbie\"\n"
+            "Then visit: 192.168.4.1\n"
+            "to configure your settings.");
+        ESP_LOGI(TAG, "No WiFi — in setup mode at %s", DEBBIE_AP_IP);
+
+        /* Stay in setup mode loop */
+        while (1) vTaskDelay(pdMS_TO_TICKS(1000));
+    }
+
+    display_manager_set_connection_status(true, false);
+    display_manager_show_text("✅ Connected!\nConnecting to AI...");
+
+    /* 9. Companion server notifications */
+    if (g_debbie_config.notifications_enabled &&
+        strlen(g_debbie_config.companion_url) > 0) {
+        esp_err_t notif_err = notification_client_init(
+            g_debbie_config.companion_url,
+            on_notification, NULL);
+        if (notif_err == ESP_OK) {
+            ESP_LOGI(TAG, "Notification client connecting to %s",
+                     g_debbie_config.companion_url);
+        }
+    } else {
+        ESP_LOGI(TAG, "Companion server not configured — notifications disabled");
+    }
+
+    /* 10. Battery monitor */
+    xTaskCreate(battery_task, "battery", 2048, NULL, 1, NULL);
+
+    /* 11. Connect to AI (inject memory context into system prompt) */
+    if (strlen(g_debbie_config.openai_api_key) > 0) {
+        /* Build memory-enriched system prompt */
+        char *enriched_prompt = memory_manager_enrich_prompt(
+            g_debbie_config.system_prompt);
+        const char *prompt_to_use = enriched_prompt
+            ? enriched_prompt : g_debbie_config.system_prompt;
+
+        esp_err_t ai_err = openai_client_connect(
+            g_debbie_config.openai_api_key,
+            prompt_to_use,
+            on_oai_event, NULL);
+
+        free(enriched_prompt); /* safe even if NULL */
+
+        if (ai_err != ESP_OK) {
+            ESP_LOGW(TAG, "Could not connect to OpenAI — check API key");
+            display_manager_show_text(
+                "⚠️ AI connection failed.\n"
+                "Check your API key at\n"
+                "192.168.4.1 or say 'setup'.");
+            set_state(DEBBIE_STATE_IDLE);
+        }
+    } else {
+        ESP_LOGW(TAG, "No OpenAI API key — visit 192.168.4.1 to configure");
+        display_manager_show_text(
+            "👋 Hi! I'm Debbie!\n\n"
+            "Please add your API key:\n"
+            "Visit 192.168.4.1 in\nyour browser.\n\n"
+            "Or connect me to your\nown AI agent!");
+        set_state(DEBBIE_STATE_IDLE);
+    }
+
+    /* 12. Start microphone — continuous VAD listening */
+    ESP_ERROR_CHECK(audio_manager_start_capture(on_audio_capture));
+    ESP_LOGI(TAG, "Debbie is ready! 🎉 (Network scanner active, say 'scan my network' to start)");
+
+    /* Main loop — lightweight, most work is in callbacks and tasks */
+    while (1) {
+        /* Periodic reconnect if AI disconnects */
+        if (g_debbie_state != DEBBIE_STATE_SETUP &&
+            wifi_manager_is_connected() &&
+            !openai_client_is_connected() &&
+            strlen(g_debbie_config.openai_api_key) > 0) {
+            ESP_LOGI(TAG, "Reconnecting to OpenAI...");
+            display_manager_show_text("Reconnecting...");
+            openai_client_connect(
+                g_debbie_config.openai_api_key,
+                g_debbie_config.system_prompt,
+                on_oai_event, NULL);
+        }
+        vTaskDelay(pdMS_TO_TICKS(15000));
+    }
+}
diff --git a/firmware/main/memory_manager.c b/firmware/main/memory_manager.c
new file mode 100644
index 0000000..9b66238
--- /dev/null
+++ b/firmware/main/memory_manager.c
@@ -0,0 +1,534 @@
+/*
+ * memory_manager.c — Debbie's short-term & long-term memory + RAG
+ *
+ * Short-term : circular buffer of recent turns in RAM.
+ * Long-term  : key-value facts persisted to NVS flash.
+ * RAG        : companion server queried via HTTP for richer context.
+ */
+
+#include "memory_manager.h"
+#include "debbie.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "esp_http_client.h"
+#include "esp_timer.h"
+#include "nvs_flash.h"
+#include "nvs.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "cJSON.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+static const char *TAG = "mem";
+
+#define NVS_MEM_NS   "debbie_mem"
+
+/* ── State ───────────────────────────────────────────────────────────────── */
+
+/* Short-term: ring buffer */
+static memory_turn_t s_turns[MEMORY_MAX_TURNS];
+static int           s_turn_head  = 0;   /* next write position */
+static int           s_turn_count = 0;   /* how many are populated */
+
+/* Long-term facts */
+static memory_fact_t s_facts[MEMORY_MAX_FACTS];
+static int           s_fact_count = 0;
+
+/* ── NVS helpers ─────────────────────────────────────────────────────────── */
+
+static void nvs_write_facts(nvs_handle_t nvs)
+{
+    nvs_set_u8(nvs, "mem_n_facts", (uint8_t)s_fact_count);
+    char key[16];
+    for (int i = 0; i < s_fact_count; i++) {
+        /* Serialise each fact as compact JSON */
+        cJSON *j = cJSON_CreateObject();
+        cJSON_AddStringToObject(j, "k", s_facts[i].key);
+        cJSON_AddStringToObject(j, "v", s_facts[i].value);
+        cJSON_AddNumberToObject(j, "i", s_facts[i].importance);
+        cJSON_AddNumberToObject(j, "t", (double)s_facts[i].timestamp_ms);
+        char *str = cJSON_PrintUnformatted(j);
+        cJSON_Delete(j);
+        if (!str) continue;
+        snprintf(key, sizeof(key), "mf%d", i);
+        nvs_set_str(nvs, key, str);
+        free(str);
+    }
+}
+
+static void nvs_write_recent_turns(nvs_handle_t nvs)
+{
+    /* Persist last 5 turns so memory survives a reboot */
+    int keep = s_turn_count < 5 ? s_turn_count : 5;
+    nvs_set_u8(nvs, "mem_n_turns", (uint8_t)keep);
+    char key[16];
+    for (int i = 0; i < keep; i++) {
+        int idx = ((s_turn_head - keep + i) + MEMORY_MAX_TURNS) % MEMORY_MAX_TURNS;
+        cJSON *j = cJSON_CreateObject();
+        cJSON_AddStringToObject(j, "r", s_turns[idx].role);
+        cJSON_AddStringToObject(j, "t", s_turns[idx].text);
+        cJSON_AddNumberToObject(j, "s", (double)s_turns[idx].timestamp_ms);
+        char *str = cJSON_PrintUnformatted(j);
+        cJSON_Delete(j);
+        if (!str) continue;
+        snprintf(key, sizeof(key), "mt%d", i);
+        nvs_set_str(nvs, key, str);
+        free(str);
+    }
+}
+
+static void nvs_read_facts(nvs_handle_t nvs)
+{
+    uint8_t count = 0;
+    if (nvs_get_u8(nvs, "mem_n_facts", &count) != ESP_OK) return;
+    if (count > MEMORY_MAX_FACTS) count = MEMORY_MAX_FACTS;
+
+    char key[16];
+    for (int i = 0; i < (int)count; i++) {
+        snprintf(key, sizeof(key), "mf%d", i);
+        char buf[300];
+        size_t len = sizeof(buf);
+        if (nvs_get_str(nvs, key, buf, &len) != ESP_OK) continue;
+
+        cJSON *j = cJSON_Parse(buf);
+        if (!j) continue;
+        cJSON *k = cJSON_GetObjectItem(j, "k");
+        cJSON *v = cJSON_GetObjectItem(j, "v");
+        cJSON *imp = cJSON_GetObjectItem(j, "i");
+        cJSON *ts  = cJSON_GetObjectItem(j, "t");
+        if (k && v && cJSON_IsString(k) && cJSON_IsString(v)) {
+            strncpy(s_facts[s_fact_count].key,   k->valuestring,
+                    sizeof(s_facts[s_fact_count].key) - 1);
+            strncpy(s_facts[s_fact_count].value, v->valuestring,
+                    sizeof(s_facts[s_fact_count].value) - 1);
+            s_facts[s_fact_count].importance    = imp ? (uint8_t)imp->valuedouble : 5;
+            s_facts[s_fact_count].timestamp_ms  = ts  ? (int64_t)ts->valuedouble  : 0;
+            s_fact_count++;
+        }
+        cJSON_Delete(j);
+    }
+    ESP_LOGI(TAG, "Loaded %d long-term facts from NVS", s_fact_count);
+}
+
+static void nvs_read_turns(nvs_handle_t nvs)
+{
+    uint8_t count = 0;
+    if (nvs_get_u8(nvs, "mem_n_turns", &count) != ESP_OK) return;
+    if (count > 5) count = 5;
+
+    char key[16];
+    for (int i = 0; i < (int)count; i++) {
+        snprintf(key, sizeof(key), "mt%d", i);
+        char buf[600];
+        size_t len = sizeof(buf);
+        if (nvs_get_str(nvs, key, buf, &len) != ESP_OK) continue;
+
+        cJSON *j  = cJSON_Parse(buf);
+        if (!j) continue;
+        cJSON *r  = cJSON_GetObjectItem(j, "r");
+        cJSON *t  = cJSON_GetObjectItem(j, "t");
+        cJSON *ts = cJSON_GetObjectItem(j, "s");
+        if (r && t && cJSON_IsString(r) && cJSON_IsString(t)) {
+            strncpy(s_turns[s_turn_head].role, r->valuestring,
+                    sizeof(s_turns[s_turn_head].role) - 1);
+            strncpy(s_turns[s_turn_head].text, t->valuestring,
+                    sizeof(s_turns[s_turn_head].text) - 1);
+            s_turns[s_turn_head].timestamp_ms = ts ? (int64_t)ts->valuedouble : 0;
+            s_turn_head = (s_turn_head + 1) % MEMORY_MAX_TURNS;
+            s_turn_count++;
+        }
+        cJSON_Delete(j);
+    }
+    ESP_LOGI(TAG, "Loaded %d recent turns from NVS", s_turn_count);
+}
+
+/* ── HTTP helper ─────────────────────────────────────────────────────────── */
+
+typedef struct { char *buf; int len; int cap; } http_resp_t;
+
+static esp_err_t http_on_data(esp_http_client_event_t *evt)
+{
+    http_resp_t *r = (http_resp_t *)evt->user_data;
+    if (evt->event_id == HTTP_EVENT_ON_DATA && r) {
+        int needed = r->len + evt->data_len + 1;
+        if (needed > r->cap) {
+            int newcap = needed + 512;
+            char *tmp = realloc(r->buf, newcap);
+            if (!tmp) return ESP_FAIL;
+            r->buf = tmp;
+            r->cap = newcap;
+        }
+        memcpy(r->buf + r->len, evt->data, evt->data_len);
+        r->len += evt->data_len;
+        r->buf[r->len] = '\0';
+    }
+    return ESP_OK;
+}
+
+/* Fire-and-forget HTTP POST with a JSON body; returns true on 2xx. */
+static bool http_post_json(const char *url, const char *json_body)
+{
+    esp_http_client_config_t cfg = {
+        .url                      = url,
+        .timeout_ms               = 4000,
+        .method                   = HTTP_METHOD_POST,
+        .skip_cert_common_name_check = true,
+    };
+    esp_http_client_handle_t cli = esp_http_client_init(&cfg);
+    if (!cli) return false;
+    esp_http_client_set_header(cli, "Content-Type", "application/json");
+    esp_http_client_set_post_field(cli, json_body, (int)strlen(json_body));
+    esp_err_t err = esp_http_client_perform(cli);
+    int status    = esp_http_client_get_status_code(cli);
+    esp_http_client_cleanup(cli);
+    return (err == ESP_OK && status >= 200 && status < 300);
+}
+
+/* HTTP GET returning heap-allocated body, or NULL. Caller must free(). */
+static char *http_get(const char *url, int max_bytes)
+{
+    if (max_bytes <= 0 || max_bytes > 8192) max_bytes = 2048;
+    http_resp_t resp = { .buf = malloc(512), .len = 0, .cap = 512 };
+    if (!resp.buf) return NULL;
+    resp.buf[0] = '\0';
+
+    esp_http_client_config_t cfg = {
+        .url                      = url,
+        .timeout_ms               = 5000,
+        .event_handler            = http_on_data,
+        .user_data                = &resp,
+        .skip_cert_common_name_check = true,
+    };
+    esp_http_client_handle_t cli = esp_http_client_init(&cfg);
+    if (!cli) { free(resp.buf); return NULL; }
+
+    esp_err_t err = esp_http_client_perform(cli);
+    int status    = esp_http_client_get_status_code(cli);
+    esp_http_client_cleanup(cli);
+
+    if (err != ESP_OK || status < 200 || status >= 300) {
+        free(resp.buf);
+        return NULL;
+    }
+
+    /* Truncate to max_bytes */
+    if (resp.len > max_bytes) {
+        resp.buf[max_bytes] = '\0';
+    }
+    return resp.buf;
+}
+
+/* Build HTTP companion URL from base (ws://... or http://...) + path */
+static void make_companion_url(char *out, size_t out_sz, const char *path)
+{
+    /* companion_url may be ws:// or http:// — normalise to http:// */
+    const char *base = g_debbie_config.companion_url;
+    if (strncmp(base, "ws://", 5) == 0) {
+        snprintf(out, out_sz, "http://%s%s", base + 5, path);
+    } else if (strncmp(base, "wss://", 6) == 0) {
+        snprintf(out, out_sz, "https://%s%s", base + 6, path);
+    } else {
+        snprintf(out, out_sz, "%s%s", base, path);
+    }
+}
+
+/* ── Public API ──────────────────────────────────────────────────────────── */
+
+esp_err_t memory_manager_init(void)
+{
+    memset(s_turns, 0, sizeof(s_turns));
+    memset(s_facts, 0, sizeof(s_facts));
+    s_turn_head  = 0;
+    s_turn_count = 0;
+    s_fact_count = 0;
+
+    if (!g_debbie_config.memory_enabled) {
+        ESP_LOGI(TAG, "Memory disabled — skipping load");
+        return ESP_OK;
+    }
+
+    nvs_handle_t nvs;
+    esp_err_t err = nvs_open(NVS_MEM_NS, NVS_READONLY, &nvs);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
+        ESP_LOGI(TAG, "No saved memory — starting fresh");
+        return ESP_OK;
+    }
+    if (err != ESP_OK) return err;
+
+    nvs_read_facts(nvs);
+    nvs_read_turns(nvs);
+    nvs_close(nvs);
+
+    ESP_LOGI(TAG, "Memory initialised: %d facts, %d recent turns",
+             s_fact_count, s_turn_count);
+    return ESP_OK;
+}
+
+esp_err_t memory_manager_save(void)
+{
+    if (!g_debbie_config.memory_enabled) return ESP_OK;
+
+    nvs_handle_t nvs;
+    esp_err_t err = nvs_open(NVS_MEM_NS, NVS_READWRITE, &nvs);
+    if (err != ESP_OK) return err;
+
+    nvs_write_facts(nvs);
+    nvs_write_recent_turns(nvs);
+    nvs_commit(nvs);
+    nvs_close(nvs);
+    return ESP_OK;
+}
+
+esp_err_t memory_manager_clear(void)
+{
+    memset(s_turns, 0, sizeof(s_turns));
+    memset(s_facts, 0, sizeof(s_facts));
+    s_turn_head  = 0;
+    s_turn_count = 0;
+    s_fact_count = 0;
+
+    nvs_handle_t nvs;
+    esp_err_t err = nvs_open(NVS_MEM_NS, NVS_READWRITE, &nvs);
+    if (err != ESP_OK) return err;
+    nvs_erase_all(nvs);
+    nvs_commit(nvs);
+    nvs_close(nvs);
+    ESP_LOGI(TAG, "Memory cleared");
+    return ESP_OK;
+}
+
+void memory_manager_add_turn(const char *role, const char *text)
+{
+    if (!g_debbie_config.memory_enabled) return;
+    if (!role || !text || strlen(text) == 0) return;
+
+    memory_turn_t *slot = &s_turns[s_turn_head];
+    strncpy(slot->role, role, sizeof(slot->role) - 1);
+    strncpy(slot->text, text, sizeof(slot->text) - 1);
+    slot->text[sizeof(slot->text) - 1] = '\0';
+    slot->timestamp_ms = (int64_t)(esp_timer_get_time() / 1000);
+
+    s_turn_head = (s_turn_head + 1) % MEMORY_MAX_TURNS;
+    if (s_turn_count < MEMORY_MAX_TURNS) s_turn_count++;
+
+    /* Persist asynchronously every 4 turns to avoid NVS wear */
+    if (s_turn_count % 4 == 0) {
+        memory_manager_save();
+    }
+}
+
+const memory_turn_t *memory_manager_get_turns(void) { return s_turns; }
+int  memory_manager_turn_count(void)               { return s_turn_count; }
+
+esp_err_t memory_manager_save_fact(const char *key,
+                                   const char *value,
+                                   uint8_t     importance)
+{
+    if (!key || !value || strlen(key) == 0) return ESP_ERR_INVALID_ARG;
+
+    /* Update existing fact if key matches */
+    for (int i = 0; i < s_fact_count; i++) {
+        if (strcmp(s_facts[i].key, key) == 0) {
+            strncpy(s_facts[i].value, value, sizeof(s_facts[i].value) - 1);
+            s_facts[i].importance   = importance;
+            s_facts[i].timestamp_ms = (int64_t)(esp_timer_get_time() / 1000);
+            ESP_LOGI(TAG, "Updated fact: %s = %s", key, value);
+            return memory_manager_save();
+        }
+    }
+
+    /* Add new fact */
+    if (s_fact_count >= MEMORY_MAX_FACTS) {
+        /* Evict the oldest, least important fact */
+        int evict = 0;
+        for (int i = 1; i < s_fact_count; i++) {
+            if (s_facts[i].importance < s_facts[evict].importance)
+                evict = i;
+        }
+        memmove(&s_facts[evict], &s_facts[evict + 1],
+                sizeof(memory_fact_t) * (s_fact_count - evict - 1));
+        s_fact_count--;
+    }
+
+    strncpy(s_facts[s_fact_count].key,   key,   sizeof(s_facts[s_fact_count].key)   - 1);
+    strncpy(s_facts[s_fact_count].value, value, sizeof(s_facts[s_fact_count].value) - 1);
+    s_facts[s_fact_count].importance   = importance;
+    s_facts[s_fact_count].timestamp_ms = (int64_t)(esp_timer_get_time() / 1000);
+    s_fact_count++;
+
+    ESP_LOGI(TAG, "Saved fact [%d]: %s = %s", s_fact_count - 1, key, value);
+    return memory_manager_save();
+}
+
+const memory_fact_t *memory_manager_get_facts(int *count_out)
+{
+    if (count_out) *count_out = s_fact_count;
+    return s_facts;
+}
+
+char *memory_manager_build_context(void)
+{
+    if (!g_debbie_config.memory_enabled) return NULL;
+    if (s_turn_count == 0 && s_fact_count == 0) return NULL;
+
+    char *ctx = malloc(MEMORY_CONTEXT_MAX);
+    if (!ctx) return NULL;
+    ctx[0] = '\0';
+    int pos = 0;
+
+#define CTX_APPEND(fmt, ...) \
+    do { \
+        int _n = snprintf(ctx + pos, MEMORY_CONTEXT_MAX - pos, fmt, ##__VA_ARGS__); \
+        if (_n > 0) pos += _n; \
+    } while (0)
+
+    CTX_APPEND("\n\n--- MEMORY ---\n");
+
+    /* Long-term facts */
+    if (s_fact_count > 0) {
+        CTX_APPEND("Known facts:");
+        for (int i = 0; i < s_fact_count && pos < MEMORY_CONTEXT_MAX - 64; i++) {
+            CTX_APPEND(" %s=%s;", s_facts[i].key, s_facts[i].value);
+        }
+        CTX_APPEND("\n");
+    }
+
+    /* Recent conversation — last min(s_turn_count, 10) turns */
+    if (s_turn_count > 0) {
+        int show = s_turn_count < 10 ? s_turn_count : 10;
+        CTX_APPEND("Recent conversation:\n");
+        for (int i = 0; i < show && pos < MEMORY_CONTEXT_MAX - 128; i++) {
+            int idx = ((s_turn_head - show + i) + MEMORY_MAX_TURNS) % MEMORY_MAX_TURNS;
+            CTX_APPEND("  %s: %s\n", s_turns[idx].role, s_turns[idx].text);
+        }
+    }
+
+    CTX_APPEND("--- END MEMORY ---\n");
+    return ctx;
+}
+
+char *memory_manager_enrich_prompt(const char *base_prompt)
+{
+    char *ctx = memory_manager_build_context();
+    if (!ctx) {
+        /* No memory — just duplicate the base prompt */
+        return base_prompt ? strdup(base_prompt) : NULL;
+    }
+
+    size_t base_len = base_prompt ? strlen(base_prompt) : 0;
+    size_t ctx_len  = strlen(ctx);
+    char  *out      = malloc(base_len + ctx_len + 4);
+    if (!out) { free(ctx); return NULL; }
+
+    if (base_prompt) {
+        memcpy(out, base_prompt, base_len);
+        out[base_len] = '\0';
+    } else {
+        out[0] = '\0';
+    }
+    strncat(out, ctx, ctx_len);
+    free(ctx);
+    return out;
+}
+
+char *memory_manager_query_rag(const char *query)
+{
+    if (!g_debbie_config.memory_enabled ||
+        !g_debbie_config.memory_rag_enabled) return NULL;
+    if (!query || strlen(query) == 0) return NULL;
+    if (strlen(g_debbie_config.companion_url) == 0) return NULL;
+
+    /* Build URL: http://<companion>/memory/query?q=<encoded_query>&limit=5 */
+    char url[512];
+    char companion_http[256];
+    make_companion_url(companion_http, sizeof(companion_http), "");
+    /* Strip trailing slash from base */
+    int base_len = (int)strlen(companion_http);
+    while (base_len > 0 && companion_http[base_len - 1] == '/') {
+        companion_http[--base_len] = '\0';
+    }
+
+    /* Simple percent-encoding of the query (spaces → %20) */
+    char encoded_query[256] = {0};
+    int qi = 0, ei = 0;
+    while (query[qi] && ei < (int)sizeof(encoded_query) - 4) {
+        char c = query[qi++];
+        if (c == ' ') {
+            encoded_query[ei++] = '%';
+            encoded_query[ei++] = '2';
+            encoded_query[ei++] = '0';
+        } else if ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') ||
+                   (c >= '0' && c <= '9') || c == '-' || c == '_' ||
+                   c == '.' || c == '~') {
+            encoded_query[ei++] = c;
+        } else {
+            ei += snprintf(encoded_query + ei, sizeof(encoded_query) - ei,
+                           "%%%02X", (unsigned char)c);
+        }
+    }
+
+    snprintf(url, sizeof(url), "%s/memory/query?q=%s&limit=5",
+             companion_http, encoded_query);
+
+    char *body = http_get(url, 2048);
+    if (!body) return NULL;
+
+    /* The companion returns JSON: {"memories":[{"text":"..."},...]}
+     * Extract into a plain text summary */
+    cJSON *json = cJSON_Parse(body);
+    free(body);
+    if (!json) return NULL;
+
+    cJSON *mems = cJSON_GetObjectItem(json, "memories");
+    if (!mems || !cJSON_IsArray(mems) || cJSON_GetArraySize(mems) == 0) {
+        cJSON_Delete(json);
+        return NULL;
+    }
+
+    char *summary = malloc(1024);
+    if (!summary) { cJSON_Delete(json); return NULL; }
+    summary[0] = '\0';
+    strncat(summary, "Relevant memories: ", 1023);
+
+    int n = cJSON_GetArraySize(mems);
+    for (int i = 0; i < n; i++) {
+        cJSON *m    = cJSON_GetArrayItem(mems, i);
+        cJSON *text = cJSON_GetObjectItem(m, "text");
+        if (text && cJSON_IsString(text)) {
+            int rem = (int)(1023 - strlen(summary));
+            if (rem > 4) {
+                strncat(summary, text->valuestring, rem - 2);
+                if (i < n - 1) strncat(summary, ". ", 2);
+            }
+        }
+    }
+    cJSON_Delete(json);
+    return summary;
+}
+
+void memory_manager_sync_turn(const char *role, const char *text)
+{
+    if (!g_debbie_config.memory_enabled ||
+        !g_debbie_config.memory_rag_enabled) return;
+    if (strlen(g_debbie_config.companion_url) == 0) return;
+    if (!role || !text || strlen(text) == 0) return;
+
+    /* Build JSON body */
+    cJSON *j = cJSON_CreateObject();
+    cJSON_AddStringToObject(j, "role", role);
+    cJSON_AddStringToObject(j, "text", text);
+    cJSON_AddNumberToObject(j, "ts",
+        (double)(esp_timer_get_time() / 1000));
+    char *body = cJSON_PrintUnformatted(j);
+    cJSON_Delete(j);
+    if (!body) return;
+
+    char url[256];
+    make_companion_url(url, sizeof(url), "/memory/turn");
+
+    /* Best-effort: ignore errors — we don't want to block audio pipeline */
+    http_post_json(url, body);
+    free(body);
+}
diff --git a/firmware/main/memory_manager.h b/firmware/main/memory_manager.h
new file mode 100644
index 0000000..5d69d8f
--- /dev/null
+++ b/firmware/main/memory_manager.h
@@ -0,0 +1,140 @@
+#pragma once
+/*
+ * memory_manager.h — Debbie's short-term & long-term memory
+ *
+ * Short-term memory: a circular buffer of the last MEMORY_MAX_TURNS
+ *   conversation turns (user + assistant) kept in RAM.
+ *
+ * Long-term memory: up to MEMORY_MAX_FACTS key-value "facts" (e.g.
+ *   "user_name=Alice", "user_likes=jazz") persisted to NVS flash.
+ *
+ * RAG: on request, queries the companion server's /memory/query endpoint
+ *   and appends the retrieved context to the system prompt.
+ */
+
+#include "esp_err.h"
+#include <stdbool.h>
+#include <stdint.h>
+
+/* ── Limits ───────────────────────────────────────────────────────────────── */
+#define MEMORY_MAX_TURNS    20      /* recent turns kept in RAM */
+#define MEMORY_MAX_FACTS    50      /* long-term facts in NVS */
+#define MEMORY_FACT_KEY_MAX 48      /* max chars for a fact key */
+#define MEMORY_FACT_VAL_MAX 192     /* max chars for a fact value */
+#define MEMORY_TURN_TEXT_MAX 512    /* max chars per turn */
+#define MEMORY_CONTEXT_MAX  4096    /* max chars in built context blob */
+
+/* ── Types ────────────────────────────────────────────────────────────────── */
+
+typedef struct {
+    char    role[12];                       /* "user" or "assistant" */
+    char    text[MEMORY_TURN_TEXT_MAX];
+    int64_t timestamp_ms;
+} memory_turn_t;
+
+typedef struct {
+    char    key[MEMORY_FACT_KEY_MAX];
+    char    value[MEMORY_FACT_VAL_MAX];
+    int64_t timestamp_ms;
+    uint8_t importance;                     /* 0-10 */
+} memory_fact_t;
+
+/* ── Lifecycle ────────────────────────────────────────────────────────────── */
+
+/**
+ * @brief  Initialise memory manager.
+ *         Loads saved facts (and last-N turns) from NVS.
+ *         Call once after storage_init().
+ */
+esp_err_t memory_manager_init(void);
+
+/**
+ * @brief  Persist current facts (and last 5 turns) to NVS.
+ *         Called automatically after each turn; call explicitly on shutdown.
+ */
+esp_err_t memory_manager_save(void);
+
+/**
+ * @brief  Erase all in-RAM and NVS memory.
+ */
+esp_err_t memory_manager_clear(void);
+
+/* ── Short-term memory ────────────────────────────────────────────────────── */
+
+/**
+ * @brief  Append a conversation turn to the in-RAM circular buffer.
+ *
+ * @param role  "user" or "assistant"
+ * @param text  Transcribed text
+ */
+void memory_manager_add_turn(const char *role, const char *text);
+
+/**
+ * @brief  Return a pointer to the turn circular buffer (read-only).
+ *         Use memory_manager_turn_count() to know how many are valid.
+ */
+const memory_turn_t *memory_manager_get_turns(void);
+
+/** @brief  Number of turns currently in the buffer (0 – MEMORY_MAX_TURNS). */
+int memory_manager_turn_count(void);
+
+/* ── Long-term facts ──────────────────────────────────────────────────────── */
+
+/**
+ * @brief  Store / update a long-term fact in NVS.
+ *
+ * @param key         Identifier (e.g. "user_name", "user_location")
+ * @param value       Value string
+ * @param importance  0-10 (higher = kept longer / shown first)
+ */
+esp_err_t memory_manager_save_fact(const char *key,
+                                   const char *value,
+                                   uint8_t     importance);
+
+/**
+ * @brief  Return all stored facts and their count.
+ */
+const memory_fact_t *memory_manager_get_facts(int *count_out);
+
+/* ── Context building (for system-prompt injection) ───────────────────────── */
+
+/**
+ * @brief  Build a memory context string to prepend to the system prompt.
+ *
+ *  Format:
+ *    [Memory] Facts: user_name=Alice; user_location=London
+ *    [Memory] Recent conversation:
+ *      user: what's the weather like?
+ *      assistant: It's sunny in London today.
+ *
+ * @return  Heap-allocated string — caller must free().
+ *          Returns NULL on allocation failure.
+ */
+char *memory_manager_build_context(void);
+
+/**
+ * @brief  Build an enriched system prompt: base_prompt + memory context.
+ *         Returns a heap-allocated string — caller must free().
+ */
+char *memory_manager_enrich_prompt(const char *base_prompt);
+
+/* ── Companion RAG ────────────────────────────────────────────────────────── */
+
+/**
+ * @brief  Query the companion server for memories relevant to `query`.
+ *         Returns NULL if companion is not reachable or not configured.
+ *         Caller must free() the returned string (it contains a brief
+ *         plain-text summary of retrieved memories).
+ *
+ * @param query  The user's latest utterance.
+ */
+char *memory_manager_query_rag(const char *query);
+
+/**
+ * @brief  Sync a new turn to the companion server's persistent store.
+ *         Non-blocking — fires-and-forgets using a short HTTP POST.
+ *
+ * @param role  "user" or "assistant"
+ * @param text  Turn text
+ */
+void memory_manager_sync_turn(const char *role, const char *text);
diff --git a/firmware/main/network_scanner.c b/firmware/main/network_scanner.c
new file mode 100644
index 0000000..45198cb
--- /dev/null
+++ b/firmware/main/network_scanner.c
@@ -0,0 +1,776 @@
+/*
+ * network_scanner.c — Ethical Network Security Scanner
+ *
+ * ⚠️  AUTHORISED USE ONLY — Only scan networks you own or have
+ *      explicit written permission to test. ⚠️
+ */
+
+#include "network_scanner.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "esp_wifi.h"
+#include "esp_netif.h"
+#include "esp_event.h"
+#include "lwip/sockets.h"
+#include "lwip/netdb.h"
+#include "lwip/inet.h"
+#include "lwip/ip4_addr.h"
+#include "lwip/opt.h"
+#include "ping/ping_sock.h"
+#include "esp_http_client.h"
+#include "cJSON.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+static const char *TAG = "netscan";
+
+/* ── Shared results buffer ────────────────────────────────────────────────── */
+static scan_results_t s_results;
+static SemaphoreHandle_t s_mutex = NULL;
+static bool s_cancel = false;
+
+/* ── Common ports to probe (curated security-relevant set) ───────────────── */
+typedef struct { uint16_t port; const char *service; } port_def_t;
+
+static const port_def_t COMMON_PORTS[] = {
+    /* Remote management */
+    { 22,    "ssh"          },
+    { 23,    "telnet"       },
+    { 3389,  "rdp"          },
+    { 5900,  "vnc"          },
+    { 5901,  "vnc-2"        },
+    { 2222,  "ssh-alt"      },
+    /* Web */
+    { 80,    "http"         },
+    { 443,   "https"        },
+    { 8080,  "http-alt"     },
+    { 8443,  "https-alt"    },
+    { 8888,  "http-alt2"    },
+    { 7080,  "http-alt3"    },
+    { 3000,  "node-http"    },
+    { 4200,  "angular-dev"  },
+    /* File sharing */
+    { 21,    "ftp"          },
+    { 20,    "ftp-data"     },
+    { 445,   "smb"          },
+    { 139,   "netbios"      },
+    { 2049,  "nfs"          },
+    /* Mail */
+    { 25,    "smtp"         },
+    { 587,   "smtp-sub"     },
+    { 110,   "pop3"         },
+    { 143,   "imap"         },
+    { 993,   "imaps"        },
+    { 995,   "pop3s"        },
+    /* Database */
+    { 3306,  "mysql"        },
+    { 5432,  "postgres"     },
+    { 27017, "mongodb"      },
+    { 6379,  "redis"        },
+    { 1433,  "mssql"        },
+    { 1521,  "oracle"       },
+    { 5984,  "couchdb"      },
+    { 9200,  "elasticsearch"},
+    /* IoT / embedded */
+    { 1883,  "mqtt"         },
+    { 8883,  "mqtts"        },
+    { 502,   "modbus"       },
+    { 102,   "s7comm"       },
+    { 4840,  "opcua"        },
+    { 9100,  "printer"      },
+    { 515,   "lpd"          },
+    /* Media / home */
+    { 8096,  "jellyfin"     },
+    { 32400, "plex"         },
+    { 1194,  "openvpn"      },
+    { 500,   "ike-vpn"      },
+    /* Admin panels */
+    { 8181,  "admin-alt"    },
+    { 9090,  "prometheus"   },
+    { 3001,  "grafana-alt"  },
+    { 9000,  "portainer"    },
+    { 2375,  "docker"       },
+    { 2376,  "dockerssl"    },
+    /* DNS / network */
+    { 53,    "dns"          },
+    { 67,    "dhcp"         },
+    { 123,   "ntp"          },
+    { 161,   "snmp"         },
+    /* Misc */
+    { 6667,  "irc"          },
+    { 1080,  "socks"        },
+    { 3128,  "squid"        },
+};
+#define COMMON_PORTS_COUNT (sizeof(COMMON_PORTS) / sizeof(COMMON_PORTS[0]))
+
+/* ── MAC OUI vendor lookup (small embedded table) ─────────────────────────── */
+typedef struct { uint8_t oui[3]; const char *vendor; } oui_entry_t;
+static const oui_entry_t OUI_TABLE[] = {
+    { {0xB8,0x27,0xEB}, "Raspberry Pi" },
+    { {0xDC,0xA6,0x32}, "Raspberry Pi" },
+    { {0xE4,0x5F,0x01}, "Raspberry Pi" },
+    { {0x00,0x50,0x56}, "VMware"       },
+    { {0x00,0x0C,0x29}, "VMware"       },
+    { {0xAC,0x87,0xA3}, "Apple"        },
+    { {0x00,0x17,0xF2}, "Apple"        },
+    { {0x78,0x4F,0x43}, "Samsung"      },
+    { {0x00,0x25,0xAB}, "Cisco"        },
+    { {0x00,0x1A,0xA0}, "Cisco"        },
+    { {0x18,0xFE,0x34}, "Espressif"    },
+    { {0xAC,0xD0,0x74}, "Espressif"    },
+    { {0x10,0x02,0xB5}, "Espressif"    },
+    { {0x24,0x6F,0x28}, "Espressif"    },
+    { {0x30,0xAE,0xA4}, "Espressif"    },
+    { {0xEC,0xFA,0xBC}, "Espressif"    },
+    { {0xA4,0xCF,0x12}, "Espressif"    },
+    { {0x00,0x1B,0x63}, "Apple"        },
+    { {0x00,0x23,0x32}, "Apple"        },
+    { {0xB8,0xC7,0x5D}, "TP-Link"      },
+    { {0xF4,0xEC,0x38}, "TP-Link"      },
+    { {0x50,0xC7,0xBF}, "TP-Link"      },
+};
+#define OUI_TABLE_COUNT (sizeof(OUI_TABLE) / sizeof(OUI_TABLE[0]))
+
+static const char *lookup_vendor(const uint8_t *mac)
+{
+    for (int i = 0; i < (int)OUI_TABLE_COUNT; i++) {
+        if (memcmp(mac, OUI_TABLE[i].oui, 3) == 0)
+            return OUI_TABLE[i].vendor;
+    }
+    return "Unknown";
+}
+
+/* ── Auth mode string ─────────────────────────────────────────────────────── */
+static const char *auth_str(wifi_auth_mode_t mode)
+{
+    switch (mode) {
+    case WIFI_AUTH_OPEN:          return "OPEN";
+    case WIFI_AUTH_WEP:           return "WEP";
+    case WIFI_AUTH_WPA_PSK:       return "WPA";
+    case WIFI_AUTH_WPA2_PSK:      return "WPA2";
+    case WIFI_AUTH_WPA_WPA2_PSK:  return "WPA/WPA2";
+    case WIFI_AUTH_WPA3_PSK:      return "WPA3";
+    case WIFI_AUTH_WPA2_WPA3_PSK: return "WPA2/WPA3";
+    case WIFI_AUTH_WPA2_ENTERPRISE: return "WPA2-ENT";
+    default:                      return "UNKNOWN";
+    }
+}
+
+/* ── Risk scoring ─────────────────────────────────────────────────────────── */
+
+static int score_port(uint16_t port, const char *banner)
+{
+    /* Ports that significantly raise the risk score */
+    switch (port) {
+    case 23:   return 30;  /* Telnet — plaintext, high risk */
+    case 21:   return 20;  /* FTP — plaintext */
+    case 2375: return 40;  /* Docker without TLS — critical */
+    case 6379: return 30;  /* Redis — often unauthenticated */
+    case 27017: return 25; /* MongoDB — often unauthenticated */
+    case 9200: return 25;  /* Elasticsearch — often unauthenticated */
+    case 502:  return 35;  /* Modbus — industrial, critical */
+    case 1883: return 20;  /* MQTT — often unauthenticated */
+    case 161:  return 15;  /* SNMP */
+    case 445:  return 20;  /* SMB */
+    case 139:  return 15;  /* NetBIOS */
+    case 3389: return 15;  /* RDP */
+    case 5900: return 15;  /* VNC */
+    default:   return 5;
+    }
+}
+
+static void compute_risk(host_result_t *host)
+{
+    int score = 0;
+    char findings[256] = "";
+
+    for (int i = 0; i < host->port_count; i++) {
+        if (host->ports[i].state == PORT_STATE_OPEN) {
+            int s = score_port(host->ports[i].port, host->ports[i].banner);
+            score += s;
+
+            if (host->ports[i].port == 23)
+                strncat(findings, "Telnet exposed! ", sizeof(findings)-strlen(findings)-1);
+            if (host->ports[i].port == 2375)
+                strncat(findings, "Docker API exposed (critical)! ", sizeof(findings)-strlen(findings)-1);
+            if (host->ports[i].port == 6379)
+                strncat(findings, "Redis possibly unauthenticated. ", sizeof(findings)-strlen(findings)-1);
+            if (host->ports[i].port == 21)
+                strncat(findings, "FTP open (plaintext). ", sizeof(findings)-strlen(findings)-1);
+            if (host->ports[i].port == 502)
+                strncat(findings, "Modbus ICS protocol exposed! ", sizeof(findings)-strlen(findings)-1);
+        }
+    }
+
+    if (host->has_http && !host->has_https)
+        strncat(findings, "HTTP without HTTPS. ", sizeof(findings)-strlen(findings)-1);
+
+    if (score == 0 && host->port_count > 0)
+        strncat(findings, "Minimal attack surface.", sizeof(findings)-strlen(findings)-1);
+    else if (score == 0)
+        strncat(findings, "No open ports detected.", sizeof(findings)-strlen(findings)-1);
+
+    host->risk_score = score > 100 ? 100 : score;
+    strncpy(host->risk_summary, findings, sizeof(host->risk_summary) - 1);
+}
+
+/* ── TCP port probe ───────────────────────────────────────────────────────── */
+
+static port_state_t tcp_probe(const char *ip, uint16_t port,
+                               char *banner, size_t banner_sz,
+                               uint32_t *rtt_ms)
+{
+    struct sockaddr_in addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_port   = htons(port);
+    if (inet_pton(AF_INET, ip, &addr.sin_addr) != 1)
+        return PORT_STATE_UNKNOWN;
+
+    int sock = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    if (sock < 0) return PORT_STATE_UNKNOWN;
+
+    /* Non-blocking connect with timeout */
+    struct timeval tv = { .tv_sec = 2, .tv_usec = 0 };
+    setsockopt(sock, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
+    setsockopt(sock, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv));
+
+    int64_t t0 = esp_timer_get_time();
+    int rc = connect(sock, (struct sockaddr *)&addr, sizeof(addr));
+    int64_t t1 = esp_timer_get_time();
+
+    if (rtt_ms) *rtt_ms = (uint32_t)((t1 - t0) / 1000);
+
+    if (rc < 0) {
+        close(sock);
+        return PORT_STATE_CLOSED;
+    }
+
+    /* Try to grab a banner */
+    if (banner && banner_sz > 1) {
+        /* Send a minimal HTTP HEAD for web ports */
+        if (port == 80 || port == 8080 || port == 8888 || port == 3000) {
+            const char *req = "HEAD / HTTP/1.0\r\nHost: debbie\r\n\r\n";
+            send(sock, req, strlen(req), 0);
+        }
+        int n = recv(sock, banner, banner_sz - 1, 0);
+        if (n > 0) {
+            banner[n] = '\0';
+            /* Strip non-printable except newlines */
+            for (int i = 0; i < n; i++) {
+                if ((uint8_t)banner[i] < 0x20 && banner[i] != '\n' && banner[i] != '\r')
+                    banner[i] = '.';
+            }
+            /* Truncate at first blank line */
+            char *nl = strstr(banner, "\r\n\r\n");
+            if (nl) *nl = '\0';
+        } else {
+            banner[0] = '\0';
+        }
+    }
+
+    close(sock);
+    return PORT_STATE_OPEN;
+}
+
+/* ── HTTP probe ───────────────────────────────────────────────────────────── */
+
+static void http_probe(host_result_t *host)
+{
+    char url[64];
+    static char resp_buf[512];
+
+    for (int use_https = 0; use_https <= 1; use_https++) {
+        snprintf(url, sizeof(url), "%s://%s:%d/",
+                 use_https ? "https" : "http",
+                 host->ip_str,
+                 use_https ? 443 : 80);
+
+        esp_http_client_config_t cfg = {
+            .url              = url,
+            .timeout_ms       = 3000,
+            .skip_cert_common_name_check = true,
+        };
+        esp_http_client_handle_t cli = esp_http_client_init(&cfg);
+        if (!cli) continue;
+
+        if (esp_http_client_perform(cli) == ESP_OK) {
+            int status = esp_http_client_get_status_code(cli);
+            if (status > 0) {
+                if (use_https) host->has_https = true;
+                else           host->has_http  = true;
+
+                /* Grab Server header */
+                esp_http_client_get_header(cli, "Server",
+                    host->http_server, sizeof(host->http_server) - 1);
+
+                /* Read body to find <title> */
+                int len = esp_http_client_read_response(cli, resp_buf, sizeof(resp_buf) - 1);
+                if (len > 0) {
+                    resp_buf[len] = '\0';
+                    char *title_s = strcasestr(resp_buf, "<title>");
+                    char *title_e = title_s ? strcasestr(title_s + 7, "</title>") : NULL;
+                    if (title_s && title_e) {
+                        int tlen = (int)(title_e - title_s - 7);
+                        if (tlen > 0 && tlen < (int)sizeof(host->http_title) - 1) {
+                            memcpy(host->http_title, title_s + 7, tlen);
+                            host->http_title[tlen] = '\0';
+                        }
+                    }
+                }
+            }
+        }
+        esp_http_client_cleanup(cli);
+    }
+}
+
+/* ── ARP scan ─────────────────────────────────────────────────────────────── */
+
+extern int etharp_request(struct netif *netif, const ip4_addr_t *ipaddr);
+
+static bool arp_ping(uint8_t *target_ip)
+{
+    /* Try a TCP connect to port 80 as ARP-substitute fallback.
+     * A proper ARP implementation requires raw socket or lwIP internals.
+     * On ESP-IDF, we use a quick TCP connect to trigger ARP, then check
+     * the ARP cache via the netif. */
+    char ip_str[16];
+    snprintf(ip_str, sizeof(ip_str), "%d.%d.%d.%d",
+             target_ip[0], target_ip[1], target_ip[2], target_ip[3]);
+
+    /* Quick ICMP ping via the ping socket API */
+    uint32_t rtt = 0;
+    esp_err_t err = net_scanner_ping(ip_str, &rtt);
+    return (err == ESP_OK);
+}
+
+/* ── Public API ───────────────────────────────────────────────────────────── */
+
+esp_err_t net_scanner_init(void)
+{
+    memset(&s_results, 0, sizeof(s_results));
+    if (!s_mutex) s_mutex = xSemaphoreCreateMutex();
+    ESP_LOGI(TAG, "Network scanner initialised");
+    return ESP_OK;
+}
+
+/* ── WiFi scan ───────────────────────────────────────────────────────────── */
+
+esp_err_t net_scanner_wifi_scan(scan_progress_cb_t progress_cb, void *ctx)
+{
+    if (progress_cb) progress_cb(0, "Scanning WiFi networks...", ctx);
+
+    wifi_scan_config_t scan_cfg = {
+        .ssid        = NULL,
+        .bssid       = NULL,
+        .channel     = 0,
+        .show_hidden = true,
+        .scan_type   = WIFI_SCAN_TYPE_ACTIVE,
+    };
+
+    esp_err_t err = esp_wifi_scan_start(&scan_cfg, true /* blocking */);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "WiFi scan failed: %s", esp_err_to_name(err));
+        return err;
+    }
+
+    uint16_t ap_count = MAX_APS;
+    wifi_ap_record_t aps[MAX_APS];
+    memset(aps, 0, sizeof(aps));
+
+    err = esp_wifi_scan_get_ap_records(&ap_count, aps);
+    if (err != ESP_OK) return err;
+
+    if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000))) {
+        s_results.ap_count = ap_count;
+        for (int i = 0; i < ap_count; i++) {
+            wifi_ap_result_t *r = &s_results.aps[i];
+            strncpy(r->ssid, (char *)aps[i].ssid, sizeof(r->ssid) - 1);
+            memcpy(r->bssid, aps[i].bssid, 6);
+            snprintf(r->bssid_str, sizeof(r->bssid_str),
+                     "%02X:%02X:%02X:%02X:%02X:%02X",
+                     aps[i].bssid[0], aps[i].bssid[1], aps[i].bssid[2],
+                     aps[i].bssid[3], aps[i].bssid[4], aps[i].bssid[5]);
+            r->rssi     = aps[i].rssi;
+            r->channel  = aps[i].primary;
+            r->auth_mode = aps[i].authmode;
+            strncpy(r->auth_str, auth_str(aps[i].authmode), sizeof(r->auth_str)-1);
+            r->hidden   = (strlen(r->ssid) == 0);
+        }
+        xSemaphoreGive(s_mutex);
+    }
+
+    ESP_LOGI(TAG, "WiFi scan found %d APs", ap_count);
+    if (progress_cb) progress_cb(100, "WiFi scan complete", ctx);
+    return ESP_OK;
+}
+
+/* ── ARP / host discovery scan ───────────────────────────────────────────── */
+
+esp_err_t net_scanner_arp_scan(scan_progress_cb_t progress_cb,
+                                host_found_cb_t    host_cb,
+                                void              *ctx)
+{
+    /* Get our IP and subnet */
+    esp_netif_t *netif = esp_netif_get_handle_from_ifkey("WIFI_STA_DEF");
+    if (!netif) return ESP_FAIL;
+
+    esp_netif_ip_info_t ip_info;
+    if (esp_netif_get_ip_info(netif, &ip_info) != ESP_OK) return ESP_FAIL;
+
+    uint32_t base_ip  = ntohl(ip_info.ip.addr);
+    uint32_t mask     = ntohl(ip_info.netmask.addr);
+    uint32_t network  = base_ip & mask;
+    uint32_t host_max = ~mask;
+
+    /* Only scan /24 or smaller subnets to avoid very long scans */
+    if (host_max > 254) host_max = 254;
+
+    uint8_t own_ip[4];
+    own_ip[0] = (base_ip >> 24) & 0xFF;
+    own_ip[1] = (base_ip >> 16) & 0xFF;
+    own_ip[2] = (base_ip >> 8)  & 0xFF;
+    own_ip[3] =  base_ip        & 0xFF;
+    snprintf(s_results.own_ip, sizeof(s_results.own_ip),
+             "%d.%d.%d.%d", own_ip[0], own_ip[1], own_ip[2], own_ip[3]);
+
+    uint32_t gw = ntohl(ip_info.gw.addr);
+    snprintf(s_results.gateway_ip, sizeof(s_results.gateway_ip),
+             "%d.%d.%d.%d",
+             (gw>>24)&0xFF, (gw>>16)&0xFF, (gw>>8)&0xFF, gw&0xFF);
+
+    snprintf(s_results.subnet_mask, sizeof(s_results.subnet_mask),
+             "%d.%d.%d.%d",
+             (mask>>24)&0xFF, (mask>>16)&0xFF, (mask>>8)&0xFF, mask&0xFF);
+
+    if (progress_cb) progress_cb(0, "Discovering hosts on subnet...", ctx);
+
+    s_results.host_count = 0;
+    int found = 0;
+
+    for (uint32_t i = 1; i <= host_max && !s_cancel; i++) {
+        uint32_t target = network | i;
+        uint8_t tip[4] = {
+            (target >> 24) & 0xFF,
+            (target >> 16) & 0xFF,
+            (target >>  8) & 0xFF,
+             target        & 0xFF,
+        };
+
+        uint8_t pct = (uint8_t)(i * 100 / host_max);
+        if (pct % 5 == 0 && progress_cb) {
+            char stage[48];
+            snprintf(stage, sizeof(stage),
+                     "Scanning %d.%d.%d.%d... (%d found)",
+                     tip[0], tip[1], tip[2], tip[3], found);
+            progress_cb(pct, stage, ctx);
+        }
+
+        if (arp_ping(tip)) {
+            host_result_t host = { 0 };
+            memcpy(host.ip, tip, 4);
+            snprintf(host.ip_str, sizeof(host.ip_str),
+                     "%d.%d.%d.%d", tip[0], tip[1], tip[2], tip[3]);
+            host.alive = true;
+            strncpy(host.vendor, lookup_vendor(host.mac), sizeof(host.vendor)-1);
+
+            if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200))) {
+                if (s_results.host_count < MAX_HOSTS) {
+                    s_results.hosts[s_results.host_count++] = host;
+                }
+                xSemaphoreGive(s_mutex);
+            }
+            found++;
+
+            if (host_cb) host_cb(&host, ctx);
+            ESP_LOGI(TAG, "Host found: %s", host.ip_str);
+        }
+
+        /* Yield every 8 hosts to keep the watchdog happy */
+        if ((i & 7) == 0) vTaskDelay(pdMS_TO_TICKS(5));
+    }
+
+    if (progress_cb) progress_cb(100, "Host discovery complete", ctx);
+    ESP_LOGI(TAG, "ARP scan found %d hosts", found);
+    return ESP_OK;
+}
+
+/* ── Port scan ───────────────────────────────────────────────────────────── */
+
+esp_err_t net_scanner_port_scan(const char    *host_ip,
+                                host_result_t *result,
+                                scan_progress_cb_t progress_cb,
+                                void          *ctx)
+{
+    if (!host_ip || !result) return ESP_ERR_INVALID_ARG;
+
+    int total = (int)COMMON_PORTS_COUNT;
+
+    for (int i = 0; i < total && !s_cancel; i++) {
+        uint16_t port    = COMMON_PORTS[i].port;
+        const char *svc  = COMMON_PORTS[i].service;
+
+        if (i % 10 == 0 && progress_cb) {
+            char stage[48];
+            snprintf(stage, sizeof(stage), "Scanning ports... (%d/%d)", i, total);
+            progress_cb((uint8_t)(i * 100 / total), stage, ctx);
+        }
+
+        char    banner[128] = "";
+        uint32_t rtt        = 0;
+        port_state_t state  = tcp_probe(host_ip, port, banner, sizeof(banner), &rtt);
+
+        if (state == PORT_STATE_OPEN && result->port_count < MAX_OPEN_PORTS) {
+            scan_port_result_t *pr = &result->ports[result->port_count++];
+            pr->port  = port;
+            pr->proto = SCAN_PROTO_TCP;
+            pr->state = PORT_STATE_OPEN;
+            pr->rtt_ms = rtt;
+            strncpy(pr->service, svc,    sizeof(pr->service) - 1);
+            strncpy(pr->banner,  banner, sizeof(pr->banner)  - 1);
+            ESP_LOGI(TAG, "%s:%d open (%s)", host_ip, port, svc);
+        }
+
+        vTaskDelay(pdMS_TO_TICKS(20)); /* pacing — don't flood */
+    }
+
+    /* HTTP-specific probe for richer info */
+    http_probe(result);
+    compute_risk(result);
+
+    if (progress_cb) progress_cb(100, "Port scan complete", ctx);
+    return ESP_OK;
+}
+
+/* ── Ping ─────────────────────────────────────────────────────────────────── */
+
+esp_err_t net_scanner_ping(const char *host_ip, uint32_t *rtt_ms)
+{
+    if (!host_ip) return ESP_ERR_INVALID_ARG;
+
+    /* Use lwip's ping via a TCP connect to a common port as a fallback
+     * since esp_ping requires a callback infrastructure.
+     * For a real ICMP ping, use esp_ping_new_session API. */
+    char    banner[8] = "";
+    uint32_t rtt = 0;
+    port_state_t st = tcp_probe(host_ip, 80, banner, sizeof(banner), &rtt);
+
+    if (st == PORT_STATE_OPEN) {
+        if (rtt_ms) *rtt_ms = rtt;
+        return ESP_OK;
+    }
+
+    /* Try port 443 */
+    st = tcp_probe(host_ip, 443, banner, sizeof(banner), &rtt);
+    if (st == PORT_STATE_OPEN) {
+        if (rtt_ms) *rtt_ms = rtt;
+        return ESP_OK;
+    }
+
+    /* Try port 22 */
+    st = tcp_probe(host_ip, 22, banner, sizeof(banner), &rtt);
+    if (st == PORT_STATE_OPEN) {
+        if (rtt_ms) *rtt_ms = rtt;
+        return ESP_OK;
+    }
+
+    return ESP_FAIL;
+}
+
+/* ── Full scan ────────────────────────────────────────────────────────────── */
+
+typedef struct {
+    scan_progress_cb_t progress_cb;
+    scan_done_cb_t     done_cb;
+    void              *ctx;
+} full_scan_args_t;
+
+static void full_scan_task(void *pvParam)
+{
+    full_scan_args_t *args = (full_scan_args_t *)pvParam;
+    s_cancel = false;
+    s_results.in_progress = true;
+    s_results.scan_start_ms = esp_timer_get_time() / 1000;
+
+    /* Stage 1: WiFi scan */
+    if (!s_cancel) {
+        if (args->progress_cb) args->progress_cb(2, "Stage 1/3: WiFi scan", args->ctx);
+        net_scanner_wifi_scan(NULL, NULL);
+    }
+
+    /* Stage 2: ARP host discovery */
+    if (!s_cancel) {
+        if (args->progress_cb) args->progress_cb(10, "Stage 2/3: Discovering hosts", args->ctx);
+        net_scanner_arp_scan(args->progress_cb, NULL, args->ctx);
+    }
+
+    /* Stage 3: Port scan each host */
+    if (!s_cancel) {
+        int total = s_results.host_count;
+        for (int i = 0; i < total && !s_cancel; i++) {
+            host_result_t *host = &s_results.hosts[i];
+            char stage[64];
+            snprintf(stage, sizeof(stage),
+                     "Stage 3/3: Port scanning %s (%d/%d)",
+                     host->ip_str, i + 1, total);
+            if (args->progress_cb)
+                args->progress_cb((uint8_t)(50 + i * 40 / (total ? total : 1)),
+                                  stage, args->ctx);
+            net_scanner_port_scan(host->ip_str, host, NULL, NULL);
+        }
+    }
+
+    s_results.in_progress       = false;
+    s_results.scan_duration_ms  = esp_timer_get_time() / 1000 - s_results.scan_start_ms;
+
+    if (args->progress_cb) args->progress_cb(100, "Scan complete!", args->ctx);
+    if (args->done_cb) args->done_cb(&s_results, args->ctx);
+
+    ESP_LOGI(TAG, "Full scan done in %lld ms — %d hosts, %d APs",
+             s_results.scan_duration_ms, s_results.host_count, s_results.ap_count);
+
+    free(args);
+    vTaskDelete(NULL);
+}
+
+esp_err_t net_scanner_full_scan(scan_progress_cb_t progress_cb,
+                                 scan_done_cb_t     done_cb,
+                                 void              *ctx)
+{
+    if (s_results.in_progress) {
+        ESP_LOGW(TAG, "Scan already in progress");
+        return ESP_ERR_INVALID_STATE;
+    }
+    /* Reset previous results */
+    memset(&s_results.hosts, 0, sizeof(s_results.hosts));
+    s_results.host_count = 0;
+    memset(&s_results.aps, 0, sizeof(s_results.aps));
+    s_results.ap_count = 0;
+
+    full_scan_args_t *args = malloc(sizeof(full_scan_args_t));
+    if (!args) return ESP_ERR_NO_MEM;
+    args->progress_cb = progress_cb;
+    args->done_cb     = done_cb;
+    args->ctx         = ctx;
+
+    xTaskCreate(full_scan_task, "net_scan", 8192, args,
+                configMAX_PRIORITIES - 4, NULL);
+    return ESP_OK;
+}
+
+void net_scanner_cancel(void)
+{
+    s_cancel = true;
+    ESP_LOGI(TAG, "Scan cancelled");
+}
+
+const scan_results_t *net_scanner_get_results(void) { return &s_results; }
+
+/* ── JSON serialisation ───────────────────────────────────────────────────── */
+
+char *net_scanner_results_to_json(bool include_banners)
+{
+    cJSON *root = cJSON_CreateObject();
+
+    /* Metadata */
+    cJSON_AddStringToObject(root, "own_ip",      s_results.own_ip);
+    cJSON_AddStringToObject(root, "gateway_ip",  s_results.gateway_ip);
+    cJSON_AddStringToObject(root, "subnet_mask", s_results.subnet_mask);
+    cJSON_AddNumberToObject(root, "scan_duration_ms", s_results.scan_duration_ms);
+
+    /* WiFi APs */
+    cJSON *aps = cJSON_CreateArray();
+    for (int i = 0; i < s_results.ap_count; i++) {
+        wifi_ap_result_t *a = &s_results.aps[i];
+        cJSON *ap = cJSON_CreateObject();
+        cJSON_AddStringToObject(ap, "ssid",     a->ssid[0] ? a->ssid : "<hidden>");
+        cJSON_AddStringToObject(ap, "bssid",    a->bssid_str);
+        cJSON_AddNumberToObject(ap, "rssi",     a->rssi);
+        cJSON_AddNumberToObject(ap, "channel",  a->channel);
+        cJSON_AddStringToObject(ap, "security", a->auth_str);
+        cJSON_AddBoolToObject(ap,   "hidden",   a->hidden);
+        cJSON_AddItemToArray(aps, ap);
+    }
+    cJSON_AddItemToObject(root, "wifi_networks", aps);
+
+    /* Hosts */
+    cJSON *hosts = cJSON_CreateArray();
+    for (int i = 0; i < s_results.host_count; i++) {
+        host_result_t *h = &s_results.hosts[i];
+        cJSON *hobj = cJSON_CreateObject();
+        cJSON_AddStringToObject(hobj, "ip",          h->ip_str);
+        cJSON_AddStringToObject(hobj, "mac",         h->mac_str);
+        cJSON_AddStringToObject(hobj, "vendor",      h->vendor);
+        cJSON_AddStringToObject(hobj, "hostname",    h->hostname);
+        cJSON_AddNumberToObject(hobj, "risk_score",  h->risk_score);
+        cJSON_AddStringToObject(hobj, "risk_summary",h->risk_summary);
+        cJSON_AddBoolToObject(hobj,   "has_http",    h->has_http);
+        cJSON_AddBoolToObject(hobj,   "has_https",   h->has_https);
+        if (h->http_title[0])
+            cJSON_AddStringToObject(hobj, "http_title", h->http_title);
+        if (h->http_server[0])
+            cJSON_AddStringToObject(hobj, "http_server",h->http_server);
+
+        cJSON *ports = cJSON_CreateArray();
+        for (int p = 0; p < h->port_count; p++) {
+            scan_port_result_t *pr = &h->ports[p];
+            if (pr->state != PORT_STATE_OPEN) continue;
+            cJSON *pobj = cJSON_CreateObject();
+            cJSON_AddNumberToObject(pobj, "port",    pr->port);
+            cJSON_AddStringToObject(pobj, "service", pr->service);
+            if (include_banners && pr->banner[0])
+                cJSON_AddStringToObject(pobj, "banner", pr->banner);
+            cJSON_AddItemToArray(ports, pobj);
+        }
+        cJSON_AddItemToObject(hobj, "open_ports", ports);
+        cJSON_AddItemToArray(hosts, hobj);
+    }
+    cJSON_AddItemToObject(root, "hosts", hosts);
+
+    char *out = cJSON_PrintUnformatted(root);
+    cJSON_Delete(root);
+    return out;
+}
+
+char *net_scanner_get_summary(void)
+{
+    char *buf = malloc(1024);
+    if (!buf) return NULL;
+
+    int offset = 0;
+    offset += snprintf(buf + offset, 1024 - offset,
+        "Network scan results — %d devices found, %d WiFi networks visible.\n",
+        s_results.host_count, s_results.ap_count);
+
+    /* Open APs warning */
+    int open_aps = 0;
+    for (int i = 0; i < s_results.ap_count; i++)
+        if (s_results.aps[i].auth_mode == WIFI_AUTH_OPEN) open_aps++;
+    if (open_aps > 0)
+        offset += snprintf(buf + offset, 1024 - offset,
+            "⚠️ %d open (unencrypted) WiFi networks nearby.\n", open_aps);
+
+    /* High-risk hosts */
+    int high_risk = 0;
+    for (int i = 0; i < s_results.host_count; i++)
+        if (s_results.hosts[i].risk_score >= 30) high_risk++;
+    if (high_risk > 0)
+        offset += snprintf(buf + offset, 1024 - offset,
+            "🔴 %d high-risk device(s) found.\n", high_risk);
+
+    /* Per-host summary */
+    for (int i = 0; i < s_results.host_count; i++) {
+        host_result_t *h = &s_results.hosts[i];
+        offset += snprintf(buf + offset, 1024 - offset,
+            "%s (%s) — %d open ports, risk %d/100. %s\n",
+            h->ip_str, h->vendor, h->port_count, h->risk_score,
+            h->risk_summary[0] ? h->risk_summary : "");
+        if (offset >= 950) break;
+    }
+
+    return buf;
+}
diff --git a/firmware/main/network_scanner.h b/firmware/main/network_scanner.h
new file mode 100644
index 0000000..dedbf82
--- /dev/null
+++ b/firmware/main/network_scanner.h
@@ -0,0 +1,196 @@
+#pragma once
+/*
+ * network_scanner.h — Ethical Network Security Scanner
+ *
+ * ⚠️  AUTHORISED USE ONLY ⚠️
+ * These tools are intended solely for testing networks you own or have
+ * explicit written authorisation to test. Unauthorised scanning or
+ * probing of networks is illegal in most jurisdictions.
+ *
+ * Features:
+ *  • WiFi network discovery (SSID, BSSID, channel, RSSI, encryption)
+ *  • ARP scan — enumerate live hosts on the local subnet
+ *  • TCP port scan — common service ports with banner grabbing
+ *  • ICMP ping with RTT measurement
+ *  • HTTP/HTTPS probe — detect web servers, titles, server headers
+ *  • Service fingerprinting from banners
+ *  • Results delivered via callback and stored for AI query
+ */
+
+#include "esp_err.h"
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_wifi_types.h"
+
+/* ── Result types ─────────────────────────────────────────────────────────── */
+
+typedef enum {
+    SCAN_PROTO_TCP = 0,
+    SCAN_PROTO_UDP,
+} scan_proto_t;
+
+typedef enum {
+    PORT_STATE_OPEN = 0,
+    PORT_STATE_CLOSED,
+    PORT_STATE_FILTERED,
+    PORT_STATE_UNKNOWN,
+} port_state_t;
+
+typedef struct {
+    uint16_t     port;
+    scan_proto_t proto;
+    port_state_t state;
+    char         service[32];     /* e.g. "http", "ssh", "telnet" */
+    char         banner[128];     /* first response bytes */
+    uint32_t     rtt_ms;
+} scan_port_result_t;
+
+#define MAX_OPEN_PORTS  64
+
+typedef struct {
+    uint8_t  ip[4];               /* IPv4 address */
+    char     ip_str[16];
+    uint8_t  mac[6];
+    char     mac_str[18];
+    char     hostname[64];        /* from reverse DNS / mDNS */
+    char     vendor[48];          /* from MAC OUI lookup */
+    uint32_t rtt_ms;              /* ping RTT */
+    bool     alive;
+
+    /* Port scan results */
+    scan_port_result_t ports[MAX_OPEN_PORTS];
+    int                port_count;
+
+    /* HTTP info */
+    char  http_title[128];
+    char  http_server[64];
+    bool  has_http;
+    bool  has_https;
+
+    /* Risk */
+    int   risk_score;             /* 0–100 */
+    char  risk_summary[256];      /* human-readable findings */
+} host_result_t;
+
+typedef struct {
+    char           ssid[33];
+    uint8_t        bssid[6];
+    char           bssid_str[18];
+    int8_t         rssi;
+    uint8_t        channel;
+    wifi_auth_mode_t auth_mode;
+    char           auth_str[16];  /* "OPEN","WEP","WPA","WPA2","WPA3" */
+    bool           hidden;
+} wifi_ap_result_t;
+
+#define MAX_HOSTS  64
+#define MAX_APS    32
+
+typedef struct {
+    /* WiFi APs visible from this location */
+    wifi_ap_result_t aps[MAX_APS];
+    int              ap_count;
+
+    /* Hosts on local subnet */
+    host_result_t    hosts[MAX_HOSTS];
+    int              host_count;
+
+    /* Our own info */
+    char  own_ip[16];
+    char  own_mac[18];
+    char  gateway_ip[16];
+    char  subnet_mask[16];
+    char  dns_primary[16];
+    char  dns_secondary[16];
+
+    /* Scan metadata */
+    int64_t  scan_start_ms;
+    int64_t  scan_duration_ms;
+    bool     in_progress;
+    uint8_t  progress_pct;        /* 0–100 */
+} scan_results_t;
+
+/* ── Callbacks ────────────────────────────────────────────────────────────── */
+
+/** Called when a host is discovered during ARP scan */
+typedef void (*host_found_cb_t)(const host_result_t *host, void *ctx);
+
+/** Called when entire scan completes */
+typedef void (*scan_done_cb_t)(const scan_results_t *results, void *ctx);
+
+/** Called with progress percentage updates (0–100) */
+typedef void (*scan_progress_cb_t)(uint8_t pct, const char *stage, void *ctx);
+
+/* ── API ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * @brief  Initialise the scanner (call once after WiFi is connected).
+ */
+esp_err_t net_scanner_init(void);
+
+/**
+ * @brief  Scan all visible WiFi access points.
+ *         Results are stored in the shared scan_results_t.
+ */
+esp_err_t net_scanner_wifi_scan(scan_progress_cb_t progress_cb, void *ctx);
+
+/**
+ * @brief  Discover all live hosts on the current subnet via ARP.
+ *
+ * @param progress_cb  Optional progress callback.
+ * @param host_cb      Called immediately when each host responds.
+ * @param ctx          User context.
+ */
+esp_err_t net_scanner_arp_scan(scan_progress_cb_t progress_cb,
+                                host_found_cb_t    host_cb,
+                                void              *ctx);
+
+/**
+ * @brief  Run a port scan against a single host.
+ *         Scans a curated list of ~120 common/high-risk ports.
+ *
+ * @param host_ip   Dotted-decimal IPv4 string.
+ * @param result    Filled in with open ports and banners.
+ */
+esp_err_t net_scanner_port_scan(const char    *host_ip,
+                                host_result_t *result,
+                                scan_progress_cb_t progress_cb,
+                                void          *ctx);
+
+/**
+ * @brief  Run a full scan: WiFi → ARP → port scan all hosts → risk score.
+ *         This is what the AI calls via function tool "full_network_scan".
+ *
+ * @param done_cb  Called when the scan finishes.
+ * @param ctx      User context for callbacks.
+ */
+esp_err_t net_scanner_full_scan(scan_progress_cb_t progress_cb,
+                                 scan_done_cb_t     done_cb,
+                                 void              *ctx);
+
+/**
+ * @brief  Ping a host. Returns ESP_OK if alive.
+ */
+esp_err_t net_scanner_ping(const char *host_ip, uint32_t *rtt_ms);
+
+/**
+ * @brief  Get a pointer to the shared results (read-only).
+ */
+const scan_results_t *net_scanner_get_results(void);
+
+/**
+ * @brief  Serialise scan results to a JSON string.
+ *         Caller must free() the returned pointer.
+ */
+char *net_scanner_results_to_json(bool include_banners);
+
+/**
+ * @brief  Get a concise human-readable summary (for AI/voice output).
+ *         Caller must free() the returned pointer.
+ */
+char *net_scanner_get_summary(void);
+
+/**
+ * @brief  Cancel an in-progress scan.
+ */
+void net_scanner_cancel(void);
diff --git a/firmware/main/notification_client.c b/firmware/main/notification_client.c
new file mode 100644
index 0000000..0dee646
--- /dev/null
+++ b/firmware/main/notification_client.c
@@ -0,0 +1,205 @@
+#include "notification_client.h"
+#include "settings.h"
+#include "esp_log.h"
+#include "esp_websocket_client.h"
+#include "cJSON.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include <string.h>
+#include <stdlib.h>
+
+static const char *TAG = "notif";
+
+#define MAX_NOTIFS 32
+
+static esp_websocket_client_handle_t s_ws      = NULL;
+static notif_cb_t                    s_cb      = NULL;
+static void                         *s_ctx     = NULL;
+static bool                          s_connected = false;
+static SemaphoreHandle_t             s_mutex   = NULL;
+
+static debbie_notification_t s_notifs[MAX_NOTIFS];
+static int                   s_notif_count = 0;
+static int                   s_unread      = 0;
+
+/* -------------------------------------------------------------------------- */
+
+static void ws_event_handler(void *arg, esp_event_base_t base,
+                             int32_t id, void *data)
+{
+    esp_websocket_event_data_t *evt = (esp_websocket_event_data_t *)data;
+
+    switch (id) {
+    case WEBSOCKET_EVENT_CONNECTED:
+        s_connected = true;
+        ESP_LOGI(TAG, "Connected to companion server");
+        break;
+
+    case WEBSOCKET_EVENT_DISCONNECTED:
+        s_connected = false;
+        ESP_LOGW(TAG, "Disconnected from companion server");
+        break;
+
+    case WEBSOCKET_EVENT_DATA: {
+        if (!evt->data_ptr || evt->data_len == 0) break;
+        char *msg = malloc(evt->data_len + 1);
+        if (!msg) break;
+        memcpy(msg, evt->data_ptr, evt->data_len);
+        msg[evt->data_len] = '\0';
+
+        cJSON *json = cJSON_Parse(msg);
+        free(msg);
+        if (!json) break;
+
+        cJSON *type_j    = cJSON_GetObjectItem(json, "type");
+        cJSON *sender_j  = cJSON_GetObjectItem(json, "sender");
+        cJSON *preview_j = cJSON_GetObjectItem(json, "preview");
+
+        if (type_j && cJSON_IsString(type_j)) {
+            debbie_notification_t notif = { 0 };
+
+            const char *type_str = type_j->valuestring;
+            if      (strcmp(type_str, "whatsapp") == 0) notif.type = NOTIF_TYPE_WHATSAPP;
+            else if (strcmp(type_str, "email")    == 0) notif.type = NOTIF_TYPE_EMAIL;
+            else if (strcmp(type_str, "agent")    == 0) notif.type = NOTIF_TYPE_AGENT;
+            else if (strcmp(type_str, "spotify")  == 0) notif.type = NOTIF_TYPE_SPOTIFY;
+            else                                         notif.type = NOTIF_TYPE_SYSTEM;
+
+            if (sender_j  && cJSON_IsString(sender_j))
+                strncpy(notif.sender,  sender_j->valuestring,  sizeof(notif.sender) - 1);
+            if (preview_j && cJSON_IsString(preview_j))
+                strncpy(notif.preview, preview_j->valuestring, sizeof(notif.preview) - 1);
+
+            notif.timestamp_ms = esp_timer_get_time() / 1000;
+            notif.read         = false;
+
+            /* Store in ring buffer */
+            if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100))) {
+                int idx = s_notif_count % MAX_NOTIFS;
+                s_notifs[idx] = notif;
+                s_notif_count++;
+                s_unread++;
+                xSemaphoreGive(s_mutex);
+            }
+
+            ESP_LOGI(TAG, "Notification [%s] from %s: %s",
+                     type_str, notif.sender, notif.preview);
+
+            if (s_cb) s_cb(&notif, s_ctx);
+        }
+
+        cJSON_Delete(json);
+        break;
+    }
+
+    case WEBSOCKET_EVENT_ERROR:
+        ESP_LOGE(TAG, "Companion server WebSocket error");
+        break;
+
+    default:
+        break;
+    }
+}
+
+/* -------------------------------------------------------------------------- */
+
+esp_err_t notification_client_init(const char *server_url,
+                                   notif_cb_t cb,
+                                   void *user_ctx)
+{
+    if (!server_url || strlen(server_url) == 0) {
+        ESP_LOGW(TAG, "No companion server URL — notifications disabled");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    s_cb    = cb;
+    s_ctx   = user_ctx;
+    s_mutex = xSemaphoreCreateMutex();
+
+    const esp_websocket_client_config_t ws_cfg = {
+        .uri                    = server_url,
+        .disable_auto_reconnect = false,
+        .reconnect_timeout_ms   = 10000,
+        .network_timeout_ms     = 5000,
+        .buffer_size            = 4096,
+        .task_stack             = 4096,
+    };
+
+    s_ws = esp_websocket_client_init(&ws_cfg);
+    if (!s_ws) return ESP_FAIL;
+
+    ESP_ERROR_CHECK(esp_websocket_register_events(s_ws, WEBSOCKET_EVENT_ANY,
+                    ws_event_handler, NULL));
+    ESP_ERROR_CHECK(esp_websocket_client_start(s_ws));
+
+    ESP_LOGI(TAG, "Connecting to companion server: %s", server_url);
+    return ESP_OK;
+}
+
+esp_err_t notification_client_deinit(void)
+{
+    if (s_ws) {
+        esp_websocket_client_stop(s_ws);
+        esp_websocket_client_destroy(s_ws);
+        s_ws = NULL;
+    }
+    s_connected = false;
+    return ESP_OK;
+}
+
+bool notification_client_is_connected(void) { return s_connected; }
+
+int notification_client_unread_count(void) { return s_unread; }
+
+void notification_client_clear(void)
+{
+    if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100))) {
+        s_unread = 0;
+        for (int i = 0; i < MAX_NOTIFS; i++) s_notifs[i].read = true;
+        xSemaphoreGive(s_mutex);
+    }
+}
+
+char *notification_client_get_summary_json(void)
+{
+    cJSON *arr = cJSON_CreateArray();
+    if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200))) {
+        int count = s_notif_count < MAX_NOTIFS ? s_notif_count : MAX_NOTIFS;
+        for (int i = 0; i < count; i++) {
+            debbie_notification_t *n = &s_notifs[i];
+            if (n->read) continue;
+            cJSON *obj = cJSON_CreateObject();
+            const char *type_str;
+            switch (n->type) {
+            case NOTIF_TYPE_WHATSAPP: type_str = "whatsapp"; break;
+            case NOTIF_TYPE_EMAIL:    type_str = "email";    break;
+            case NOTIF_TYPE_AGENT:    type_str = "agent";    break;
+            case NOTIF_TYPE_SPOTIFY:  type_str = "spotify";  break;
+            default:                  type_str = "system";   break;
+            }
+            cJSON_AddStringToObject(obj, "type",    type_str);
+            cJSON_AddStringToObject(obj, "sender",  n->sender);
+            cJSON_AddStringToObject(obj, "preview", n->preview);
+            cJSON_AddItemToArray(arr, obj);
+        }
+        xSemaphoreGive(s_mutex);
+    }
+    char *out = cJSON_PrintUnformatted(arr);
+    cJSON_Delete(arr);
+    return out;
+}
+
+esp_err_t notification_client_spotify_command(const char *action)
+{
+    if (!s_connected || !action) return ESP_ERR_INVALID_STATE;
+    cJSON *cmd = cJSON_CreateObject();
+    cJSON_AddStringToObject(cmd, "type",   "spotify_command");
+    cJSON_AddStringToObject(cmd, "action", action);
+    char *str = cJSON_PrintUnformatted(cmd);
+    cJSON_Delete(cmd);
+    if (!str) return ESP_ERR_NO_MEM;
+    esp_websocket_client_send_text(s_ws, str, strlen(str), portMAX_DELAY);
+    free(str);
+    return ESP_OK;
+}
diff --git a/firmware/main/notification_client.h b/firmware/main/notification_client.h
new file mode 100644
index 0000000..754b73d
--- /dev/null
+++ b/firmware/main/notification_client.h
@@ -0,0 +1,57 @@
+#pragma once
+#include "esp_err.h"
+#include "debbie.h"
+#include <stdbool.h>
+
+/**
+ * @brief  Connect to the companion server WebSocket for push notifications.
+ *
+ *  The companion server (Node.js) bridges WhatsApp, email, Spotify, and
+ *  custom agent notifications.  Messages arrive as JSON on the WebSocket
+ *  and are surfaced via the callback set in notification_client_init().
+ */
+
+typedef void (*notif_cb_t)(const debbie_notification_t *notif, void *user_ctx);
+
+/**
+ * @brief  Initialise and connect to the companion server.
+ *
+ * @param server_url   WebSocket URL of companion server, e.g. "ws://192.168.1.10:3001"
+ * @param cb           Callback invoked on new notification (task context).
+ * @param user_ctx     Passed through to callback.
+ */
+esp_err_t notification_client_init(const char *server_url,
+                                   notif_cb_t cb,
+                                   void *user_ctx);
+
+/**
+ * @brief  Disconnect from the companion server.
+ */
+esp_err_t notification_client_deinit(void);
+
+/**
+ * @brief  Return true if connected to companion server.
+ */
+bool notification_client_is_connected(void);
+
+/**
+ * @brief  Get the count of unread notifications.
+ */
+int notification_client_unread_count(void);
+
+/**
+ * @brief  Mark all notifications as read.
+ */
+void notification_client_clear(void);
+
+/**
+ * @brief  Get a summary of pending notifications as a JSON string.
+ *         Caller must free() the returned pointer.
+ */
+char *notification_client_get_summary_json(void);
+
+/**
+ * @brief  Send a Spotify command to the companion server.
+ *         action examples: "play", "pause", "next", "search:lofi beats"
+ */
+esp_err_t notification_client_spotify_command(const char *action);
diff --git a/firmware/main/openai_client.c b/firmware/main/openai_client.c
new file mode 100644
index 0000000..8207a24
--- /dev/null
+++ b/firmware/main/openai_client.c
@@ -0,0 +1,575 @@
+/*
+ * openai_client.c — OpenAI Realtime API WebSocket client
+ *
+ * Voice path  : ESP32 mic → PCM16/24kHz → OpenAI → PCM16/24kHz → speaker
+ * Vision path : Camera JPEG → base64 → Chat Completions vision endpoint
+ *
+ * Protocol reference:
+ *   https://platform.openai.com/docs/guides/realtime-model-capabilities
+ */
+
+#include "openai_client.h"
+#include "settings.h"
+#include "debbie.h"
+#include "esp_log.h"
+#include "esp_websocket_client.h"
+#include "esp_http_client.h"
+#include "cJSON.h"
+#include "mbedtls/base64.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include <string.h>
+#include <stdlib.h>
+
+static const char *TAG = "oai";
+
+/* ── State ─────────────────────────────────────────────────────────────── */
+static esp_websocket_client_handle_t s_ws      = NULL;
+static oai_event_cb_t                s_cb      = NULL;
+static void                         *s_ctx     = NULL;
+static SemaphoreHandle_t             s_mutex   = NULL;
+static bool                          s_connected = false;
+static char                          s_api_key[128];
+static char                          s_current_response_id[64];
+
+/* ── Helpers ─────────────────────────────────────────────────────────────── */
+
+/* Encode int16 PCM → base64 for the Realtime protocol */
+static char *pcm_to_base64(const int16_t *pcm, size_t count, size_t *out_len)
+{
+    size_t raw_bytes = count * sizeof(int16_t);
+    size_t b64_len   = 0;
+    mbedtls_base64_encode(NULL, 0, &b64_len, (uint8_t *)pcm, raw_bytes);
+    char *b64 = malloc(b64_len + 1);
+    if (!b64) return NULL;
+    mbedtls_base64_encode((unsigned char *)b64, b64_len + 1, out_len,
+                          (const uint8_t *)pcm, raw_bytes);
+    b64[*out_len] = '\0';
+    return b64;
+}
+
+/* Decode base64 → int16 PCM */
+static int16_t *base64_to_pcm(const char *b64, size_t *sample_count)
+{
+    size_t b64_len   = strlen(b64);
+    size_t raw_bytes = 0;
+    mbedtls_base64_decode(NULL, 0, &raw_bytes, (const uint8_t *)b64, b64_len);
+    uint8_t *raw = malloc(raw_bytes);
+    if (!raw) return NULL;
+    mbedtls_base64_decode(raw, raw_bytes, &raw_bytes,
+                          (const uint8_t *)b64, b64_len);
+    *sample_count = raw_bytes / sizeof(int16_t);
+    return (int16_t *)raw;
+}
+
+/* -------------------------------------------------------------------------- */
+
+static void send_json(cJSON *root)
+{
+    char *str = cJSON_PrintUnformatted(root);
+    if (str && s_ws && s_connected) {
+        esp_websocket_client_send_text(s_ws, str, strlen(str), portMAX_DELAY);
+    }
+    free(str);
+}
+
+/* ── Session initialisation ──────────────────────────────────────────────── */
+
+static void send_session_update(const char *system_prompt)
+{
+    cJSON *root  = cJSON_CreateObject();
+    cJSON *sess  = cJSON_CreateObject();
+    cJSON *tools = cJSON_CreateArray();
+
+    /* Built-in tools Debbie exposes to the model */
+    cJSON *t_cam  = cJSON_CreateObject();
+    cJSON_AddStringToObject(t_cam, "type", "function");
+    cJSON_AddStringToObject(t_cam, "name", "capture_image");
+    cJSON_AddStringToObject(t_cam, "description",
+        "Capture a photo from the device camera and describe what you see. "
+        "Use when the user asks 'what do you see?', 'look at this', etc.");
+    cJSON_AddItemToObject(t_cam, "parameters",
+        cJSON_CreateObject()); /* no params */
+    cJSON_AddItemToArray(tools, t_cam);
+
+    cJSON *t_notif = cJSON_CreateObject();
+    cJSON_AddStringToObject(t_notif, "type", "function");
+    cJSON_AddStringToObject(t_notif, "name", "read_notifications");
+    cJSON_AddStringToObject(t_notif, "description",
+        "Read any pending WhatsApp, email, or other notifications.");
+    cJSON_AddItemToObject(t_notif, "parameters", cJSON_CreateObject());
+    cJSON_AddItemToArray(tools, t_notif);
+
+    cJSON *t_spot = cJSON_CreateObject();
+    cJSON_AddStringToObject(t_spot, "type", "function");
+    cJSON_AddStringToObject(t_spot, "name", "spotify_control");
+    cJSON_AddStringToObject(t_spot, "description",
+        "Control Spotify playback — play, pause, next, previous, or search.");
+    cJSON *t_spot_params = cJSON_CreateObject();
+    cJSON *t_spot_props  = cJSON_CreateObject();
+    cJSON *t_action      = cJSON_CreateObject();
+    cJSON_AddStringToObject(t_action, "type", "string");
+    cJSON_AddStringToObject(t_action, "description",
+        "One of: play, pause, next, previous, search:<query>, volume:<0-100>");
+    cJSON_AddItemToObject(t_spot_props, "action", t_action);
+    cJSON_AddItemToObject(t_spot_params, "properties", t_spot_props);
+    cJSON *required_arr = cJSON_CreateArray();
+    cJSON_AddItemToArray(required_arr, cJSON_CreateString("action"));
+    cJSON_AddItemToObject(t_spot_params, "required", required_arr);
+    cJSON_AddStringToObject(t_spot_params, "type", "object");
+    cJSON_AddItemToObject(t_spot, "parameters", t_spot_params);
+    cJSON_AddItemToArray(tools, t_spot);
+
+    cJSON *t_mem = cJSON_CreateObject();
+    cJSON_AddStringToObject(t_mem, "type", "function");
+    cJSON_AddStringToObject(t_mem, "name", "save_memory");
+    cJSON_AddStringToObject(t_mem, "description",
+        "Save an important fact or piece of information to long-term memory "
+        "so you can recall it in future conversations. Use when the user shares "
+        "personal details, preferences, or important context (e.g. their name, "
+        "location, interests, schedule, or preferences).");
+    {
+        cJSON *params = cJSON_CreateObject();
+        cJSON *props  = cJSON_CreateObject();
+        cJSON *p_key  = cJSON_CreateObject();
+        cJSON *p_val  = cJSON_CreateObject();
+        cJSON *p_imp  = cJSON_CreateObject();
+        cJSON_AddStringToObject(p_key, "type", "string");
+        cJSON_AddStringToObject(p_key, "description",
+            "Short snake_case identifier for this fact, e.g. user_name, user_location, "
+            "favourite_colour");
+        cJSON_AddStringToObject(p_val, "type", "string");
+        cJSON_AddStringToObject(p_val, "description", "The value to store");
+        cJSON_AddStringToObject(p_imp, "type", "integer");
+        cJSON_AddStringToObject(p_imp, "description",
+            "Importance score 0-10 (10 = critical, 5 = normal)");
+        cJSON_AddItemToObject(props, "key",        p_key);
+        cJSON_AddItemToObject(props, "value",      p_val);
+        cJSON_AddItemToObject(props, "importance", p_imp);
+        cJSON_AddItemToObject(params, "properties", props);
+        cJSON *req_arr = cJSON_CreateArray();
+        cJSON_AddItemToArray(req_arr, cJSON_CreateString("key"));
+        cJSON_AddItemToArray(req_arr, cJSON_CreateString("value"));
+        cJSON_AddItemToObject(params, "required", req_arr);
+        cJSON_AddStringToObject(params, "type", "object");
+        cJSON_AddItemToObject(t_mem, "parameters", params);
+    }
+    cJSON_AddItemToArray(tools, t_mem);
+
+    cJSON_AddStringToObject(root,  "type",  "session.update");
+    cJSON_AddStringToObject(sess,  "modalities", "audio");
+    cJSON_AddStringToObject(sess,  "voice",  "alloy");
+    cJSON_AddStringToObject(sess,  "instructions", system_prompt);
+    cJSON_AddStringToObject(sess,  "input_audio_format",  "pcm16");
+    cJSON_AddStringToObject(sess,  "output_audio_format", "pcm16");
+    cJSON_AddBoolToObject(sess,    "turn_detection", false);  /* manual VAD */
+    cJSON_AddItemToObject(sess,    "tools", tools);
+    cJSON_AddStringToObject(sess,  "tool_choice", "auto");
+    cJSON_AddItemToObject(root,    "session", sess);
+
+    send_json(root);
+    cJSON_Delete(root);
+    ESP_LOGI(TAG, "Session updated with persona + tools");
+}
+
+/* ── WebSocket event handler ─────────────────────────────────────────────── */
+
+static void ws_event_handler(void *handler_args, esp_event_base_t base,
+                             int32_t event_id, void *event_data)
+{
+    esp_websocket_event_data_t *data = (esp_websocket_event_data_t *)event_data;
+
+    switch (event_id) {
+    case WEBSOCKET_EVENT_CONNECTED:
+        s_connected = true;
+        ESP_LOGI(TAG, "WebSocket connected to OpenAI Realtime API");
+        {
+            oai_event_data_t evt = { .type = OAI_EVT_CONNECTED };
+            if (s_cb) s_cb(&evt, s_ctx);
+        }
+        break;
+
+    case WEBSOCKET_EVENT_DISCONNECTED:
+        s_connected = false;
+        ESP_LOGW(TAG, "WebSocket disconnected");
+        {
+            oai_event_data_t evt = { .type = OAI_EVT_DISCONNECTED };
+            if (s_cb) s_cb(&evt, s_ctx);
+        }
+        break;
+
+    case WEBSOCKET_EVENT_DATA: {
+        if (!data->data_ptr || data->data_len == 0) break;
+
+        /* Null-terminate */
+        char *msg = malloc(data->data_len + 1);
+        if (!msg) break;
+        memcpy(msg, data->data_ptr, data->data_len);
+        msg[data->data_len] = '\0';
+
+        cJSON *json = cJSON_Parse(msg);
+        free(msg);
+        if (!json) break;
+
+        cJSON *type_j = cJSON_GetObjectItem(json, "type");
+        if (!type_j || !cJSON_IsString(type_j)) { cJSON_Delete(json); break; }
+        const char *type = type_j->valuestring;
+
+        if (strcmp(type, "session.created") == 0 ||
+            strcmp(type, "session.updated") == 0) {
+            oai_event_data_t evt = { .type = OAI_EVT_SESSION_CREATED };
+            if (s_cb) s_cb(&evt, s_ctx);
+        }
+        else if (strcmp(type, "response.audio.delta") == 0) {
+            cJSON *delta_j = cJSON_GetObjectItem(json, "delta");
+            if (delta_j && cJSON_IsString(delta_j)) {
+                size_t   sample_count = 0;
+                int16_t *pcm = base64_to_pcm(delta_j->valuestring, &sample_count);
+                if (pcm) {
+                    oai_event_data_t evt = {
+                        .type       = OAI_EVT_AUDIO_DELTA,
+                        .audio.pcm  = pcm,
+                        .audio.count = sample_count,
+                    };
+                    if (s_cb) s_cb(&evt, s_ctx);
+                    free(pcm);
+                }
+            }
+        }
+        else if (strcmp(type, "response.audio_transcript.delta") == 0) {
+            cJSON *text_j = cJSON_GetObjectItem(json, "transcript");
+            if (!text_j) text_j = cJSON_GetObjectItem(json, "delta");
+            if (text_j && cJSON_IsString(text_j)) {
+                oai_event_data_t evt = {
+                    .type            = OAI_EVT_TRANSCRIPT,
+                    .transcript.text = text_j->valuestring,
+                };
+                if (s_cb) s_cb(&evt, s_ctx);
+            }
+        }
+        else if (strcmp(type, "conversation.item.input_audio_transcription.completed") == 0) {
+            cJSON *text_j = cJSON_GetObjectItem(json, "transcript");
+            if (text_j && cJSON_IsString(text_j)) {
+                oai_event_data_t evt = {
+                    .type            = OAI_EVT_USER_TRANSCRIPT,
+                    .transcript.text = text_j->valuestring,
+                };
+                if (s_cb) s_cb(&evt, s_ctx);
+            }
+        }
+        else if (strcmp(type, "response.function_call_arguments.done") == 0) {
+            cJSON *name_j = cJSON_GetObjectItem(json, "name");
+            cJSON *args_j = cJSON_GetObjectItem(json, "arguments");
+            cJSON *id_j   = cJSON_GetObjectItem(json, "call_id");
+            if (name_j && cJSON_IsString(name_j) && id_j && cJSON_IsString(id_j)) {
+                s_current_response_id[sizeof(s_current_response_id) - 1] = '\0';
+                strncpy(s_current_response_id, id_j->valuestring,
+                        sizeof(s_current_response_id) - 1);
+                oai_event_data_t evt = {
+                    .type         = OAI_EVT_FUNCTION_CALL,
+                    .fn.name      = name_j->valuestring,
+                    .fn.args_json = args_j ? args_j->valuestring : "{}",
+                    .fn.call_id   = s_current_response_id,
+                };
+                if (s_cb) s_cb(&evt, s_ctx);
+            }
+        }
+        else if (strcmp(type, "error") == 0) {
+            cJSON *err_j = cJSON_GetObjectItem(json, "error");
+            cJSON *msg_j = err_j ? cJSON_GetObjectItem(err_j, "message") : NULL;
+            oai_event_data_t evt = {
+                .type          = OAI_EVT_ERROR,
+                .error.message = msg_j ? msg_j->valuestring : "unknown error",
+            };
+            ESP_LOGE(TAG, "API error: %s", evt.error.message);
+            if (s_cb) s_cb(&evt, s_ctx);
+        }
+
+        cJSON_Delete(json);
+        break;
+    }
+
+    case WEBSOCKET_EVENT_ERROR:
+        ESP_LOGE(TAG, "WebSocket error");
+        break;
+
+    default:
+        break;
+    }
+}
+
+/* ── Public API ──────────────────────────────────────────────────────────── */
+
+esp_err_t openai_client_connect(const char *api_key,
+                                const char *system_prompt,
+                                oai_event_cb_t cb,
+                                void *user_ctx)
+{
+    if (!api_key || strlen(api_key) == 0) {
+        ESP_LOGE(TAG, "No API key provided");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    strncpy(s_api_key, api_key, sizeof(s_api_key) - 1);
+    s_cb  = cb;
+    s_ctx = user_ctx;
+
+    if (!s_mutex) s_mutex = xSemaphoreCreateMutex();
+
+    /*
+     * Build the combined headers string required by the OpenAI Realtime API.
+     * esp_websocket_client_config_t accepts a single multi-line header string.
+     * Format: "Key1: Value1\r\nKey2: Value2\r\n"
+     */
+    char headers[320];
+    snprintf(headers, sizeof(headers),
+             "Authorization: Bearer %s\r\nOpenAI-Beta: realtime=v1\r\n",
+             api_key);
+
+    const esp_websocket_client_config_t ws_cfg = {
+        .uri                    = "wss://" OPENAI_REALTIME_HOST OPENAI_REALTIME_PATH,
+        .headers                = headers,
+        .cert_pem               = NULL,   /* Uses bundled CA certificates */
+        .disable_auto_reconnect = false,
+        .reconnect_timeout_ms   = 5000,
+        .network_timeout_ms     = 10000,
+        .buffer_size            = 8192,
+        .task_stack             = 8192,
+        .task_prio              = configMAX_PRIORITIES - 3,
+    };
+
+    s_ws = esp_websocket_client_init(&ws_cfg);
+    if (!s_ws) {
+        ESP_LOGE(TAG, "Failed to init WebSocket client");
+        return ESP_FAIL;
+    }
+
+    ESP_ERROR_CHECK(esp_websocket_register_events(s_ws, WEBSOCKET_EVENT_ANY,
+                    ws_event_handler, NULL));
+    ESP_ERROR_CHECK(esp_websocket_client_start(s_ws));
+
+    /* Wait for connection up to 10 s */
+    int waited = 0;
+    while (!s_connected && waited < 100) {
+        vTaskDelay(pdMS_TO_TICKS(100));
+        waited++;
+    }
+
+    if (!s_connected) {
+        ESP_LOGE(TAG, "Timed out waiting for WebSocket connection");
+        esp_websocket_client_stop(s_ws);
+        esp_websocket_client_destroy(s_ws);
+        s_ws = NULL;
+        return ESP_FAIL;
+    }
+
+    /* Configure the session */
+    send_session_update(system_prompt ? system_prompt :
+                        "You are Debbie, a helpful and friendly AI companion.");
+    return ESP_OK;
+}
+
+esp_err_t openai_client_disconnect(void)
+{
+    if (s_ws) {
+        esp_websocket_client_stop(s_ws);
+        esp_websocket_client_destroy(s_ws);
+        s_ws = NULL;
+    }
+    s_connected = false;
+    return ESP_OK;
+}
+
+esp_err_t openai_client_send_audio(const int16_t *pcm, size_t count)
+{
+    if (!s_connected || !pcm || count == 0) return ESP_ERR_INVALID_STATE;
+
+    size_t  b64_len = 0;
+    char   *b64     = pcm_to_base64(pcm, count, &b64_len);
+    if (!b64) return ESP_ERR_NO_MEM;
+
+    cJSON *root  = cJSON_CreateObject();
+    cJSON_AddStringToObject(root, "type",  "input_audio_buffer.append");
+    cJSON_AddStringToObject(root, "audio", b64);
+    send_json(root);
+    cJSON_Delete(root);
+    free(b64);
+    return ESP_OK;
+}
+
+esp_err_t openai_client_commit_audio(void)
+{
+    if (!s_connected) return ESP_ERR_INVALID_STATE;
+
+    /* Commit the audio buffer */
+    cJSON *commit = cJSON_CreateObject();
+    cJSON_AddStringToObject(commit, "type", "input_audio_buffer.commit");
+    send_json(commit);
+    cJSON_Delete(commit);
+
+    /* Request a response */
+    cJSON *respond = cJSON_CreateObject();
+    cJSON_AddStringToObject(respond, "type", "response.create");
+    send_json(respond);
+    cJSON_Delete(respond);
+
+    return ESP_OK;
+}
+
+esp_err_t openai_client_send_text(const char *text)
+{
+    if (!s_connected || !text) return ESP_ERR_INVALID_STATE;
+
+    /* Create a conversation item with the user's text */
+    cJSON *root    = cJSON_CreateObject();
+    cJSON *item    = cJSON_CreateObject();
+    cJSON *content = cJSON_CreateArray();
+    cJSON *part    = cJSON_CreateObject();
+
+    cJSON_AddStringToObject(part, "type", "input_text");
+    cJSON_AddStringToObject(part, "text", text);
+    cJSON_AddItemToArray(content, part);
+    cJSON_AddStringToObject(item, "type",    "message");
+    cJSON_AddStringToObject(item, "role",    "user");
+    cJSON_AddItemToObject(item,  "content",  content);
+    cJSON_AddStringToObject(root, "type", "conversation.item.create");
+    cJSON_AddItemToObject(root,   "item", item);
+    send_json(root);
+    cJSON_Delete(root);
+
+    /* Request a response */
+    cJSON *respond = cJSON_CreateObject();
+    cJSON_AddStringToObject(respond, "type", "response.create");
+    send_json(respond);
+    cJSON_Delete(respond);
+
+    return ESP_OK;
+}
+
+esp_err_t openai_client_send_image(const char *jpeg_b64, const char *prompt)
+{
+    if (!jpeg_b64 || !s_api_key[0]) return ESP_ERR_INVALID_ARG;
+
+    /*
+     * Vision via Chat Completions API (gpt-4o).
+     * The Realtime API does not yet support direct image input, so we
+     * make a separate HTTPS request and inject the description back
+     * into the realtime session as a text message.
+     */
+    cJSON *body    = cJSON_CreateObject();
+    cJSON *msgs    = cJSON_CreateArray();
+    cJSON *user_m  = cJSON_CreateObject();
+    cJSON *content = cJSON_CreateArray();
+
+    /* Text part */
+    cJSON *txt_part = cJSON_CreateObject();
+    cJSON_AddStringToObject(txt_part, "type", "text");
+    cJSON_AddStringToObject(txt_part, "text",
+        prompt ? prompt : "Describe what you see in this image in detail.");
+    cJSON_AddItemToArray(content, txt_part);
+
+    /* Image part */
+    cJSON *img_part  = cJSON_CreateObject();
+    cJSON *img_url_o = cJSON_CreateObject();
+    char   data_url[32];
+    snprintf(data_url, sizeof(data_url), "data:image/jpeg;base64,");
+    /* Build full data URL — note: large strings may need heap allocation */
+    char *full_url = malloc(strlen(data_url) + strlen(jpeg_b64) + 1);
+    if (!full_url) { cJSON_Delete(body); return ESP_ERR_NO_MEM; }
+    strcpy(full_url, data_url);
+    strcat(full_url, jpeg_b64);
+    cJSON_AddStringToObject(img_url_o, "url",    full_url);
+    cJSON_AddStringToObject(img_url_o, "detail", "auto");
+    cJSON_AddStringToObject(img_part, "type",      "image_url");
+    cJSON_AddItemToObject(img_part,   "image_url", img_url_o);
+    cJSON_AddItemToArray(content, img_part);
+    free(full_url);
+
+    cJSON_AddStringToObject(user_m, "role", "user");
+    cJSON_AddItemToObject(user_m, "content", content);
+    cJSON_AddItemToArray(msgs, user_m);
+    cJSON_AddStringToObject(body, "model",      OPENAI_VISION_MODEL);
+    cJSON_AddItemToObject(body,   "messages",   msgs);
+    cJSON_AddNumberToObject(body, "max_tokens", 512);
+
+    char *body_str = cJSON_PrintUnformatted(body);
+    cJSON_Delete(body);
+
+    /* HTTPS POST */
+    char auth_hdr[160];
+    snprintf(auth_hdr, sizeof(auth_hdr), "Bearer %s", s_api_key);
+
+    esp_http_client_config_t http_cfg = {
+        .host             = OPENAI_CHAT_HOST,
+        .path             = OPENAI_CHAT_PATH,
+        .transport_type   = HTTP_TRANSPORT_OVER_SSL,
+        .method           = HTTP_METHOD_POST,
+    };
+    esp_http_client_handle_t client = esp_http_client_init(&http_cfg);
+    esp_http_client_set_header(client, "Content-Type",  "application/json");
+    esp_http_client_set_header(client, "Authorization", auth_hdr);
+    esp_http_client_set_post_field(client, body_str, strlen(body_str));
+
+    esp_err_t err = esp_http_client_perform(client);
+    if (err == ESP_OK) {
+        int status = esp_http_client_get_status_code(client);
+        if (status == 200) {
+            int content_len = esp_http_client_get_content_length(client);
+            char *resp_buf  = malloc(content_len + 1);
+            if (resp_buf) {
+                esp_http_client_read_response(client, resp_buf, content_len);
+                resp_buf[content_len] = '\0';
+
+                cJSON *resp = cJSON_Parse(resp_buf);
+                if (resp) {
+                    cJSON *choices  = cJSON_GetObjectItem(resp, "choices");
+                    cJSON *choice0  = cJSON_GetArrayItem(choices, 0);
+                    cJSON *msg      = cJSON_GetObjectItem(choice0, "message");
+                    cJSON *resp_txt = cJSON_GetObjectItem(msg, "content");
+                    if (resp_txt && cJSON_IsString(resp_txt)) {
+                        /* Inject description into realtime conversation */
+                        char desc[1024];
+                        snprintf(desc, sizeof(desc),
+                                 "[Camera sees]: %s", resp_txt->valuestring);
+                        openai_client_send_text(desc);
+                    }
+                    cJSON_Delete(resp);
+                }
+                free(resp_buf);
+            }
+        } else {
+            ESP_LOGW(TAG, "Vision API returned HTTP %d", status);
+        }
+    }
+
+    esp_http_client_cleanup(client);
+    free(body_str);
+    return err;
+}
+
+esp_err_t openai_client_send_function_result(const char *call_id,
+                                             const char *result_json)
+{
+    if (!s_connected) return ESP_ERR_INVALID_STATE;
+
+    cJSON *root    = cJSON_CreateObject();
+    cJSON *item    = cJSON_CreateObject();
+    cJSON_AddStringToObject(root, "type", "conversation.item.create");
+    cJSON_AddStringToObject(item, "type",    "function_call_output");
+    cJSON_AddStringToObject(item, "call_id", call_id);
+    cJSON_AddStringToObject(item, "output",  result_json);
+    cJSON_AddItemToObject(root, "item", item);
+    send_json(root);
+    cJSON_Delete(root);
+
+    /* Ask the model to continue with a response */
+    cJSON *respond = cJSON_CreateObject();
+    cJSON_AddStringToObject(respond, "type", "response.create");
+    send_json(respond);
+    cJSON_Delete(respond);
+
+    return ESP_OK;
+}
+
+bool openai_client_is_connected(void) { return s_connected; }
diff --git a/firmware/main/openai_client.h b/firmware/main/openai_client.h
new file mode 100644
index 0000000..2c3fc1a
--- /dev/null
+++ b/firmware/main/openai_client.h
@@ -0,0 +1,96 @@
+#pragma once
+#include "esp_err.h"
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+/**
+ * @brief  Initialise the OpenAI Realtime (WebSocket) client.
+ *
+ *  - Uses WebSocket to wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview
+ *  - Audio is streamed bidirectionally as PCM16 mono 24 kHz.
+ *  - Callbacks deliver events to the application layer.
+ */
+
+typedef enum {
+    OAI_EVT_CONNECTED    = 0,
+    OAI_EVT_DISCONNECTED,
+    OAI_EVT_AUDIO_DELTA,          /* AI speaking — PCM chunk ready */
+    OAI_EVT_TRANSCRIPT,           /* AI text transcript available */
+    OAI_EVT_USER_TRANSCRIPT,      /* User speech transcript (for memory) */
+    OAI_EVT_FUNCTION_CALL,        /* function/tool call requested by model */
+    OAI_EVT_SESSION_CREATED,
+    OAI_EVT_ERROR,
+} oai_event_t;
+
+typedef struct {
+    oai_event_t type;
+    union {
+        struct { const int16_t *pcm; size_t count; } audio;   /* AUDIO_DELTA */
+        struct { const char *text;                 } transcript;
+        struct {                                               /* FUNCTION_CALL */
+            const char *name;
+            const char *args_json;
+            const char *call_id;  /* Must be passed back to send_function_result */
+        } fn;
+        struct { const char *message;              } error;
+    };
+} oai_event_data_t;
+
+typedef void (*oai_event_cb_t)(const oai_event_data_t *evt, void *user_ctx);
+
+/**
+ * @brief  Connect to OpenAI Realtime API.
+ *
+ * @param api_key     OpenAI API key.
+ * @param system_prompt  Optional persona/system prompt.
+ * @param cb          Event callback invoked from a dedicated task.
+ * @param user_ctx    Passed through to the callback.
+ */
+esp_err_t openai_client_connect(const char *api_key,
+                                const char *system_prompt,
+                                oai_event_cb_t cb,
+                                void *user_ctx);
+
+/**
+ * @brief  Disconnect and clean up.
+ */
+esp_err_t openai_client_disconnect(void);
+
+/**
+ * @brief  Stream a chunk of microphone PCM audio to the API.
+ *         Call this continuously while the user is speaking.
+ */
+esp_err_t openai_client_send_audio(const int16_t *pcm, size_t count);
+
+/**
+ * @brief  Signal end of user speech (triggers model response).
+ */
+esp_err_t openai_client_commit_audio(void);
+
+/**
+ * @brief  Send a text message (alternative to voice).
+ */
+esp_err_t openai_client_send_text(const char *text);
+
+/**
+ * @brief  Send a camera image to the model for visual analysis.
+ *         The image is sent as a vision user message via the Chat API
+ *         (OpenAI Realtime API does not yet support image input directly).
+ *
+ * @param jpeg_b64   Base64-encoded JPEG image.
+ * @param prompt     User prompt to accompany the image.
+ */
+esp_err_t openai_client_send_image(const char *jpeg_b64,
+                                   const char *prompt);
+
+/**
+ * @brief  Return a function-call result so the model can continue.
+ */
+esp_err_t openai_client_send_function_result(const char *call_id,
+                                             const char *result_json);
+
+/**
+ * @brief  Return true if the WebSocket is currently connected.
+ */
+bool openai_client_is_connected(void);
diff --git a/firmware/main/self_agent.c b/firmware/main/self_agent.c
new file mode 100644
index 0000000..470b42e
--- /dev/null
+++ b/firmware/main/self_agent.c
@@ -0,0 +1,597 @@
+/*
+ * self_agent.c — Debbie's Full Agent Capabilities
+ *
+ * Provides Debbie with tools to:
+ *  ✅ Inspect her own hardware and runtime state
+ *  ✅ Query the internet (HTTP GET/POST)
+ *  ✅ Execute all network security scan tools
+ *  ✅ Browse web pages and extract text
+ *  ✅ Perform DNS lookups
+ *  ✅ Look up MAC vendors (OUI)
+ *  ✅ Query the NVD CVE database
+ *  ✅ Generate and serve vulnerability reports
+ *
+ * These capabilities are exposed to the OpenAI model as function tools
+ * and registered at session startup.
+ */
+
+#include "self_agent.h"
+#include "network_scanner.h"
+#include "vuln_reporter.h"
+#include "openai_client.h"
+#include "display_manager.h"
+#include "settings.h"
+#include "debbie.h"
+#include "esp_log.h"
+#include "esp_system.h"
+#include "esp_chip_info.h"
+#include "esp_heap_caps.h"
+#include "esp_wifi.h"
+#include "esp_netif.h"
+#include "esp_idf_version.h"
+#include "esp_http_client.h"
+#include "esp_timer.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "cJSON.h"
+#include "lwip/netdb.h"
+#include "lwip/sockets.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+static const char *TAG = "selfagent";
+
+/* ── Self-introspection ──────────────────────────────────────────────────── */
+
+char *self_agent_get_system_info(void)
+{
+    cJSON *root = cJSON_CreateObject();
+
+    /* Chip info */
+    esp_chip_info_t chip;
+    esp_chip_info(&chip);
+    cJSON_AddStringToObject(root, "chip",     "ESP32-S3");
+    cJSON_AddNumberToObject(root, "cores",    chip.cores);
+    cJSON_AddStringToObject(root, "idf_ver",  esp_get_idf_version());
+    cJSON_AddStringToObject(root, "fw_ver",   DEBBIE_FW_VERSION);
+
+    /* Memory */
+    size_t free_heap   = heap_caps_get_free_size(MALLOC_CAP_DEFAULT);
+    size_t total_heap  = heap_caps_get_total_size(MALLOC_CAP_DEFAULT);
+    size_t free_psram  = heap_caps_get_free_size(MALLOC_CAP_SPIRAM);
+    cJSON_AddNumberToObject(root, "free_heap_bytes",  free_heap);
+    cJSON_AddNumberToObject(root, "total_heap_bytes", total_heap);
+    cJSON_AddNumberToObject(root, "free_psram_bytes", free_psram);
+    cJSON_AddNumberToObject(root, "heap_used_pct",
+        (int)((1.0 - (double)free_heap / total_heap) * 100));
+
+    /* Uptime */
+    uint64_t uptime_s = esp_timer_get_time() / 1000000;
+    char uptime_str[32];
+    snprintf(uptime_str, sizeof(uptime_str), "%llu days %02llu:%02llu:%02llu",
+             uptime_s / 86400,
+             (uptime_s % 86400) / 3600,
+             (uptime_s % 3600) / 60,
+             uptime_s % 60);
+    cJSON_AddStringToObject(root, "uptime", uptime_str);
+
+    /* WiFi info */
+    wifi_ap_record_t ap;
+    if (esp_wifi_sta_get_ap_info(&ap) == ESP_OK) {
+        cJSON_AddStringToObject(root, "wifi_ssid",    (char *)ap.ssid);
+        cJSON_AddNumberToObject(root, "wifi_rssi",    ap.rssi);
+        cJSON_AddNumberToObject(root, "wifi_channel", ap.primary);
+    }
+
+    /* IP info */
+    esp_netif_t *netif = esp_netif_get_handle_from_ifkey("WIFI_STA_DEF");
+    if (netif) {
+        esp_netif_ip_info_t ip_info;
+        if (esp_netif_get_ip_info(netif, &ip_info) == ESP_OK) {
+            char ip_str[16], gw_str[16];
+            snprintf(ip_str, sizeof(ip_str), IPSTR, IP2STR(&ip_info.ip));
+            snprintf(gw_str, sizeof(gw_str), IPSTR, IP2STR(&ip_info.gw));
+            cJSON_AddStringToObject(root, "ip",      ip_str);
+            cJSON_AddStringToObject(root, "gateway", gw_str);
+        }
+    }
+
+    /* Task list (top-level summary) */
+    UBaseType_t task_count = uxTaskGetNumberOfTasks();
+    cJSON_AddNumberToObject(root, "running_tasks", task_count);
+
+    /* Features enabled */
+    cJSON *features = cJSON_CreateObject();
+    cJSON_AddBoolToObject(features, "camera",        g_debbie_config.camera_enabled);
+    cJSON_AddBoolToObject(features, "notifications", g_debbie_config.notifications_enabled);
+    cJSON_AddBoolToObject(features, "network_scan",  true);
+    cJSON_AddBoolToObject(features, "vuln_scanner",  true);
+    cJSON_AddBoolToObject(features, "web_agent",     true);
+    cJSON_AddItemToObject(root, "features", features);
+
+    char *out = cJSON_PrintUnformatted(root);
+    cJSON_Delete(root);
+    return out;
+}
+
+/* ── Internet HTTP fetch ─────────────────────────────────────────────────── */
+
+/* Accumulate HTTP response body */
+typedef struct { char *buf; int len; int cap; } http_resp_t;
+
+static esp_err_t http_body_handler(esp_http_client_event_t *evt)
+{
+    http_resp_t *r = (http_resp_t *)evt->user_data;
+    if (evt->event_id == HTTP_EVENT_ON_DATA && r) {
+        int needed = r->len + evt->data_len + 1;
+        if (needed > r->cap) {
+            int newcap = needed + 1024;
+            char *tmp = realloc(r->buf, newcap);
+            if (!tmp) return ESP_FAIL;
+            r->buf = tmp;
+            r->cap = newcap;
+        }
+        memcpy(r->buf + r->len, evt->data, evt->data_len);
+        r->len += evt->data_len;
+        r->buf[r->len] = '\0';
+    }
+    return ESP_OK;
+}
+
+char *self_agent_http_get(const char *url, int max_bytes)
+{
+    if (!url) return NULL;
+    if (max_bytes <= 0 || max_bytes > 32768) max_bytes = 4096;
+
+    http_resp_t resp = { .buf = malloc(1024), .len = 0, .cap = 1024 };
+    if (!resp.buf) return NULL;
+    resp.buf[0] = '\0';
+
+    esp_http_client_config_t cfg = {
+        .url            = url,
+        .timeout_ms     = 8000,
+        .event_handler  = http_body_handler,
+        .user_data      = &resp,
+        .skip_cert_common_name_check = true,
+    };
+
+    esp_http_client_handle_t cli = esp_http_client_init(&cfg);
+    if (!cli) { free(resp.buf); return NULL; }
+
+    esp_http_client_set_header(cli, "User-Agent",
+        "Mozilla/5.0 Debbie-Agent/1.0 (ESP32-S3)");
+
+    esp_err_t err = esp_http_client_perform(cli);
+    int status    = esp_http_client_get_status_code(cli);
+    esp_http_client_cleanup(cli);
+
+    if (err != ESP_OK || status < 200 || status >= 400) {
+        ESP_LOGW(TAG, "HTTP GET %s returned %d (%s)",
+                 url, status, esp_err_to_name(err));
+        free(resp.buf);
+        return NULL;
+    }
+
+    /* Truncate to max_bytes */
+    if (resp.len > max_bytes) {
+        resp.buf[max_bytes] = '\0';
+    }
+
+    ESP_LOGD(TAG, "HTTP GET %s → %d bytes", url, resp.len);
+    return resp.buf;  /* caller must free */
+}
+
+/* ── DNS lookup ──────────────────────────────────────────────────────────── */
+
+char *self_agent_dns_lookup(const char *hostname)
+{
+    if (!hostname) return NULL;
+    struct hostent *he = gethostbyname(hostname);
+    if (!he || !he->h_addr_list[0]) return strdup("DNS lookup failed");
+
+    cJSON *root = cJSON_CreateObject();
+    cJSON_AddStringToObject(root, "hostname", hostname);
+    cJSON *addrs = cJSON_CreateArray();
+    for (int i = 0; he->h_addr_list[i]; i++) {
+        struct in_addr addr;
+        memcpy(&addr, he->h_addr_list[i], sizeof(addr));
+        cJSON_AddItemToArray(addrs, cJSON_CreateString(inet_ntoa(addr)));
+    }
+    cJSON_AddItemToObject(root, "addresses", addrs);
+    char *out = cJSON_PrintUnformatted(root);
+    cJSON_Delete(root);
+    return out;
+}
+
+/* ── CVE lookup via NVD API (via HTTP) ───────────────────────────────────── */
+
+char *self_agent_cve_lookup(const char *cve_id)
+{
+    if (!cve_id) return NULL;
+    char url[128];
+    snprintf(url, sizeof(url),
+             "https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=%s",
+             cve_id);
+
+    char *body = self_agent_http_get(url, 4096);
+    if (!body) return strdup("{\"error\":\"CVE lookup failed\"}");
+
+    /* Extract summary from NVD JSON */
+    cJSON *json = cJSON_Parse(body);
+    free(body);
+    if (!json) return strdup("{\"error\":\"Parse failed\"}");
+
+    char *out = NULL;
+    cJSON *vulns = cJSON_GetObjectItem(json, "vulnerabilities");
+    cJSON *v0    = cJSON_GetArrayItem(vulns, 0);
+    cJSON *cve   = v0 ? cJSON_GetObjectItem(v0, "cve") : NULL;
+
+    if (cve) {
+        cJSON *result = cJSON_CreateObject();
+        cJSON_AddStringToObject(result, "id", cve_id);
+
+        /* Description */
+        cJSON *descs = cJSON_GetObjectItem(cve, "descriptions");
+        cJSON *d0    = cJSON_GetArrayItem(descs, 0);
+        cJSON *value = d0 ? cJSON_GetObjectItem(d0, "value") : NULL;
+        if (value && cJSON_IsString(value))
+            cJSON_AddStringToObject(result, "description", value->valuestring);
+
+        /* CVSS score */
+        cJSON *metrics   = cJSON_GetObjectItem(cve, "metrics");
+        cJSON *cvss31arr = cJSON_GetObjectItem(metrics, "cvssMetricV31");
+        cJSON *cvss31_0  = cJSON_GetArrayItem(cvss31arr, 0);
+        cJSON *cvssdata  = cvss31_0 ? cJSON_GetObjectItem(cvss31_0, "cvssData") : NULL;
+        if (cvssdata) {
+            cJSON *score    = cJSON_GetObjectItem(cvssdata, "baseScore");
+            cJSON *severity = cJSON_GetObjectItem(cvssdata, "baseSeverity");
+            if (score)    cJSON_AddNumberToObject(result, "cvss_score", score->valuedouble);
+            if (severity) cJSON_AddStringToObject(result, "severity", severity->valuestring);
+        }
+
+        out = cJSON_PrintUnformatted(result);
+        cJSON_Delete(result);
+    } else {
+        out = strdup("{\"error\":\"CVE not found\"}");
+    }
+
+    cJSON_Delete(json);
+    return out;
+}
+
+/* ── Register all agent tools with OpenAI ────────────────────────────────── */
+
+/*
+ * Additional tool definitions injected into the OpenAI session.
+ * These supplement the tools defined in openai_client.c.
+ */
+const char *AGENT_TOOLS_JSON =
+"["
+/* network_scan */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"network_scan\","
+"  \"description\":\"Scan the local WiFi network. Discovers all connected devices, "
+"    open ports, services, and security vulnerabilities. "
+"    IMPORTANT: Only use on networks you own or have explicit authorisation to test. "
+"    Specify scope: 'wifi' for AP scan only, 'hosts' for device discovery, "
+"    'ports' for port scan on a specific IP, 'full' for complete scan.\","
+"  \"parameters\":{"
+"    \"type\":\"object\","
+"    \"properties\":{"
+"      \"scope\":{\"type\":\"string\","
+"        \"description\":\"One of: wifi, hosts, ports, full\"},"
+"      \"target_ip\":{\"type\":\"string\","
+"        \"description\":\"IP address for ports scope (e.g. 192.168.1.1)\"}"
+"    },"
+"    \"required\":[\"scope\"]"
+"  }"
+"},"
+/* get_vuln_report */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"get_vuln_report\","
+"  \"description\":\"Get the vulnerability assessment report from the last network scan. "
+"    Returns a summary of security findings, risk scores, and remediation steps.\","
+"  \"parameters\":{\"type\":\"object\",\"properties\":{}}"
+"},"
+/* system_info */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"system_info\","
+"  \"description\":\"Get Debbie's own hardware and runtime information: "
+"    CPU, memory usage, WiFi signal, uptime, enabled features.\","
+"  \"parameters\":{\"type\":\"object\",\"properties\":{}}"
+"},"
+/* web_fetch */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"web_fetch\","
+"  \"description\":\"Fetch a URL from the internet and return the page content. "
+"    Use for looking up information, checking websites, getting news, weather, etc.\","
+"  \"parameters\":{"
+"    \"type\":\"object\","
+"    \"properties\":{"
+"      \"url\":{\"type\":\"string\",\"description\":\"The full URL to fetch\"},"
+"      \"max_bytes\":{\"type\":\"number\","
+"        \"description\":\"Maximum response size in bytes (default 2048)\"}"
+"    },"
+"    \"required\":[\"url\"]"
+"  }"
+"},"
+/* dns_lookup */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"dns_lookup\","
+"  \"description\":\"Resolve a hostname to IP addresses.\","
+"  \"parameters\":{"
+"    \"type\":\"object\","
+"    \"properties\":{"
+"      \"hostname\":{\"type\":\"string\",\"description\":\"The hostname to resolve\"}"
+"    },"
+"    \"required\":[\"hostname\"]"
+"  }"
+"},"
+/* cve_lookup */
+"{"
+"  \"type\":\"function\","
+"  \"name\":\"cve_lookup\","
+"  \"description\":\"Look up details about a specific CVE (Common Vulnerability and Exposure) "
+"    from the NVD database. Returns description, CVSS score, and severity.\","
+"  \"parameters\":{"
+"    \"type\":\"object\","
+"    \"properties\":{"
+"      \"cve_id\":{\"type\":\"string\","
+"        \"description\":\"CVE identifier, e.g. CVE-2021-44228\"}"
+"    },"
+"    \"required\":[\"cve_id\"]"
+"  }"
+"}"
+"]";
+
+/* ── Handle agent function calls ─────────────────────────────────────────── */
+
+/* Forward declaration */
+extern void display_manager_show_text(const char *text);
+extern volatile debbie_state_t g_debbie_state;
+extern debbie_config_t g_debbie_config;
+
+typedef struct {
+    char call_id[64];
+    char fn_name[64];
+    char args_json[256];
+} fn_call_task_args_t;
+
+/* Scan progress → display */
+static void scan_progress_display(uint8_t pct, const char *stage, void *ctx)
+{
+    char buf[128];
+    snprintf(buf, sizeof(buf), "🔍 %s\n%d%%", stage ? stage : "Scanning...", pct);
+    display_manager_show_text(buf);
+}
+
+/* Scan done → AI callback */
+typedef struct {
+    char call_id[64];
+} scan_done_ctx_t;
+
+static void on_scan_done(const scan_results_t *results, void *ctx)
+{
+    scan_done_ctx_t *sdc = (scan_done_ctx_t *)ctx;
+
+    /* Analyse vulnerabilities */
+    vuln_report_t report = { 0 };
+    vuln_reporter_analyse(results, &report);
+
+    /* Build compact JSON result */
+    cJSON *result = cJSON_CreateObject();
+    cJSON_AddNumberToObject(result, "hosts_found",    results->host_count);
+    cJSON_AddNumberToObject(result, "wifi_aps",       results->ap_count);
+    cJSON_AddNumberToObject(result, "vulnerabilities",report.count);
+    cJSON_AddNumberToObject(result, "critical",       report.critical_count);
+    cJSON_AddNumberToObject(result, "high",           report.high_count);
+    cJSON_AddStringToObject(result, "own_ip",         results->own_ip);
+    cJSON_AddStringToObject(result, "gateway_ip",     results->gateway_ip);
+
+    /* Include per-host summary */
+    cJSON *hosts = cJSON_CreateArray();
+    for (int i = 0; i < results->host_count; i++) {
+        const host_result_t *h = &results->hosts[i];
+        cJSON *hobj = cJSON_CreateObject();
+        cJSON_AddStringToObject(hobj, "ip",         h->ip_str);
+        cJSON_AddStringToObject(hobj, "vendor",     h->vendor);
+        cJSON_AddNumberToObject(hobj, "open_ports", h->port_count);
+        cJSON_AddNumberToObject(hobj, "risk_score", h->risk_score);
+        if (h->risk_summary[0])
+            cJSON_AddStringToObject(hobj, "issues", h->risk_summary);
+        cJSON_AddItemToArray(hosts, hobj);
+    }
+    cJSON_AddItemToObject(result, "hosts", hosts);
+
+    char *result_str = cJSON_PrintUnformatted(result);
+    cJSON_Delete(result);
+
+    if (result_str) {
+        openai_client_send_function_result(sdc->call_id, result_str);
+        free(result_str);
+    }
+
+    /* Update display with summary */
+    char *voice_summary = vuln_reporter_get_voice_summary(&report);
+    if (voice_summary) {
+        display_manager_show_text(voice_summary);
+        free(voice_summary);
+    }
+
+    free(sdc);
+}
+
+bool self_agent_handle_function_call(const char *fn_name,
+                                     const char *args_json,
+                                     const char *call_id)
+{
+    if (!fn_name || !call_id) return false;
+
+    cJSON *args = args_json ? cJSON_Parse(args_json) : cJSON_CreateObject();
+
+    /* ── system_info ── */
+    if (strcmp(fn_name, "system_info") == 0) {
+        char *info = self_agent_get_system_info();
+        openai_client_send_function_result(call_id, info ? info : "{}");
+        free(info);
+        cJSON_Delete(args);
+        return true;
+    }
+
+    /* ── web_fetch ── */
+    if (strcmp(fn_name, "web_fetch") == 0) {
+        cJSON *url_j     = cJSON_GetObjectItem(args, "url");
+        cJSON *maxbytes_j = cJSON_GetObjectItem(args, "max_bytes");
+        int max_bytes    = maxbytes_j ? (int)maxbytes_j->valuedouble : 2048;
+
+        if (url_j && cJSON_IsString(url_j)) {
+            display_manager_show_text("🌐 Fetching URL...");
+            char *body = self_agent_http_get(url_j->valuestring, max_bytes);
+            if (body) {
+                /* Wrap in JSON result */
+                cJSON *res = cJSON_CreateObject();
+                cJSON_AddStringToObject(res, "url",     url_j->valuestring);
+                cJSON_AddStringToObject(res, "content", body);
+                cJSON_AddNumberToObject(res, "bytes",   strlen(body));
+                char *out = cJSON_PrintUnformatted(res);
+                cJSON_Delete(res);
+                free(body);
+                openai_client_send_function_result(call_id, out ? out : "{}");
+                free(out);
+            } else {
+                openai_client_send_function_result(call_id,
+                    "{\"error\":\"Fetch failed or no content\"}");
+            }
+        } else {
+            openai_client_send_function_result(call_id,
+                "{\"error\":\"URL parameter required\"}");
+        }
+        cJSON_Delete(args);
+        return true;
+    }
+
+    /* ── dns_lookup ── */
+    if (strcmp(fn_name, "dns_lookup") == 0) {
+        cJSON *host_j = cJSON_GetObjectItem(args, "hostname");
+        if (host_j && cJSON_IsString(host_j)) {
+            char *result = self_agent_dns_lookup(host_j->valuestring);
+            openai_client_send_function_result(call_id,
+                result ? result : "{\"error\":\"lookup failed\"}");
+            free(result);
+        } else {
+            openai_client_send_function_result(call_id,
+                "{\"error\":\"hostname required\"}");
+        }
+        cJSON_Delete(args);
+        return true;
+    }
+
+    /* ── cve_lookup ── */
+    if (strcmp(fn_name, "cve_lookup") == 0) {
+        cJSON *cve_j = cJSON_GetObjectItem(args, "cve_id");
+        if (cve_j && cJSON_IsString(cve_j)) {
+            display_manager_show_text("🔍 Looking up CVE...");
+            char *result = self_agent_cve_lookup(cve_j->valuestring);
+            openai_client_send_function_result(call_id,
+                result ? result : "{\"error\":\"lookup failed\"}");
+            free(result);
+        } else {
+            openai_client_send_function_result(call_id,
+                "{\"error\":\"cve_id required\"}");
+        }
+        cJSON_Delete(args);
+        return true;
+    }
+
+    /* ── network_scan ── */
+    if (strcmp(fn_name, "network_scan") == 0) {
+        cJSON *scope_j  = cJSON_GetObjectItem(args, "scope");
+        cJSON *target_j = cJSON_GetObjectItem(args, "target_ip");
+        const char *scope = scope_j && cJSON_IsString(scope_j)
+                            ? scope_j->valuestring : "full";
+
+        display_manager_show_text(
+            "🔍 Network scan starting...\n"
+            "⚠️ Authorised use only!\n"
+            "Scanning...");
+
+        if (strcmp(scope, "wifi") == 0) {
+            net_scanner_wifi_scan(scan_progress_display, NULL);
+            char *json = net_scanner_results_to_json(false);
+            openai_client_send_function_result(call_id, json ? json : "{}");
+            free(json);
+        }
+        else if (strcmp(scope, "hosts") == 0) {
+            net_scanner_arp_scan(scan_progress_display, NULL, NULL);
+            char *json = net_scanner_results_to_json(false);
+            openai_client_send_function_result(call_id, json ? json : "{}");
+            free(json);
+        }
+        else if (strcmp(scope, "ports") == 0 &&
+                 target_j && cJSON_IsString(target_j)) {
+            const scan_results_t *prev = net_scanner_get_results();
+            /* Find existing host entry or create temporary one */
+            host_result_t *host = NULL;
+            for (int i = 0; i < prev->host_count; i++) {
+                if (strcmp(prev->hosts[i].ip_str, target_j->valuestring) == 0) {
+                    host = (host_result_t *)&prev->hosts[i];
+                    break;
+                }
+            }
+            host_result_t tmp_host = { 0 };
+            if (!host) {
+                strncpy(tmp_host.ip_str, target_j->valuestring,
+                        sizeof(tmp_host.ip_str)-1);
+                host = &tmp_host;
+            }
+            net_scanner_port_scan(target_j->valuestring, host,
+                                  scan_progress_display, NULL);
+            vuln_report_t report = { 0 };
+            scan_results_t tmp_scan = { 0 };
+            tmp_scan.host_count = 1;
+            tmp_scan.hosts[0]   = *host;
+            vuln_reporter_analyse(&tmp_scan, &report);
+            char *vuln_json = vuln_reporter_to_json(&report);
+            openai_client_send_function_result(call_id,
+                vuln_json ? vuln_json : "{}");
+            free(vuln_json);
+        }
+        else {
+            /* Full scan — async */
+            scan_done_ctx_t *sdc = malloc(sizeof(scan_done_ctx_t));
+            if (sdc) {
+                strncpy(sdc->call_id, call_id, sizeof(sdc->call_id)-1);
+                net_scanner_full_scan(scan_progress_display, on_scan_done, sdc);
+                /* Result sent asynchronously from on_scan_done */
+            }
+        }
+        cJSON_Delete(args);
+        return true;
+    }
+
+    /* ── get_vuln_report ── */
+    if (strcmp(fn_name, "get_vuln_report") == 0) {
+        const scan_results_t *results = net_scanner_get_results();
+        if (results->host_count == 0) {
+            openai_client_send_function_result(call_id,
+                "{\"error\":\"No scan results available. Run network_scan first.\"}");
+        } else {
+            vuln_report_t report = { 0 };
+            vuln_reporter_analyse(results, &report);
+            char *json = vuln_reporter_to_json(&report);
+            openai_client_send_function_result(call_id, json ? json : "{}");
+            free(json);
+        }
+        cJSON_Delete(args);
+        return true;
+    }
+
+    cJSON_Delete(args);
+    return false;  /* Not handled by self_agent */
+}
diff --git a/firmware/main/self_agent.h b/firmware/main/self_agent.h
new file mode 100644
index 0000000..9a9e2bb
--- /dev/null
+++ b/firmware/main/self_agent.h
@@ -0,0 +1,61 @@
+#pragma once
+/*
+ * self_agent.h — Debbie's Full Agent Capabilities
+ *
+ * ✅ Self-introspection (hardware, memory, WiFi, uptime)
+ * ✅ Internet access (HTTP GET/POST)
+ * ✅ DNS lookups
+ * ✅ CVE database queries (NVD API)
+ * ✅ Network security scanning tools
+ * ✅ Vulnerability reporting
+ * ✅ OpenAI function-call dispatcher
+ */
+
+#include "esp_err.h"
+#include <stdbool.h>
+
+/**
+ * @brief  Get a JSON string with Debbie's hardware and runtime status.
+ *         Includes CPU, memory, WiFi, uptime, enabled features.
+ *         Caller must free() the returned pointer.
+ */
+char *self_agent_get_system_info(void);
+
+/**
+ * @brief  Fetch a URL and return the response body.
+ *         Caller must free() the returned pointer.
+ *
+ * @param url       Full URL (http:// or https://)
+ * @param max_bytes Maximum bytes to return (0 = default 4096)
+ */
+char *self_agent_http_get(const char *url, int max_bytes);
+
+/**
+ * @brief  Resolve a hostname to IP addresses.
+ *         Returns a JSON string. Caller must free().
+ */
+char *self_agent_dns_lookup(const char *hostname);
+
+/**
+ * @brief  Look up a CVE in the NVD database.
+ *         Returns a JSON string with description and CVSS score.
+ *         Caller must free().
+ */
+char *self_agent_cve_lookup(const char *cve_id);
+
+/**
+ * @brief  Handle a function call dispatched by the AI model.
+ *         Handles: system_info, web_fetch, dns_lookup, cve_lookup,
+ *                  network_scan, get_vuln_report.
+ *
+ * @return true if the function was handled, false if unknown.
+ */
+bool self_agent_handle_function_call(const char *fn_name,
+                                     const char *args_json,
+                                     const char *call_id);
+
+/**
+ * @brief  JSON array string of additional tool definitions to register
+ *         with the OpenAI session (network_scan, web_fetch, dns_lookup, etc.)
+ */
+extern const char *AGENT_TOOLS_JSON;
diff --git a/firmware/main/settings.h b/firmware/main/settings.h
new file mode 100644
index 0000000..6eec855
--- /dev/null
+++ b/firmware/main/settings.h
@@ -0,0 +1,162 @@
+#pragma once
+#include "debbie.h"  /* for LLM_PROVIDER_* defines */
+
+/* =============================================================================
+ * Debbie — Portable Personal AI Friend
+ * Freenove Media Kit ESP32-S3 (FNK0102) — Hardware Pin Definitions
+ * =============================================================================
+ *
+ * Change DEBBIE_DISPLAY_SIZE to match your kit variant:
+ *   DEBBIE_DISPLAY_35 → 3.5" 480×320 (ST7796) — recommended
+ *   DEBBIE_DISPLAY_114 → 1.14" 135×240 (ST7789)
+ */
+
+/* ── Display variant ──────────────────────────────────────────────────────── */
+#define DEBBIE_DISPLAY_35   1   /* set to 0 to use 1.14" version */
+#define DEBBIE_DISPLAY_114  0
+
+/* ── SPI Display (ST7796 / ST7789) ─────────────────────────────────────────*/
+#define LCD_SPI_HOST        SPI2_HOST
+#define LCD_PIN_MOSI        35
+#define LCD_PIN_CLK         36
+#define LCD_PIN_CS          34
+#define LCD_PIN_DC          37
+#define LCD_PIN_RST         38
+#define LCD_PIN_BL          33
+#define LCD_SPI_FREQ_HZ     (40 * 1000 * 1000)
+
+#if DEBBIE_DISPLAY_35
+#   define LCD_WIDTH        480
+#   define LCD_HEIGHT       320
+#   define LCD_DRIVER       "ST7796"
+#else
+#   define LCD_WIDTH        240
+#   define LCD_HEIGHT       135
+#   define LCD_DRIVER       "ST7789"
+#endif
+
+/* ── Camera (OV2640) ────────────────────────────────────────────────────── */
+#define CAM_PIN_PWDN        -1
+#define CAM_PIN_RESET       -1
+#define CAM_PIN_XCLK        10
+#define CAM_PIN_SIOD        21
+#define CAM_PIN_SIOC        22
+#define CAM_PIN_D7          9
+#define CAM_PIN_D6          8
+#define CAM_PIN_D5          47
+#define CAM_PIN_D4          7
+#define CAM_PIN_D3          6
+#define CAM_PIN_D2          5
+#define CAM_PIN_D1          4
+#define CAM_PIN_D0          3
+#define CAM_PIN_VSYNC       2
+#define CAM_PIN_HREF        1
+#define CAM_PIN_PCLK        0
+
+/* ── I2S Microphone (MEMS, e.g. MSM261S4030H0) ─────────────────────────── */
+#define I2S_MIC_PORT        I2S_NUM_0
+#define I2S_MIC_SCK         14    /* bit clock */
+#define I2S_MIC_WS          13    /* word select / LRCK */
+#define I2S_MIC_SD          12    /* serial data in */
+
+/* ── I2S Speaker (I2S DAC, e.g. MAX98357) ──────────────────────────────── */
+#define I2S_SPK_PORT        I2S_NUM_1
+#define I2S_SPK_BCK         17    /* bit clock */
+#define I2S_SPK_LRCK        16    /* word select */
+#define I2S_SPK_DATA        15    /* serial data out */
+#define I2S_SPK_SD_EN       -1    /* shutdown pin (optional) */
+
+/* ── Audio parameters ───────────────────────────────────────────────────── */
+#define AUDIO_SAMPLE_RATE   24000 /* Hz — matches OpenAI Realtime API */
+#define AUDIO_BITS          16
+#define AUDIO_CHANNELS      1
+#define AUDIO_BUF_MS        60    /* ms per audio chunk */
+
+/* ── WS2812 RGB LED ─────────────────────────────────────────────────────── */
+#define RGB_LED_PIN         40
+#define RGB_LED_COUNT       1
+
+/* ── 5-way navigation switch ────────────────────────────────────────────── */
+#define NAV_UP              41
+#define NAV_DOWN            42
+#define NAV_LEFT            43
+#define NAV_RIGHT           44
+#define NAV_CENTER          45    /* press to capture image / confirm */
+
+/* ── Battery ADC ────────────────────────────────────────────────────────── */
+#define BAT_ADC_PIN         4     /* ADC1_CH3 — check your board variant */
+#define BAT_DIVIDER_RATIO   2.0f  /* voltage divider (R1=R2) */
+
+/* ── SD Card (SPI) ──────────────────────────────────────────────────────── */
+#define SD_PIN_CLK          36    /* shared SPI bus */
+#define SD_PIN_MOSI         35
+#define SD_PIN_MISO         39
+#define SD_PIN_CS           46
+
+/* ── Connectivity defaults ──────────────────────────────────────────────── */
+#define DEBBIE_AP_SSID      "Debbie"
+#define DEBBIE_AP_PASSWORD  ""    /* open network for first-run setup */
+#define DEBBIE_AP_IP        "192.168.4.1"
+
+/* ── Bluetooth defaults ─────────────────────────────────────────────────── */
+#define DEBBIE_BLE_DEVICE_NAME  "Debbie"
+#define DEBBIE_BLE_DEFAULT_ON   true
+
+/* ── OpenAI ─────────────────────────────────────────────────────────────── */
+#define OPENAI_REALTIME_HOST   "api.openai.com"
+#define OPENAI_REALTIME_PATH   "/v1/realtime?model=gpt-4o-realtime-preview"
+#define OPENAI_CHAT_HOST       "api.openai.com"
+#define OPENAI_CHAT_PATH       "/v1/chat/completions"
+#define OPENAI_VISION_MODEL    "gpt-4o"
+
+/* ── Local LLM defaults (Ollama / LM Studio) ───────────────────────────── */
+#define LOCAL_LLM_DEFAULT_URL   "http://192.168.1.100:11434"
+#define LOCAL_LLM_DEFAULT_MODEL "llama3"
+
+/* ── Agent / companion server defaults ──────────────────────────────────── */
+#define AGENT_WS_DEFAULT_URL   "ws://YOUR_COMPANION_SERVER:3001"
+
+/* ── LLM provider & model defaults ─────────────────────────────────────── */
+#define DEFAULT_LLM_PROVIDER    LLM_PROVIDER_OPENAI
+#define DEFAULT_LLM_MODEL       "gpt-4o"
+
+/* ── Personality defaults ────────────────────────────────────────────────── */
+#define DEFAULT_VOICE_STYLE     "friendly"
+#define DEFAULT_RESPONSE_LENGTH "normal"
+#define DEFAULT_VAD_THRESHOLD   300
+
+/* ── Memory & RAG defaults ──────────────────────────────────────────────── */
+#define MEMORY_ENABLED_DEFAULT      true
+#define MEMORY_RAG_ENABLED_DEFAULT  true
+#define MEMORY_MAX_TURNS_DEFAULT    20
+
+/* ── Spotify (handled by companion server) ──────────────────────────────── */
+/* The device sends commands to the companion server which calls Spotify API */
+
+/* ── NVS namespace ──────────────────────────────────────────────────────── */
+#define NVS_NAMESPACE          "debbie"
+
+/* ── LVGL tick rate ─────────────────────────────────────────────────────── */
+#define LVGL_TICK_MS           5
+
+/* ── Default system prompt (includes network security capabilities) ───────── */
+#define DEBBIE_DEFAULT_SYSTEM_PROMPT \
+    "You are Debbie, a warm and knowledgeable AI companion running on a " \
+    "portable ESP32-S3 device. You have a friendly, upbeat personality " \
+    "and love helping with anything — from daily chat to network security.\n\n" \
+    "Your capabilities include:\n" \
+    "• Voice conversations (just talk to me!)\n" \
+    "• Camera vision — ask me to look at something\n" \
+    "• Reading WhatsApp messages and emails\n" \
+    "• Controlling Spotify music playback\n" \
+    "• Fetching information from the internet\n" \
+    "• Network security scanning (say 'scan my network')\n" \
+    "  - Discovering all devices on the local network\n" \
+    "  - Checking for open ports and vulnerabilities\n" \
+    "  - Looking up CVE security advisories\n" \
+    "  - Generating security reports\n\n" \
+    "IMPORTANT SECURITY ETHICS: Only ever scan networks you own or have " \
+    "explicit written permission to test. Always remind the user of this " \
+    "when they ask for network scanning. Never assist with illegal activity.\n\n" \
+    "Speak naturally and concisely. For security findings, explain them " \
+    "clearly in plain English with practical remediation steps."
diff --git a/firmware/main/storage_manager.c b/firmware/main/storage_manager.c
new file mode 100644
index 0000000..7a1b9c6
--- /dev/null
+++ b/firmware/main/storage_manager.c
@@ -0,0 +1,189 @@
+#include "storage_manager.h"
+#include "debbie.h"
+#include "settings.h"
+
+#include "nvs_flash.h"
+#include "nvs.h"
+#include "esp_log.h"
+#include <string.h>
+
+static const char *TAG = "storage";
+
+/* -------------------------------------------------------------------------- */
+
+esp_err_t storage_init(void)
+{
+    esp_err_t err = nvs_flash_init();
+    if (err == ESP_ERR_NVS_NO_FREE_PAGES ||
+        err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_LOGW(TAG, "NVS partition truncated — erasing…");
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        err = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(err);
+
+    /* populate defaults */
+    memset(&g_debbie_config, 0, sizeof(g_debbie_config));
+    strncpy(g_debbie_config.debbie_name, "Debbie", sizeof(g_debbie_config.debbie_name) - 1);
+    strncpy(g_debbie_config.system_prompt,
+            DEBBIE_DEFAULT_SYSTEM_PROMPT,
+            sizeof(g_debbie_config.system_prompt) - 1);
+    g_debbie_config.speaker_volume         = 75;
+    g_debbie_config.notifications_enabled  = true;
+    g_debbie_config.notif_whatsapp         = true;
+    g_debbie_config.notif_email            = true;
+    g_debbie_config.notif_spotify          = true;
+    g_debbie_config.camera_enabled         = true;
+    g_debbie_config.use_custom_agent       = false;
+    g_debbie_config.bluetooth_enabled      = DEBBIE_BLE_DEFAULT_ON;
+    g_debbie_config.vad_threshold          = DEFAULT_VAD_THRESHOLD;
+    strncpy(g_debbie_config.agent_ws_url, AGENT_WS_DEFAULT_URL,
+            sizeof(g_debbie_config.agent_ws_url) - 1);
+    strncpy(g_debbie_config.ble_device_name, DEBBIE_BLE_DEVICE_NAME,
+            sizeof(g_debbie_config.ble_device_name) - 1);
+    strncpy(g_debbie_config.llm_provider, DEFAULT_LLM_PROVIDER,
+            sizeof(g_debbie_config.llm_provider) - 1);
+    strncpy(g_debbie_config.llm_model, DEFAULT_LLM_MODEL,
+            sizeof(g_debbie_config.llm_model) - 1);
+    strncpy(g_debbie_config.local_llm_url, LOCAL_LLM_DEFAULT_URL,
+            sizeof(g_debbie_config.local_llm_url) - 1);
+    strncpy(g_debbie_config.local_llm_model, LOCAL_LLM_DEFAULT_MODEL,
+            sizeof(g_debbie_config.local_llm_model) - 1);
+    g_debbie_config.memory_enabled      = MEMORY_ENABLED_DEFAULT;
+    g_debbie_config.memory_rag_enabled  = MEMORY_RAG_ENABLED_DEFAULT;
+    g_debbie_config.memory_max_turns    = MEMORY_MAX_TURNS_DEFAULT;
+    strncpy(g_debbie_config.voice_style, DEFAULT_VOICE_STYLE,
+            sizeof(g_debbie_config.voice_style) - 1);
+    strncpy(g_debbie_config.response_length, DEFAULT_RESPONSE_LENGTH,
+            sizeof(g_debbie_config.response_length) - 1);
+
+    /* try to load from NVS */
+    nvs_handle_t nvs;
+    err = nvs_open(NVS_NAMESPACE, NVS_READONLY, &nvs);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
+        ESP_LOGI(TAG, "No saved config — using defaults");
+        return ESP_OK;
+    }
+    ESP_ERROR_CHECK(err);
+
+#define NVS_GET_STR(key, dst) do {                                      \
+        size_t _len = sizeof(dst);                                      \
+        nvs_get_str(nvs, key, dst, &_len);                              \
+    } while (0)
+#define NVS_GET_U8(key, dst) nvs_get_u8(nvs, key, &(dst))
+
+    NVS_GET_STR("wifi_ssid",     g_debbie_config.wifi_ssid);
+    NVS_GET_STR("wifi_pass",     g_debbie_config.wifi_password);
+    NVS_GET_STR("wifi_ssid2",    g_debbie_config.wifi_ssid2);
+    NVS_GET_STR("wifi_pass2",    g_debbie_config.wifi_password2);
+    NVS_GET_STR("wifi_ssid3",    g_debbie_config.wifi_ssid3);
+    NVS_GET_STR("wifi_pass3",    g_debbie_config.wifi_password3);
+    NVS_GET_STR("oai_key",       g_debbie_config.openai_api_key);
+    NVS_GET_STR("anthropic_key", g_debbie_config.anthropic_api_key);
+    NVS_GET_STR("groq_key",      g_debbie_config.groq_api_key);
+    NVS_GET_STR("or_key",        g_debbie_config.openrouter_api_key);
+    NVS_GET_STR("llm_provider",  g_debbie_config.llm_provider);
+    NVS_GET_STR("llm_model",     g_debbie_config.llm_model);
+    NVS_GET_STR("local_llm_url", g_debbie_config.local_llm_url);
+    NVS_GET_STR("local_llm_mdl", g_debbie_config.local_llm_model);
+    NVS_GET_STR("agent_url",     g_debbie_config.agent_ws_url);
+    NVS_GET_STR("companion_url", g_debbie_config.companion_url);
+    NVS_GET_STR("name",          g_debbie_config.debbie_name);
+    NVS_GET_STR("sys_prompt",    g_debbie_config.system_prompt);
+    NVS_GET_STR("voice_style",   g_debbie_config.voice_style);
+    NVS_GET_STR("resp_len",      g_debbie_config.response_length);
+    NVS_GET_STR("ble_name",      g_debbie_config.ble_device_name);
+    NVS_GET_STR("spotify_tok",   g_debbie_config.spotify_token);
+    NVS_GET_U8("volume",         g_debbie_config.speaker_volume);
+
+    uint8_t tmp;
+    if (nvs_get_u8(nvs, "use_agent",  &tmp) == ESP_OK)
+        g_debbie_config.use_custom_agent = (tmp != 0);
+    if (nvs_get_u8(nvs, "notifs_en",  &tmp) == ESP_OK)
+        g_debbie_config.notifications_enabled = (tmp != 0);
+    if (nvs_get_u8(nvs, "notif_wa",   &tmp) == ESP_OK)
+        g_debbie_config.notif_whatsapp = (tmp != 0);
+    if (nvs_get_u8(nvs, "notif_em",   &tmp) == ESP_OK)
+        g_debbie_config.notif_email = (tmp != 0);
+    if (nvs_get_u8(nvs, "notif_sp",   &tmp) == ESP_OK)
+        g_debbie_config.notif_spotify = (tmp != 0);
+    if (nvs_get_u8(nvs, "cam_en",     &tmp) == ESP_OK)
+        g_debbie_config.camera_enabled = (tmp != 0);
+    if (nvs_get_u8(nvs, "bt_en",      &tmp) == ESP_OK)
+        g_debbie_config.bluetooth_enabled = (tmp != 0);
+
+    if (nvs_get_u8(nvs, "mem_en",     &tmp) == ESP_OK)
+        g_debbie_config.memory_enabled = (tmp != 0);
+    if (nvs_get_u8(nvs, "mem_rag",    &tmp) == ESP_OK)
+        g_debbie_config.memory_rag_enabled = (tmp != 0);
+    if (nvs_get_u8(nvs, "mem_turns",  &tmp) == ESP_OK)
+        g_debbie_config.memory_max_turns = tmp ? tmp : MEMORY_MAX_TURNS_DEFAULT;
+
+    uint16_t vad;
+    if (nvs_get_u16(nvs, "vad_thresh", &vad) == ESP_OK)
+        g_debbie_config.vad_threshold = vad;
+
+    nvs_close(nvs);
+    ESP_LOGI(TAG, "Config loaded — WiFi SSID: %s", g_debbie_config.wifi_ssid);
+    return ESP_OK;
+}
+
+esp_err_t storage_save_config(void)
+{
+    nvs_handle_t nvs;
+    ESP_ERROR_CHECK(nvs_open(NVS_NAMESPACE, NVS_READWRITE, &nvs));
+
+#define NVS_SET_STR(key, src) nvs_set_str(nvs, key, src)
+#define NVS_SET_U8(key, val)  nvs_set_u8(nvs, key, val)
+
+    NVS_SET_STR("wifi_ssid",     g_debbie_config.wifi_ssid);
+    NVS_SET_STR("wifi_pass",     g_debbie_config.wifi_password);
+    NVS_SET_STR("wifi_ssid2",    g_debbie_config.wifi_ssid2);
+    NVS_SET_STR("wifi_pass2",    g_debbie_config.wifi_password2);
+    NVS_SET_STR("wifi_ssid3",    g_debbie_config.wifi_ssid3);
+    NVS_SET_STR("wifi_pass3",    g_debbie_config.wifi_password3);
+    NVS_SET_STR("oai_key",       g_debbie_config.openai_api_key);
+    NVS_SET_STR("anthropic_key", g_debbie_config.anthropic_api_key);
+    NVS_SET_STR("groq_key",      g_debbie_config.groq_api_key);
+    NVS_SET_STR("or_key",        g_debbie_config.openrouter_api_key);
+    NVS_SET_STR("llm_provider",  g_debbie_config.llm_provider);
+    NVS_SET_STR("llm_model",     g_debbie_config.llm_model);
+    NVS_SET_STR("local_llm_url", g_debbie_config.local_llm_url);
+    NVS_SET_STR("local_llm_mdl", g_debbie_config.local_llm_model);
+    NVS_SET_STR("agent_url",     g_debbie_config.agent_ws_url);
+    NVS_SET_STR("companion_url", g_debbie_config.companion_url);
+    NVS_SET_STR("name",          g_debbie_config.debbie_name);
+    NVS_SET_STR("sys_prompt",    g_debbie_config.system_prompt);
+    NVS_SET_STR("voice_style",   g_debbie_config.voice_style);
+    NVS_SET_STR("resp_len",      g_debbie_config.response_length);
+    NVS_SET_STR("ble_name",      g_debbie_config.ble_device_name);
+    NVS_SET_STR("spotify_tok",   g_debbie_config.spotify_token);
+    NVS_SET_U8("volume",         g_debbie_config.speaker_volume);
+    NVS_SET_U8("use_agent",      g_debbie_config.use_custom_agent ? 1 : 0);
+    NVS_SET_U8("notifs_en",      g_debbie_config.notifications_enabled ? 1 : 0);
+    NVS_SET_U8("notif_wa",       g_debbie_config.notif_whatsapp ? 1 : 0);
+    NVS_SET_U8("notif_em",       g_debbie_config.notif_email ? 1 : 0);
+    NVS_SET_U8("notif_sp",       g_debbie_config.notif_spotify ? 1 : 0);
+    NVS_SET_U8("cam_en",         g_debbie_config.camera_enabled ? 1 : 0);
+    NVS_SET_U8("bt_en",          g_debbie_config.bluetooth_enabled ? 1 : 0);
+    NVS_SET_U8("mem_en",         g_debbie_config.memory_enabled ? 1 : 0);
+    NVS_SET_U8("mem_rag",        g_debbie_config.memory_rag_enabled ? 1 : 0);
+    NVS_SET_U8("mem_turns",      g_debbie_config.memory_max_turns);
+    nvs_set_u16(nvs, "vad_thresh", g_debbie_config.vad_threshold);
+
+    esp_err_t err = nvs_commit(nvs);
+    nvs_close(nvs);
+    ESP_LOGI(TAG, "Config saved");
+    return err;
+}
+
+esp_err_t storage_factory_reset(void)
+{
+    nvs_handle_t nvs;
+    ESP_ERROR_CHECK(nvs_open(NVS_NAMESPACE, NVS_READWRITE, &nvs));
+    esp_err_t err = nvs_erase_all(nvs);
+    nvs_commit(nvs);
+    nvs_close(nvs);
+    ESP_LOGI(TAG, "Factory reset complete");
+    return err;
+}
diff --git a/firmware/main/storage_manager.h b/firmware/main/storage_manager.h
new file mode 100644
index 0000000..d2387c0
--- /dev/null
+++ b/firmware/main/storage_manager.h
@@ -0,0 +1,18 @@
+#pragma once
+#include "esp_err.h"
+
+/**
+ * @brief  Initialise NVS flash and load saved configuration.
+ *         If no config exists the defaults in settings.h are used.
+ */
+esp_err_t storage_init(void);
+
+/**
+ * @brief  Persist the current g_debbie_config to NVS.
+ */
+esp_err_t storage_save_config(void);
+
+/**
+ * @brief  Erase all Debbie NVS keys (factory reset).
+ */
+esp_err_t storage_factory_reset(void);
diff --git a/firmware/main/vuln_reporter.c b/firmware/main/vuln_reporter.c
new file mode 100644
index 0000000..a52ac8a
--- /dev/null
+++ b/firmware/main/vuln_reporter.c
@@ -0,0 +1,586 @@
+/*
+ * vuln_reporter.c — Vulnerability Assessment & Reporting
+ *
+ * ⚠️  AUTHORISED USE ONLY — Only analyse networks you own or have
+ *      explicit written permission to test. ⚠️
+ */
+
+#include "vuln_reporter.h"
+#include "settings.h"
+#include "debbie.h"
+#include "esp_log.h"
+#include "esp_system.h"
+#include "esp_idf_version.h"
+#include "cJSON.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <time.h>
+
+static const char *TAG = "vulnrpt";
+
+/* ── Known-vulnerable service signatures ─────────────────────────────────── */
+
+typedef struct {
+    const char *banner_fragment;  /* substring to match in banner */
+    const char *vuln_id;
+    const char *title;
+    const char *description;
+    const char *remediation;
+    vuln_severity_t severity;
+} banner_sig_t;
+
+static const banner_sig_t BANNER_SIGS[] = {
+    {
+        "Telnetd", "LOCAL-TELNET-001",
+        "Telnet service exposed",
+        "Telnet transmits credentials and data in plaintext. "
+        "An attacker on the same network can capture login credentials "
+        "using a passive packet sniffer.",
+        "Disable Telnet. Use SSH (port 22) for remote management instead.",
+        VULN_SEV_HIGH,
+    },
+    {
+        "220 FTP", "LOCAL-FTP-001",
+        "FTP service exposed (plaintext)",
+        "FTP credentials and file transfers are sent in plaintext. "
+        "Credentials can be captured by a network eavesdropper.",
+        "Replace FTP with SFTP or FTPS. Restrict access to authorised IPs.",
+        VULN_SEV_MEDIUM,
+    },
+    {
+        "Redis", "LOCAL-REDIS-001",
+        "Redis server detected — verify authentication",
+        "Unauthenticated Redis instances allow remote code execution via "
+        "CONFIG SET to write SSH keys or cron jobs.",
+        "Enable requirepass in redis.conf. Bind Redis to 127.0.0.1 only. "
+        "Use a firewall rule to block external access to port 6379.",
+        VULN_SEV_HIGH,
+    },
+    {
+        "MongoDB", "LOCAL-MONGO-001",
+        "MongoDB detected — verify authentication",
+        "MongoDB instances without authentication allow any client to "
+        "read, write, and drop all databases.",
+        "Enable --auth flag. Create admin users. Bind to 127.0.0.1 "
+        "unless remote access is required.",
+        VULN_SEV_HIGH,
+    },
+    {
+        "Docker", "LOCAL-DOCKER-001",
+        "Docker API exposed without TLS",
+        "An unauthenticated Docker API allows any host on the network to "
+        "create containers with full host filesystem access, enabling "
+        "complete host compromise.",
+        "Enable Docker TLS client authentication (--tlsverify). "
+        "Remove port 2375 exposure — use Unix socket locally.",
+        VULN_SEV_CRITICAL,
+    },
+    {
+        "HTTP/1", "LOCAL-HTTP-001",
+        "Unencrypted HTTP service",
+        "Data transmitted over HTTP is in plaintext and can be "
+        "intercepted or modified by network attackers (MITM).",
+        "Redirect HTTP to HTTPS. Obtain a certificate from Let's Encrypt.",
+        VULN_SEV_LOW,
+    },
+    {
+        "OpenSSH 6", "CVE-2016-0777",
+        "OpenSSH < 7.1 — roaming memory leak",
+        "OpenSSH versions before 7.1p2 with roaming enabled may leak "
+        "private key material to a malicious server.",
+        "Upgrade OpenSSH to version 7.4 or later.",
+        VULN_SEV_MEDIUM,
+    },
+    {
+        "OpenSSH 7.0", "CVE-2015-6564",
+        "OpenSSH 7.0 — use-after-free in keyboard-interactive auth",
+        "A use-after-free vulnerability in the keyboard-interactive "
+        "authentication mechanism could allow authentication bypass.",
+        "Upgrade OpenSSH to 7.4 or later.",
+        VULN_SEV_HIGH,
+    },
+    {
+        "MQTT", "LOCAL-MQTT-001",
+        "MQTT broker detected — verify authentication",
+        "MQTT brokers without authentication allow any client to subscribe "
+        "to all topics and publish arbitrary messages, including to IoT "
+        "actuators.",
+        "Enable MQTT username/password or certificate authentication. "
+        "Use MQTTS (port 8883) with TLS.",
+        VULN_SEV_MEDIUM,
+    },
+    {
+        "Elasticsearch", "LOCAL-ES-001",
+        "Elasticsearch API exposed",
+        "Unauthenticated Elasticsearch instances expose all indexed data "
+        "to any network client and allow deletion of indices.",
+        "Enable Elasticsearch X-Pack security. Restrict network access. "
+        "Upgrade to a version with built-in security.",
+        VULN_SEV_HIGH,
+    },
+};
+#define BANNER_SIGS_COUNT (sizeof(BANNER_SIGS) / sizeof(BANNER_SIGS[0]))
+
+/* ── Port-based checks (without banner) ─────────────────────────────────── */
+
+typedef struct {
+    uint16_t        port;
+    const char     *vuln_id;
+    const char     *title;
+    const char     *description;
+    const char     *remediation;
+    vuln_severity_t severity;
+} port_vuln_t;
+
+static const port_vuln_t PORT_VULNS[] = {
+    {
+        502, "ICS-MODBUS-001",
+        "Modbus TCP exposed — Industrial control protocol",
+        "Modbus is an industrial control protocol with NO authentication "
+        "or encryption. Exposure on a general network allows any client "
+        "to read sensor values and issue control commands to PLCs/actuators. "
+        "This is a CRITICAL risk for industrial/OT environments.",
+        "Isolate Modbus devices on a dedicated OT network segment with "
+        "strict firewall rules. Never expose port 502 to untrusted networks.",
+        VULN_SEV_CRITICAL,
+    },
+    {
+        102, "ICS-S7-001",
+        "Siemens S7comm exposed — Industrial control protocol",
+        "S7comm is Siemens' proprietary PLC protocol with limited security. "
+        "Remote access allows reading/writing memory areas and halting PLCs.",
+        "Isolate on dedicated OT/ICS network. Apply Siemens' security "
+        "hardening guidelines. Use TLS where available (S7comm+).",
+        VULN_SEV_CRITICAL,
+    },
+    {
+        4840, "ICS-OPCUA-001",
+        "OPC-UA server detected",
+        "OPC-UA is an industrial protocol. Verify that security policies "
+        "are not set to 'None' which would allow unauthenticated access.",
+        "Configure OPC-UA security policy to SignAndEncrypt minimum. "
+        "Enable user authentication.",
+        VULN_SEV_MEDIUM,
+    },
+    {
+        5900, "LOCAL-VNC-001",
+        "VNC remote desktop exposed",
+        "VNC without strong authentication or a VPN exposes the desktop "
+        "to brute-force attacks. Many embedded devices use default or "
+        "no VNC passwords.",
+        "Restrict VNC access behind a VPN or SSH tunnel. "
+        "Set a strong password. Use NLA or certificate authentication.",
+        VULN_SEV_HIGH,
+    },
+    {
+        2375, "LOCAL-DOCKER-NOAUTH",
+        "Docker Remote API on port 2375 (no TLS)",
+        "Port 2375 is Docker's unauthenticated API. Any client on the "
+        "network can create privileged containers and escape to the host OS.",
+        "Stop Docker on this port immediately. Use Unix socket "
+        "(/var/run/docker.sock) or enable TLS with client certificates.",
+        VULN_SEV_CRITICAL,
+    },
+    {
+        9200, "LOCAL-ES-PORT",
+        "Elasticsearch HTTP API on port 9200",
+        "Elasticsearch's default configuration allows unauthenticated "
+        "access to all data and administrative functions.",
+        "Enable X-Pack security. Restrict to localhost only.",
+        VULN_SEV_HIGH,
+    },
+    {
+        161, "LOCAL-SNMP-001",
+        "SNMP service detected",
+        "SNMP v1/v2c use community strings (often 'public'/'private') "
+        "which are transmitted in plaintext and rarely changed from defaults. "
+        "SNMP write access allows device configuration changes.",
+        "Use SNMPv3 with authentication and privacy. Change default "
+        "community strings. Restrict SNMP access by source IP.",
+        VULN_SEV_MEDIUM,
+    },
+    {
+        1883, "LOCAL-MQTT-PORT",
+        "MQTT broker on port 1883 (plaintext)",
+        "Unencrypted MQTT allows credential sniffing and message interception. "
+        "IoT devices may subscribe to control topics.",
+        "Migrate to MQTTS (port 8883). Enable broker authentication.",
+        VULN_SEV_MEDIUM,
+    },
+};
+#define PORT_VULNS_COUNT (sizeof(PORT_VULNS) / sizeof(PORT_VULNS[0]))
+
+/* ── WiFi checks ─────────────────────────────────────────────────────────── */
+
+static void check_wifi_security(const scan_results_t *scan,
+                                 vuln_report_t *report)
+{
+    for (int i = 0; i < scan->ap_count; i++) {
+        const wifi_ap_result_t *ap = &scan->aps[i];
+        const char *ssid = ap->ssid[0] ? ap->ssid : "<hidden>";
+
+        if (ap->auth_mode == WIFI_AUTH_OPEN && report->count < MAX_FINDINGS) {
+            vuln_finding_t *f = &report->findings[report->count++];
+            f->severity = VULN_SEV_HIGH;
+            strncpy(f->id,    "WIFI-OPEN-001",             sizeof(f->id)-1);
+            snprintf(f->title, sizeof(f->title),
+                     "Open WiFi network: \"%s\"", ssid);
+            snprintf(f->description, sizeof(f->description),
+                     "Network '%s' (channel %d, BSSID %s) has no encryption. "
+                     "All traffic on this network is visible to any nearby observer.",
+                     ssid, ap->channel, ap->bssid_str);
+            strncpy(f->remediation,
+                    "Enable WPA2-PSK or WPA3 encryption. "
+                    "If intentional (guest AP), isolate it from the main LAN.",
+                    sizeof(f->remediation)-1);
+        }
+
+        if (ap->auth_mode == WIFI_AUTH_WEP && report->count < MAX_FINDINGS) {
+            vuln_finding_t *f = &report->findings[report->count++];
+            f->severity = VULN_SEV_CRITICAL;
+            strncpy(f->id,    "WIFI-WEP-001",              sizeof(f->id)-1);
+            snprintf(f->title, sizeof(f->title),
+                     "WEP encryption on \"%s\" — broken, easily cracked", ssid);
+            snprintf(f->description, sizeof(f->description),
+                     "Network '%s' uses WEP encryption which can be cracked in "
+                     "under 60 seconds using freely available tools. This provides "
+                     "no meaningful security protection.", ssid);
+            strncpy(f->remediation,
+                    "Replace WEP with WPA2-PSK (AES/CCMP) or WPA3 immediately. "
+                    "All connected clients must be re-configured.",
+                    sizeof(f->remediation)-1);
+        }
+    }
+}
+
+/* ── Helper to add a finding ─────────────────────────────────────────────── */
+
+static void add_finding(vuln_report_t *report, const port_vuln_t *pv,
+                        const char *ip, uint16_t port)
+{
+    if (report->count >= MAX_FINDINGS) return;
+    vuln_finding_t *f = &report->findings[report->count++];
+    f->severity      = pv->severity;
+    f->affected_port = port;
+    strncpy(f->id,           pv->vuln_id,      sizeof(f->id)-1);
+    strncpy(f->title,        pv->title,        sizeof(f->title)-1);
+    strncpy(f->description,  pv->description,  sizeof(f->description)-1);
+    strncpy(f->remediation,  pv->remediation,  sizeof(f->remediation)-1);
+    strncpy(f->affected_ip,  ip,               sizeof(f->affected_ip)-1);
+}
+
+static void add_banner_finding(vuln_report_t *report, const banner_sig_t *bs,
+                               const char *ip, uint16_t port)
+{
+    if (report->count >= MAX_FINDINGS) return;
+    vuln_finding_t *f = &report->findings[report->count++];
+    f->severity      = bs->severity;
+    f->affected_port = port;
+    strncpy(f->id,          bs->vuln_id,     sizeof(f->id)-1);
+    strncpy(f->title,       bs->title,       sizeof(f->title)-1);
+    strncpy(f->description, bs->description, sizeof(f->description)-1);
+    strncpy(f->remediation, bs->remediation, sizeof(f->remediation)-1);
+    strncpy(f->affected_ip, ip,              sizeof(f->affected_ip)-1);
+}
+
+/* ── Count by severity ────────────────────────────────────────────────────── */
+
+static void tally_severities(vuln_report_t *report)
+{
+    report->critical_count = 0;
+    report->high_count     = 0;
+    report->medium_count   = 0;
+    report->low_count      = 0;
+    report->info_count     = 0;
+    for (int i = 0; i < report->count; i++) {
+        switch (report->findings[i].severity) {
+        case VULN_SEV_CRITICAL: report->critical_count++; break;
+        case VULN_SEV_HIGH:     report->high_count++;     break;
+        case VULN_SEV_MEDIUM:   report->medium_count++;   break;
+        case VULN_SEV_LOW:      report->low_count++;      break;
+        case VULN_SEV_INFO:     report->info_count++;     break;
+        }
+    }
+}
+
+/* ── Public API ───────────────────────────────────────────────────────────── */
+
+esp_err_t vuln_reporter_analyse(const scan_results_t *scan,
+                                vuln_report_t        *report)
+{
+    if (!scan || !report) return ESP_ERR_INVALID_ARG;
+    memset(report, 0, sizeof(*report));
+
+    report->total_hosts_scanned = scan->host_count;
+
+    /* Record timestamp */
+    time_t now = 0;
+    time(&now);
+    struct tm tm_info;
+    localtime_r(&now, &tm_info);
+    strftime(report->scan_timestamp, sizeof(report->scan_timestamp),
+             "%Y-%m-%d %H:%M:%S", &tm_info);
+
+    snprintf(report->network_cidr, sizeof(report->network_cidr),
+             "%s/%s", scan->own_ip, scan->subnet_mask);
+
+    /* WiFi security checks */
+    check_wifi_security(scan, report);
+
+    /* Per-host analysis */
+    int total_ports = 0;
+    for (int h = 0; h < scan->host_count; h++) {
+        const host_result_t *host = &scan->hosts[h];
+        total_ports += host->port_count;
+
+        for (int p = 0; p < host->port_count; p++) {
+            const scan_port_result_t *port = &host->ports[p];
+            if (port->state != PORT_STATE_OPEN) continue;
+
+            /* Banner signature matching */
+            for (int s = 0; s < (int)BANNER_SIGS_COUNT; s++) {
+                if (port->banner[0] &&
+                    strstr(port->banner, BANNER_SIGS[s].banner_fragment)) {
+                    add_banner_finding(report, &BANNER_SIGS[s],
+                                       host->ip_str, port->port);
+                }
+            }
+
+            /* Port-based checks (no banner needed) */
+            for (int v = 0; v < (int)PORT_VULNS_COUNT; v++) {
+                if (port->port == PORT_VULNS[v].port) {
+                    add_finding(report, &PORT_VULNS[v],
+                                host->ip_str, port->port);
+                }
+            }
+        }
+    }
+    report->total_ports_scanned = total_ports;
+
+    /* De-duplicate findings (same vuln_id + ip) */
+    for (int i = 0; i < report->count - 1; i++) {
+        for (int j = i + 1; j < report->count; j++) {
+            if (strcmp(report->findings[i].id,          report->findings[j].id) == 0 &&
+                strcmp(report->findings[i].affected_ip, report->findings[j].affected_ip) == 0) {
+                /* Remove j by overwriting with last */
+                report->findings[j] = report->findings[report->count - 1];
+                report->count--;
+                j--;
+            }
+        }
+    }
+
+    tally_severities(report);
+
+    ESP_LOGI(TAG, "Analysis: %d findings (C:%d H:%d M:%d L:%d)",
+             report->count,
+             report->critical_count, report->high_count,
+             report->medium_count,   report->low_count);
+    return ESP_OK;
+}
+
+/* ── Serialisation ────────────────────────────────────────────────────────── */
+
+static const char *sev_str(vuln_severity_t s)
+{
+    switch (s) {
+    case VULN_SEV_CRITICAL: return "CRITICAL";
+    case VULN_SEV_HIGH:     return "HIGH";
+    case VULN_SEV_MEDIUM:   return "MEDIUM";
+    case VULN_SEV_LOW:      return "LOW";
+    default:                return "INFO";
+    }
+}
+
+char *vuln_reporter_to_json(const vuln_report_t *report)
+{
+    if (!report) return NULL;
+    cJSON *root = cJSON_CreateObject();
+    cJSON_AddStringToObject(root, "scan_time",            report->scan_timestamp);
+    cJSON_AddStringToObject(root, "network",              report->network_cidr);
+    cJSON_AddNumberToObject(root, "hosts_scanned",        report->total_hosts_scanned);
+    cJSON_AddNumberToObject(root, "ports_scanned",        report->total_ports_scanned);
+    cJSON_AddNumberToObject(root, "total_findings",       report->count);
+    cJSON_AddNumberToObject(root, "critical",             report->critical_count);
+    cJSON_AddNumberToObject(root, "high",                 report->high_count);
+    cJSON_AddNumberToObject(root, "medium",               report->medium_count);
+    cJSON_AddNumberToObject(root, "low",                  report->low_count);
+    cJSON_AddNumberToObject(root, "info",                 report->info_count);
+
+    cJSON *findings = cJSON_CreateArray();
+    for (int i = 0; i < report->count; i++) {
+        const vuln_finding_t *f = &report->findings[i];
+        cJSON *fobj = cJSON_CreateObject();
+        cJSON_AddStringToObject(fobj, "severity",    sev_str(f->severity));
+        cJSON_AddStringToObject(fobj, "id",          f->id);
+        cJSON_AddStringToObject(fobj, "title",       f->title);
+        cJSON_AddStringToObject(fobj, "description", f->description);
+        cJSON_AddStringToObject(fobj, "remediation", f->remediation);
+        if (f->affected_ip[0])
+            cJSON_AddStringToObject(fobj, "affected_ip", f->affected_ip);
+        if (f->affected_port)
+            cJSON_AddNumberToObject(fobj, "affected_port", f->affected_port);
+        cJSON_AddItemToArray(findings, fobj);
+    }
+    cJSON_AddItemToObject(root, "findings", findings);
+
+    char *out = cJSON_PrintUnformatted(root);
+    cJSON_Delete(root);
+    return out;
+}
+
+char *vuln_reporter_to_text(const vuln_report_t *report)
+{
+    if (!report) return NULL;
+    char *buf = malloc(4096);
+    if (!buf) return NULL;
+    int off = 0;
+
+    off += snprintf(buf + off, 4096 - off,
+        "═══════════════════════════════════════════════════════\n"
+        "  DEBBIE NETWORK SECURITY REPORT\n"
+        "  ⚠️  Authorised Use Only — Own Networks / With Permission\n"
+        "═══════════════════════════════════════════════════════\n"
+        "Scan time   : %s\n"
+        "Network     : %s\n"
+        "Hosts scanned: %d  |  Ports scanned: %d\n"
+        "Findings    : %d total — "
+        "🔴 %d CRITICAL  🟠 %d HIGH  🟡 %d MEDIUM  🟢 %d LOW\n"
+        "───────────────────────────────────────────────────────\n",
+        report->scan_timestamp, report->network_cidr,
+        report->total_hosts_scanned, report->total_ports_scanned,
+        report->count,
+        report->critical_count, report->high_count,
+        report->medium_count, report->low_count);
+
+    /* Print findings: critical first */
+    for (int i = 0; i < report->count && off < 3900; i++) {
+        const vuln_finding_t *f = &report->findings[i];
+        /* Use ASCII severity labels to avoid multi-byte buffer overflow */
+        const char *sev_icon;
+        switch (f->severity) {
+        case VULN_SEV_CRITICAL: sev_icon = "[CRITICAL]"; break;
+        case VULN_SEV_HIGH:     sev_icon = "[HIGH]";     break;
+        case VULN_SEV_MEDIUM:   sev_icon = "[MEDIUM]";   break;
+        case VULN_SEV_LOW:      sev_icon = "[LOW]";      break;
+        default:                sev_icon = "[INFO]";     break;
+        }
+        off += snprintf(buf + off, 4096 - off,
+            "\n%s %s (%s)\n"
+            "   Host: %s  Port: %d\n"
+            "   %s\n"
+            "   Fix: %s\n",
+            sev_icon, f->title, f->id,
+            f->affected_ip[0] ? f->affected_ip : "N/A",
+            f->affected_port,
+            f->description,
+            f->remediation);
+    }
+
+    off += snprintf(buf + off, 4096 - off,
+        "\n═══════════════════════════════════════════════════════\n"
+        "  Generated by Debbie — Portable AI Security Assistant\n"
+        "═══════════════════════════════════════════════════════\n");
+    return buf;
+}
+
+char *vuln_reporter_get_voice_summary(const vuln_report_t *report)
+{
+    if (!report) return NULL;
+    char *buf = malloc(512);
+    if (!buf) return NULL;
+    int off = 0;
+
+    if (report->count == 0) {
+        snprintf(buf, 512,
+            "Great news! The network scan is complete. "
+            "I scanned %d devices and found no significant vulnerabilities. "
+            "Your network looks pretty clean!",
+            report->total_hosts_scanned);
+        return buf;
+    }
+
+    off += snprintf(buf + off, 512 - off,
+        "Security scan complete. I scanned %d devices and found %d vulnerabilities — ",
+        report->total_hosts_scanned, report->count);
+
+    if (report->critical_count > 0)
+        off += snprintf(buf + off, 512 - off,
+            "%d critical, ", report->critical_count);
+    if (report->high_count > 0)
+        off += snprintf(buf + off, 512 - off,
+            "%d high, ", report->high_count);
+    if (report->medium_count > 0)
+        off += snprintf(buf + off, 512 - off,
+            "%d medium severity. ", report->medium_count);
+
+    /* Mention the worst finding */
+    if (report->count > 0) {
+        const vuln_finding_t *worst = &report->findings[0];
+        off += snprintf(buf + off, 512 - off,
+            "The most serious issue is: %s. I've logged the full report. "
+            "Shall I walk you through the fixes?",
+            worst->title);
+    }
+
+    return buf;
+}
+
+/* ── Self-assessment of Debbie device ────────────────────────────────────── */
+
+esp_err_t vuln_reporter_self_assess(vuln_report_t *report)
+{
+    if (!report) return ESP_ERR_INVALID_ARG;
+    memset(report, 0, sizeof(*report));
+
+    /* Use a real timestamp */
+    time_t now = 0;
+    time(&now);
+    struct tm tm_info;
+    localtime_r(&now, &tm_info);
+    strftime(report->scan_timestamp, sizeof(report->scan_timestamp),
+             "%Y-%m-%d %H:%M:%S", &tm_info);
+    strncpy(report->network_cidr, "device-self", sizeof(report->network_cidr)-1);
+
+    /* Check TLS config */
+#ifdef CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY
+    if (report->count < MAX_FINDINGS) {
+        vuln_finding_t *f = &report->findings[report->count++];
+        f->severity = VULN_SEV_HIGH;
+        strncpy(f->id, "SELF-TLS-001", sizeof(f->id)-1);
+        strncpy(f->title, "TLS certificate verification disabled (development mode)",
+                sizeof(f->title)-1);
+        strncpy(f->description,
+                "CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY is enabled. "
+                "The device does not verify TLS server certificates, "
+                "making it vulnerable to MITM attacks on all HTTPS/WSS connections.",
+                sizeof(f->description)-1);
+        strncpy(f->remediation,
+                "Remove CONFIG_ESP_TLS_INSECURE from sdkconfig.defaults "
+                "before deploying to production.",
+                sizeof(f->remediation)-1);
+    }
+#endif
+
+    /* Check firmware version */
+    if (report->count < MAX_FINDINGS) {
+        vuln_finding_t *f = &report->findings[report->count++];
+        f->severity = VULN_SEV_INFO;
+        strncpy(f->id, "SELF-VER-001", sizeof(f->id)-1);
+        snprintf(f->title, sizeof(f->title),
+                 "Firmware: ESP-IDF v%d.%d.%d",
+                 ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH);
+        snprintf(f->description, sizeof(f->description),
+                 "Running ESP-IDF v%d.%d.%d. Ensure this is kept up to date.",
+                 ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH);
+        strncpy(f->remediation,
+                "Monitor https://github.com/espressif/esp-idf/releases for security patches.",
+                sizeof(f->remediation)-1);
+    }
+
+    tally_severities(report);
+    return ESP_OK;
+}
diff --git a/firmware/main/vuln_reporter.h b/firmware/main/vuln_reporter.h
new file mode 100644
index 0000000..970ce26
--- /dev/null
+++ b/firmware/main/vuln_reporter.h
@@ -0,0 +1,88 @@
+#pragma once
+/*
+ * vuln_reporter.h — Vulnerability Assessment & Reporting
+ *
+ * ⚠️  AUTHORISED USE ONLY ⚠️
+ *
+ * Provides:
+ *  • Device self-assessment (own open services, firmware version)
+ *  • CVE lookup via companion server (NVD API)
+ *  • Known default-credential checks for common embedded devices
+ *  • TLS/SSL configuration analysis
+ *  • Formatted vulnerability reports (text + JSON)
+ */
+
+#include "esp_err.h"
+#include "network_scanner.h"
+#include <stdbool.h>
+
+typedef enum {
+    VULN_SEV_INFO     = 0,
+    VULN_SEV_LOW,
+    VULN_SEV_MEDIUM,
+    VULN_SEV_HIGH,
+    VULN_SEV_CRITICAL,
+} vuln_severity_t;
+
+typedef struct {
+    vuln_severity_t severity;
+    char            id[24];        /* e.g. "CVE-2021-12345" or "LOCAL-001" */
+    char            title[96];
+    char            description[256];
+    char            remediation[200];
+    char            affected_ip[16];
+    uint16_t        affected_port;
+} vuln_finding_t;
+
+#define MAX_FINDINGS 64
+
+typedef struct {
+    vuln_finding_t  findings[MAX_FINDINGS];
+    int             count;
+    int             critical_count;
+    int             high_count;
+    int             medium_count;
+    int             low_count;
+    int             info_count;
+    char            scan_timestamp[32];
+    char            network_cidr[20];
+    int             total_hosts_scanned;
+    int             total_ports_scanned;
+} vuln_report_t;
+
+/**
+ * @brief  Analyse scan results and build a vulnerability report.
+ *         Checks for:
+ *           - Plaintext protocols (Telnet, FTP, unencrypted MQTT)
+ *           - Exposed management interfaces (Docker API, Redis, MongoDB)
+ *           - Weak WiFi encryption (WEP, open APs)
+ *           - Default credential indicators (via banner matching)
+ *           - Known-vulnerable service signatures
+ *           - Dangerous industrial protocol exposure (Modbus, S7)
+ */
+esp_err_t vuln_reporter_analyse(const scan_results_t *scan,
+                                vuln_report_t        *report);
+
+/**
+ * @brief  Serialise report to a JSON string.
+ *         Caller must free() the returned pointer.
+ */
+char *vuln_reporter_to_json(const vuln_report_t *report);
+
+/**
+ * @brief  Generate a human-readable text report.
+ *         Caller must free() the returned pointer.
+ */
+char *vuln_reporter_to_text(const vuln_report_t *report);
+
+/**
+ * @brief  Generate a concise summary for AI voice output.
+ *         Caller must free() the returned pointer.
+ */
+char *vuln_reporter_get_voice_summary(const vuln_report_t *report);
+
+/**
+ * @brief  Perform a self-assessment of the Debbie device itself.
+ *         Checks NVS, open ports, TLS configuration, firmware version.
+ */
+esp_err_t vuln_reporter_self_assess(vuln_report_t *report);
diff --git a/firmware/main/web_server.c b/firmware/main/web_server.c
new file mode 100644
index 0000000..d102b6e
--- /dev/null
+++ b/firmware/main/web_server.c
@@ -0,0 +1,831 @@
+#include "web_server.h"
+#include "debbie.h"
+#include "settings.h"
+#include "storage_manager.h"
+#include "wifi_manager.h"
+#include "camera_manager.h"
+#include "memory_manager.h"
+#include "esp_log.h"
+#include "esp_http_server.h"
+#include "cJSON.h"
+#include <string.h>
+#include <stdlib.h>
+
+static const char *TAG = "web";
+
+/* --------------------------------------------------------------------------
+ * Full configuration portal — tabbed single-page app
+ * Tabs: Network | AI & LLM | Personality | Notifications | Advanced
+ * -------------------------------------------------------------------------- */
+static const char SETUP_HTML[] =
+"<!DOCTYPE html><html lang='en'><head>"
+"<meta charset='UTF-8'><meta name='viewport' content='width=device-width,initial-scale=1'>"
+"<title>Debbie Config ✨</title>"
+"<style>"
+"*{box-sizing:border-box;margin:0;padding:0}"
+"body{font-family:system-ui,sans-serif;background:#0d0d1a;color:#e0e0f0;min-height:100vh}"
+".hero{background:linear-gradient(135deg,#0f3460 0%,#533483 60%,#9b2bba 100%);"
+"padding:28px 20px 20px;text-align:center}"
+".hero h1{font-size:1.9rem;margin-bottom:4px;letter-spacing:.5px}"
+".hero p{opacity:.8;font-size:.9rem}"
+".badge{display:inline-block;background:rgba(255,255,255,.15);border-radius:20px;"
+"padding:2px 10px;font-size:.75rem;margin-top:6px}"
+
+/* Tab bar */
+".tabs{display:flex;overflow-x:auto;background:#12122a;border-bottom:2px solid #1e1e3f}"
+".tab{flex:0 0 auto;padding:11px 16px;cursor:pointer;font-size:.83rem;color:#aaa;"
+"white-space:nowrap;border-bottom:3px solid transparent;transition:.2s}"
+".tab.active{color:#06d6a0;border-bottom-color:#06d6a0;font-weight:600}"
+".tab:hover{color:#eee}"
+
+/* Content */
+".page{display:none;padding:0 12px 80px}"
+".page.active{display:block}"
+".card{background:#12122a;border-radius:14px;padding:20px;margin:14px 0;"
+"box-shadow:0 4px 20px rgba(0,0,0,.35)}"
+".card-title{color:#06d6a0;font-size:.95rem;font-weight:600;margin-bottom:14px;"
+"display:flex;align-items:center;gap:8px}"
+"label{display:block;margin-bottom:3px;font-size:.8rem;color:#999}"
+"input,select,textarea{width:100%;padding:9px 11px;border-radius:8px;"
+"border:1px solid #2a2a4a;background:#0d0d1a;color:#e0e0f0;"
+"font-size:.9rem;margin-bottom:10px}"
+"input:focus,textarea:focus,select:focus{outline:none;border-color:#06d6a0}"
+"textarea{resize:vertical;min-height:90px;font-family:inherit}"
+"select option{background:#0d0d1a}"
+".row2{display:grid;grid-template-columns:1fr 1fr;gap:10px}"
+".toggle-row{display:flex;justify-content:space-between;align-items:center;"
+"padding:8px 0;border-bottom:1px solid #1e1e3f}"
+".toggle-row:last-child{border:none}"
+".toggle-label{font-size:.88rem;color:#ccc}"
+".toggle-sub{font-size:.75rem;color:#777;margin-top:2px}"
+"input[type=checkbox]{width:auto;margin:0;accent-color:#06d6a0}"
+".switch{position:relative;width:44px;height:24px}"
+".switch input{opacity:0;width:0;height:0}"
+".slider{position:absolute;cursor:pointer;inset:0;background:#333;border-radius:24px;transition:.3s}"
+".slider:before{content:'';position:absolute;height:18px;width:18px;left:3px;bottom:3px;"
+"background:#fff;border-radius:50%;transition:.3s}"
+"input:checked+.slider{background:#06d6a0}"
+"input:checked+.slider:before{transform:translateX(20px)}"
+
+/* Provider cards */
+".llm-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(130px,1fr));gap:8px;margin-bottom:12px}"
+".llm-card{border:2px solid #2a2a4a;border-radius:10px;padding:10px 8px;cursor:pointer;"
+"text-align:center;transition:.2s;background:#0d0d1a}"
+".llm-card:hover{border-color:#5e548e}"
+".llm-card.sel{border-color:#06d6a0;background:#0a2a1e}"
+".llm-icon{font-size:1.5rem;margin-bottom:4px}"
+".llm-name{font-size:.75rem;font-weight:600;color:#ccc}"
+".llm-desc{font-size:.68rem;color:#666;margin-top:2px}"
+
+/* Buttons */
+".btn-bar{position:fixed;bottom:0;left:0;right:0;background:#12122a;"
+"border-top:1px solid #1e1e3f;padding:10px 16px;display:flex;gap:8px;z-index:100}"
+"button{padding:10px 16px;border-radius:8px;border:none;font-size:.88rem;cursor:pointer;transition:.2s}"
+".btn-save{background:linear-gradient(90deg,#06d6a0,#5e548e);color:#fff;font-weight:700;flex:1}"
+".btn-reset{background:#3a1010;color:#e74c3c;}"
+"button:hover{opacity:.88;transform:translateY(-1px)}"
+".msg{padding:10px 14px;border-radius:8px;margin-top:10px;display:none;font-size:.88rem}"
+".msg.ok{background:#0d3a28;color:#06d6a0;display:block}"
+".msg.err{background:#3a0d0d;color:#e74c3c;display:block}"
+".status-bar{display:flex;gap:12px;flex-wrap:wrap;padding:10px 0;font-size:.8rem;color:#888}"
+".dot{display:inline-block;width:7px;height:7px;border-radius:50%;margin-right:4px}"
+".green{background:#06d6a0}.red{background:#e74c3c}.blue{background:#3a8fd6}"
+".hint{font-size:.72rem;color:#555;margin-top:-6px;margin-bottom:8px}"
+".section-sep{border:none;border-top:1px solid #1e1e3f;margin:14px 0}"
+"</style></head><body>"
+
+/* Hero */
+"<div class='hero'>"
+"<h1>✨ Debbie Config</h1>"
+"<p>Portable Personal AI Companion</p>"
+"<div class='badge' id='fw_badge'>Firmware v" DEBBIE_FW_VERSION "</div>"
+"</div>"
+
+/* Tab bar */
+"<div class='tabs'>"
+"<div class='tab active' onclick='showTab(0)'>📶 Network</div>"
+"<div class='tab' onclick='showTab(1)'>🤖 AI & LLM</div>"
+"<div class='tab' onclick='showTab(2)'>🎀 Personality</div>"
+"<div class='tab' onclick='showTab(3)'>🔔 Notifications</div>"
+"<div class='tab' onclick='showTab(4)'>⚙️ Advanced</div>"
+"<div class='tab' onclick='showTab(5)'>🧠 Memory</div>"
+"</div>"
+
+/* ── Page 0: Network ───────────────────────────────────────── */
+"<div class='page active' id='p0'>"
+
+"<div class='card'>"
+"<div class='card-title'>📶 Wi-Fi Networks</div>"
+"<p style='font-size:.8rem;color:#777;margin-bottom:12px'>"
+"Save up to 3 networks. Debbie tries them in order on boot.</p>"
+
+"<label>Primary SSID</label><input id='ssid' placeholder='Your home WiFi'>"
+"<label>Password</label><input id='pass' type='password' placeholder='Password'>"
+"<hr class='section-sep'>"
+"<label>Secondary SSID <span style='color:#555'>(fallback 1)</span></label>"
+"<input id='ssid2' placeholder='Office / mobile hotspot'>"
+"<label>Password</label><input id='pass2' type='password' placeholder='Password'>"
+"<hr class='section-sep'>"
+"<label>Tertiary SSID <span style='color:#555'>(fallback 2)</span></label>"
+"<input id='ssid3' placeholder='Another network'>"
+"<label>Password</label><input id='pass3' type='password' placeholder='Password'>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>🔵 Bluetooth (BLE)</div>"
+"<p style='font-size:.8rem;color:#777;margin-bottom:12px'>"
+"BLE lets you configure Debbie wirelessly from any phone using a "
+"BLE Serial app (e.g. nRF Toolbox, Serial Bluetooth Terminal) — "
+"no WiFi setup required. Send JSON config commands to the Nordic UART Service.</p>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>Enable Bluetooth</div>"
+"<div class='toggle-sub'>BLE advertising · Nordic UART Service</div></div>"
+"<label class='switch'><input type='checkbox' id='bt_en'>"
+"<span class='slider'></span></label></div>"
+"<br>"
+"<label>BLE Device Name</label>"
+"<input id='ble_name' placeholder='Debbie'>"
+"<p class='hint'>Name shown when scanning for BLE devices on your phone.</p>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>📡 Companion Server</div>"
+"<label>Companion Server URL</label>"
+"<input id='companion_url' placeholder='ws://192.168.1.10:3001'>"
+"<p class='hint'>Node.js companion server for WhatsApp, Email, Spotify &amp; agent tools.</p>"
+"</div>"
+
+"</div>"
+
+/* ── Page 1: AI & LLM ─────────────────────────────────────── */
+"<div class='page' id='p1'>"
+
+"<div class='card'>"
+"<div class='card-title'>🧠 LLM Provider</div>"
+"<p style='font-size:.8rem;color:#777;margin-bottom:12px'>"
+"Choose which AI service powers Debbie. Local providers (Ollama, LM Studio) "
+"work entirely on your own hardware — great for privacy and offline use.</p>"
+"<div class='llm-grid'>"
+"<div class='llm-card sel' id='pcard_openai' onclick='selectProvider(\"openai\")'>"
+"<div class='llm-icon'>🌐</div><div class='llm-name'>OpenAI</div>"
+"<div class='llm-desc'>GPT-4o, o1, Realtime</div></div>"
+"<div class='llm-card' id='pcard_anthropic' onclick='selectProvider(\"anthropic\")'>"
+"<div class='llm-icon'>🧬</div><div class='llm-name'>Anthropic</div>"
+"<div class='llm-desc'>Claude 3.5+</div></div>"
+"<div class='llm-card' id='pcard_groq' onclick='selectProvider(\"groq\")'>"
+"<div class='llm-icon'>⚡</div><div class='llm-name'>Groq</div>"
+"<div class='llm-desc'>Ultra-fast inference</div></div>"
+"<div class='llm-card' id='pcard_openrouter' onclick='selectProvider(\"openrouter\")'>"
+"<div class='llm-icon'>🔀</div><div class='llm-name'>OpenRouter</div>"
+"<div class='llm-desc'>100+ models</div></div>"
+"<div class='llm-card' id='pcard_ollama' onclick='selectProvider(\"ollama\")'>"
+"<div class='llm-icon'>🏠</div><div class='llm-name'>Ollama</div>"
+"<div class='llm-desc'>Local · private</div></div>"
+"</div>"
+"<input type='hidden' id='llm_provider' value='openai'>"
+"</div>"
+
+"<div class='card' id='card_openai'>"
+"<div class='card-title'>🌐 OpenAI Settings</div>"
+"<label>API Key</label>"
+"<input id='oai_key' type='password' placeholder='sk-...'>"
+"<label>Model</label>"
+"<select id='oai_model'>"
+"<option value='gpt-4o'>gpt-4o (recommended)</option>"
+"<option value='gpt-4o-mini'>gpt-4o-mini (faster / cheaper)</option>"
+"<option value='o1-preview'>o1-preview (reasoning)</option>"
+"<option value='o1-mini'>o1-mini</option>"
+"</select>"
+"<p class='hint'>Realtime voice always uses gpt-4o-realtime-preview regardless of model selection above.</p>"
+"</div>"
+
+"<div class='card' id='card_anthropic' style='display:none'>"
+"<div class='card-title'>🧬 Anthropic Settings</div>"
+"<label>API Key</label>"
+"<input id='anthropic_key' type='password' placeholder='sk-ant-...'>"
+"<label>Model</label>"
+"<select id='anthropic_model'>"
+"<option value='claude-3-5-sonnet-20241022'>Claude 3.5 Sonnet (recommended)</option>"
+"<option value='claude-3-5-haiku-20241022'>Claude 3.5 Haiku (fast)</option>"
+"<option value='claude-3-opus-20240229'>Claude 3 Opus (most capable)</option>"
+"</select>"
+"</div>"
+
+"<div class='card' id='card_groq' style='display:none'>"
+"<div class='card-title'>⚡ Groq Settings</div>"
+"<label>API Key</label>"
+"<input id='groq_key' type='password' placeholder='gsk_...'>"
+"<label>Model</label>"
+"<select id='groq_model'>"
+"<option value='llama-3.3-70b-versatile'>Llama 3.3 70B Versatile (recommended)</option>"
+"<option value='llama-3.1-8b-instant'>Llama 3.1 8B Instant (fastest)</option>"
+"<option value='mixtral-8x7b-32768'>Mixtral 8x7B</option>"
+"<option value='gemma2-9b-it'>Gemma 2 9B</option>"
+"</select>"
+"</div>"
+
+"<div class='card' id='card_openrouter' style='display:none'>"
+"<div class='card-title'>🔀 OpenRouter Settings</div>"
+"<label>API Key</label>"
+"<input id='or_key' type='password' placeholder='sk-or-...'>"
+"<label>Model (OpenRouter model ID)</label>"
+"<input id='or_model' placeholder='anthropic/claude-3.5-sonnet'>"
+"<p class='hint'>Any model available on openrouter.ai. Examples:<br>"
+"• anthropic/claude-3.5-sonnet<br>• google/gemini-2.0-flash<br>• meta-llama/llama-3.3-70b-instruct</p>"
+"</div>"
+
+"<div class='card' id='card_ollama' style='display:none'>"
+"<div class='card-title'>🏠 Local LLM (Ollama / LM Studio)</div>"
+"<label>Server URL</label>"
+"<input id='local_llm_url' placeholder='http://192.168.1.100:11434'>"
+"<p class='hint'>Ollama default: http://&lt;your-PC-IP&gt;:11434 &nbsp;|&nbsp; LM Studio: http://&lt;your-PC-IP&gt;:1234</p>"
+"<label>Model Name</label>"
+"<input id='local_llm_model' placeholder='llama3'>"
+"<p class='hint'>Run <code style='color:#06d6a0'>ollama list</code> to see installed models. "
+"Examples: llama3, mistral, phi3, gemma2, qwen2.5</p>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>🔗 Custom Agent (optional)</div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>Use Custom Agent Endpoint</div>"
+"<div class='toggle-sub'>Route all AI calls through your own agent server</div></div>"
+"<label class='switch'><input type='checkbox' id='use_agent'>"
+"<span class='slider'></span></label></div>"
+"<br>"
+"<label>Agent WebSocket URL</label>"
+"<input id='agent_url' placeholder='ws://your-agent:8080'>"
+"<p class='hint'>Your agent receives function calls and returns results. "
+"Must implement the Debbie agent protocol.</p>"
+"</div>"
+"</div>"
+
+/* ── Page 2: Personality ──────────────────────────────────── */
+"<div class='page' id='p2'>"
+
+"<div class='card'>"
+"<div class='card-title'>🎀 Identity</div>"
+"<label>Name</label>"
+"<input id='name' placeholder='Debbie'>"
+"<p class='hint'>What your AI companion calls herself and how she introduces herself.</p>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>💬 Voice &amp; Response Style</div>"
+"<label>Voice Style</label>"
+"<select id='voice_style'>"
+"<option value='friendly'>😊 Friendly (warm, casual, approachable)</option>"
+"<option value='professional'>💼 Professional (formal, concise, business-like)</option>"
+"<option value='playful'>🎉 Playful (fun, energetic, uses humour)</option>"
+"<option value='calm'>🧘 Calm (soothing, measured, thoughtful)</option>"
+"</select>"
+"<label>Response Length</label>"
+"<select id='resp_len'>"
+"<option value='brief'>⚡ Brief (1–2 sentences max)</option>"
+"<option value='normal'>📝 Normal (natural conversational length)</option>"
+"<option value='detailed'>📚 Detailed (thorough explanations)</option>"
+"</select>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>📜 System Prompt</div>"
+"<p style='font-size:.8rem;color:#777;margin-bottom:10px'>"
+"The system prompt defines your AI companion's core personality, knowledge "
+"and behaviour. The defaults work great — only change this if you want to "
+"significantly alter Debbie's persona.</p>"
+"<label>System Prompt</label>"
+"<textarea id='sys_prompt' rows='8'></textarea>"
+"<button class='btn-save' style='width:auto;padding:8px 16px;font-size:.8rem' "
+"onclick='resetPrompt()'>↩ Reset to Default</button>"
+"</div>"
+"</div>"
+
+/* ── Page 3: Notifications ───────────────────────────────── */
+"<div class='page' id='p3'>"
+
+"<div class='card'>"
+"<div class='card-title'>🔔 Notification Sources</div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>All Notifications</div>"
+"<div class='toggle-sub'>Master switch</div></div>"
+"<label class='switch'><input type='checkbox' id='notifs_en' checked>"
+"<span class='slider'></span></label></div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>💬 WhatsApp</div>"
+"<div class='toggle-sub'>New messages via companion server</div></div>"
+"<label class='switch'><input type='checkbox' id='notif_wa' checked>"
+"<span class='slider'></span></label></div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>📧 Email</div>"
+"<div class='toggle-sub'>Unread emails via companion server</div></div>"
+"<label class='switch'><input type='checkbox' id='notif_em' checked>"
+"<span class='slider'></span></label></div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>🎵 Spotify</div>"
+"<div class='toggle-sub'>Now playing &amp; playback controls</div></div>"
+"<label class='switch'><input type='checkbox' id='notif_sp' checked>"
+"<span class='slider'></span></label></div>"
+"</div>"
+"</div>"
+
+/* ── Page 4: Advanced ────────────────────────────────────── */
+"<div class='page' id='p4'>"
+
+"<div class='card'>"
+"<div class='card-title'>🔊 Audio</div>"
+"<label>Speaker Volume (0–100)</label>"
+"<input id='volume' type='number' min='0' max='100' value='75'>"
+"<label>VAD Threshold (100–2000)</label>"
+"<input id='vad_thresh' type='number' min='100' max='2000' value='300'>"
+"<p class='hint'>Voice activity detection sensitivity. Lower = more sensitive. "
+"Default 300. Increase if Debbie triggers on background noise.</p>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>📷 Camera</div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>Enable Camera</div>"
+"<div class='toggle-sub'>OV2640 — vision queries use gpt-4o</div></div>"
+"<label class='switch'><input type='checkbox' id='cam_en' checked>"
+"<span class='slider'></span></label></div>"
+"<br>"
+"<a href='/snapshot' target='_blank' style='color:#06d6a0;font-size:.85rem'>"
+"📸 Test Camera Snapshot →</a>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>ℹ️ Device Status</div>"
+"<div class='status-bar' id='status_bar'>Loading...</div>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>🗑️ Factory Reset</div>"
+"<p style='font-size:.8rem;color:#777;margin-bottom:12px'>"
+"Erase all saved settings and reboot. You will need to reconfigure everything.</p>"
+"<button class='btn-reset' onclick='doReset()'>🗑️ Factory Reset</button>"
+"</div>"
+"</div>"
+
+/* ── Page 5: Memory & RAG ────────────────────────────────── */
+"<div class='page' id='p5'>"
+
+"<div class='card'>"
+"<div class='card-title'>🧠 Conversation Memory</div>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>Enable Memory</div>"
+"<div class='toggle-sub'>Remember recent conversations and facts across sessions</div></div>"
+"<label class='switch'><input type='checkbox' id='mem_en' checked>"
+"<span class='slider'></span></label></div><br>"
+"<div class='toggle-row'>"
+"<div><div class='toggle-label'>Companion RAG</div>"
+"<div class='toggle-sub'>Query companion server for richer context retrieval</div></div>"
+"<label class='switch'><input type='checkbox' id='mem_rag' checked>"
+"<span class='slider'></span></label></div><br>"
+"<label>Recent turns to keep in memory (5–50)</label>"
+"<input id='mem_turns' type='number' min='5' max='50' value='20'>"
+"<p class='hint'>Stored in NVS flash; survives reboots. Companion server stores unlimited history.</p>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>📊 Memory Stats</div>"
+"<div class='status-bar' id='mem_stats'>Loading...</div>"
+"<br><button class='btn' style='background:#c0392b;color:#fff' onclick='clearMem()'>"
+"🗑️ Clear All Memory</button>"
+"</div>"
+
+"<div class='card'>"
+"<div class='card-title'>💡 How Debbie's Memory Works</div>"
+"<p style='font-size:.8rem;color:#999;line-height:1.6'>"
+"<b style='color:#06d6a0'>Short-term:</b> Last 20 turns (user + AI) kept in RAM "
+"and injected into every new conversation as context, so Debbie always knows what "
+"was just discussed.<br><br>"
+"<b style='color:#06d6a0'>Long-term facts:</b> You can say <em>'Remember that my name is Alice'</em> "
+"or <em>'Remember I have a cat named Pixel'</em> and Debbie will save it to NVS flash "
+"— it persists across reboots.<br><br>"
+"<b style='color:#06d6a0'>Companion RAG:</b> When a companion server is configured, "
+"all conversation history is stored there in a searchable SQLite database. When you ask "
+"something, relevant past conversations are retrieved and added to the AI context "
+"— making Debbie smarter over time.<br><br>"
+"<b style='color:#06d6a0'>Voice commands:</b> <em>'Remember that...'</em> / "
+"<em>'What do you know about me?'</em> / <em>'Forget everything'</em>"
+"</p>"
+"</div>"
+"</div>"
+
+/* Sticky save bar */
+"<div class='btn-bar'>"
+"<button class='btn-save' onclick='save()'>💾 Save All Settings</button>"
+"</div>"
+"<div id='msg' class='msg' style='position:fixed;bottom:64px;left:12px;right:12px;z-index:200'></div>"
+
+"<script>"
+/* ── Provider selection ─── */
+"var PROVIDERS=['openai','anthropic','groq','openrouter','ollama'];"
+"var MODELS={"
+" openai:'gpt-4o',"
+" anthropic:'claude-3-5-sonnet-20241022',"
+" groq:'llama-3.3-70b-versatile',"
+" openrouter:'',"
+" ollama:'llama3'"
+"};"
+"function selectProvider(p){"
+" PROVIDERS.forEach(function(x){"
+"  var c=document.getElementById('pcard_'+x);"
+"  if(c)c.className='llm-card'+(x===p?' sel':'');"
+"  var d=document.getElementById('card_'+x);"
+"  if(d)d.style.display=(x===p?'':'none');"
+" });"
+" document.getElementById('llm_provider').value=p;"
+"}"
+
+/* ── Tab switching ─── */
+"var tabs=document.querySelectorAll('.tab');"
+"var pages=document.querySelectorAll('.page');"
+"function showTab(i){"
+" tabs.forEach(function(t,j){t.className='tab'+(i===j?' active':'');});"
+" pages.forEach(function(p,j){p.className='page'+(i===j?' active':'');});"
+" if(i===4)loadStatus();"
+" if(i===5)loadMemStats();"
+"}"
+
+/* ── Helpers ─── */
+"function g(id){var el=document.getElementById(id);if(!el)return '';return el.value||'';}"
+"function gc(id){var el=document.getElementById(id);return el?el.checked:false;}"
+"function s(id,v){var el=document.getElementById(id);if(el&&v!==undefined&&v!==null)el.value=v;}"
+"function sc(id,v){var el=document.getElementById(id);if(el)el.checked=!!v;}"
+
+/* ── Get model string based on provider ─── */
+"function getModel(){"
+" var p=g('llm_provider');"
+" if(p==='openai')return g('oai_model');"
+" if(p==='anthropic')return g('anthropic_model');"
+" if(p==='groq')return g('groq_model');"
+" if(p==='openrouter')return g('or_model');"
+" if(p==='ollama')return g('local_llm_model');"
+" return '';"
+"}"
+
+/* ── Save ─── */
+"function save(){"
+" var p=g('llm_provider');"
+" var d={"
+"  ssid:g('ssid'),pass:g('pass'),"
+"  ssid2:g('ssid2'),pass2:g('pass2'),"
+"  ssid3:g('ssid3'),pass3:g('pass3'),"
+"  bt_en:gc('bt_en'),ble_name:g('ble_name'),"
+"  companion_url:g('companion_url'),"
+"  llm_provider:p,llm_model:getModel(),"
+"  oai_key:g('oai_key'),"
+"  anthropic_key:g('anthropic_key'),"
+"  groq_key:g('groq_key'),"
+"  or_key:g('or_key'),"
+"  local_llm_url:g('local_llm_url'),"
+"  local_llm_model:g('local_llm_model'),"
+"  agent_url:g('agent_url'),use_agent:gc('use_agent'),"
+"  name:g('name'),sys_prompt:g('sys_prompt'),"
+"  voice_style:g('voice_style'),resp_len:g('resp_len'),"
+"  notifs_en:gc('notifs_en'),notif_wa:gc('notif_wa'),"
+"  notif_em:gc('notif_em'),notif_sp:gc('notif_sp'),"
+"  volume:parseInt(g('volume'))||75,"
+"  vad_threshold:parseInt(g('vad_thresh'))||300,"
+"  cam_en:gc('cam_en'),"
+"  mem_en:gc('mem_en'),"
+"  mem_rag:gc('mem_rag'),"
+"  mem_turns:parseInt(g('mem_turns'))||20"
+" };"
+" fetch('/configure',{method:'POST',"
+"  headers:{'Content-Type':'application/json'},body:JSON.stringify(d)})"
+" .then(function(r){return r.json();})"
+" .then(function(j){showMsg(j.ok?'ok':'err',j.msg||'Saved!');loadStatus();})"
+" .catch(function(e){showMsg('err',''+e);});"
+"}"
+
+/* ── Reset ─── */
+"function doReset(){"
+" if(!confirm('Factory reset Debbie? All settings will be erased.'))return;"
+" fetch('/reset',{method:'POST'})"
+" .then(function(){showMsg('ok','Resetting and rebooting...');});"
+"}"
+
+/* ── Default prompt ─── */
+"var DEF_PROMPT='You are Debbie, a warm and knowledgeable AI companion. "
+"You have a friendly, upbeat personality and love helping with anything. "
+"Speak naturally and concisely.';"
+"function resetPrompt(){s('sys_prompt',DEF_PROMPT);}"
+
+/* ── Message ─── */
+"function showMsg(cls,txt){"
+" var el=document.getElementById('msg');"
+" el.className='msg '+cls;el.textContent=txt;"
+" setTimeout(function(){el.className='msg';},4000);"
+"}"
+
+/* ── Status ─── */
+"function loadStatus(){"
+" fetch('/status').then(function(r){return r.json();})"
+" .then(function(j){"
+"  var sb=document.getElementById('status_bar');"
+"  if(!sb)return;"
+"  sb.innerHTML="
+"   '<span><span class=\"dot '+(j.wifi_ok?'green':'red')+'\" ></span>WiFi: '+(j.wifi_ok?'Connected':'Offline')+'</span>'"
+"   +'<span><span class=\"dot '+(j.bt_on?'blue':'red')+'\" ></span>BLE: '+(j.bt_on?'On':'Off')+'</span>'"
+"   +'<span>State: '+j.state+'</span>'"
+"   +'<span>LLM: '+j.llm_provider+'/'+j.llm_model+'</span>';"
+"  /* pre-fill fields from config */"
+"  if(j.ssid)s('ssid',j.ssid);"
+"  if(j.ssid2)s('ssid2',j.ssid2);"
+"  if(j.ssid3)s('ssid3',j.ssid3);"
+"  if(j.ble_name)s('ble_name',j.ble_name);"
+"  sc('bt_en',j.bt_en);"
+"  if(j.companion_url)s('companion_url',j.companion_url);"
+"  if(j.llm_provider){selectProvider(j.llm_provider);}"
+"  if(j.llm_model){"
+"   s('oai_model',j.llm_model);"
+"   s('anthropic_model',j.llm_model);"
+"   s('groq_model',j.llm_model);"
+"   s('or_model',j.llm_model);"
+"   s('local_llm_model',j.llm_model);"
+"  }"
+"  if(j.local_llm_url)s('local_llm_url',j.local_llm_url);"
+"  if(j.agent_url)s('agent_url',j.agent_url);"
+"  sc('use_agent',j.use_agent);"
+"  if(j.name)s('name',j.name);"
+"  if(j.sys_prompt)s('sys_prompt',j.sys_prompt);"
+"  if(j.voice_style)s('voice_style',j.voice_style);"
+"  if(j.resp_len)s('resp_len',j.resp_len);"
+"  sc('notifs_en',j.notifs_en);"
+"  sc('notif_wa',j.notif_wa);"
+"  sc('notif_em',j.notif_em);"
+"  sc('notif_sp',j.notif_sp);"
+"  if(j.volume!=null)s('volume',j.volume);"
+"  if(j.vad_threshold!=null)s('vad_thresh',j.vad_threshold);"
+"  sc('cam_en',j.cam_en);"
+"  sc('mem_en',j.mem_en);"
+"  sc('mem_rag',j.mem_rag);"
+"  if(j.mem_turns!=null)s('mem_turns',j.mem_turns);"
+" }).catch(function(){});"
+"}"
+
+/* ── Memory stats & clear ─── */
+"function loadMemStats(){"
+" var sb=document.getElementById('mem_stats');"
+" if(sb)sb.innerHTML='Loading...';"
+" fetch('/memory_stats').then(function(r){return r.json();})"
+" .then(function(j){"
+"  if(!sb)return;"
+"  sb.innerHTML="
+"   '<span>💬 Turns: '+j.turn_count+'</span>'"
+"   +'<span>📌 Facts: '+j.fact_count+'</span>'"
+"   +'<span style=\"color:'+(j.companion_rag?'#06d6a0':'#777')+'\">"
+"   🔍 Companion RAG: '+(j.companion_rag?'Active':'Off')+'</span>';"
+" }).catch(function(){if(sb)sb.innerHTML='Stats unavailable';});"
+"}"
+"function clearMem(){"
+" if(!confirm('Clear all Debbie memory? This cannot be undone.'))return;"
+" fetch('/memory_clear',{method:'POST'})"
+" .then(function(){showMsg('ok','Memory cleared!');loadMemStats();})"
+" .catch(function(e){showMsg('err',''+e);});"
+"}"
+
+"loadStatus();"
+"</script></body></html>";
+
+/* ── Handlers ──────────────────────────────────────────────────────────── */
+
+static esp_err_t handler_root(httpd_req_t *req)
+{
+    httpd_resp_set_type(req, "text/html");
+    httpd_resp_send(req, SETUP_HTML, strlen(SETUP_HTML));
+    return ESP_OK;
+}
+
+static esp_err_t handler_status(httpd_req_t *req)
+{
+    cJSON *json = cJSON_CreateObject();
+    cJSON_AddStringToObject(json, "name",         g_debbie_config.debbie_name);
+    cJSON_AddStringToObject(json, "sys_prompt",   g_debbie_config.system_prompt);
+    cJSON_AddStringToObject(json, "agent_url",    g_debbie_config.agent_ws_url);
+    cJSON_AddStringToObject(json, "companion_url",g_debbie_config.companion_url);
+    cJSON_AddStringToObject(json, "llm_provider", g_debbie_config.llm_provider);
+    cJSON_AddStringToObject(json, "llm_model",    g_debbie_config.llm_model);
+    cJSON_AddStringToObject(json, "local_llm_url",g_debbie_config.local_llm_url);
+    cJSON_AddStringToObject(json, "ssid",         g_debbie_config.wifi_ssid);
+    cJSON_AddStringToObject(json, "ssid2",        g_debbie_config.wifi_ssid2);
+    cJSON_AddStringToObject(json, "ssid3",        g_debbie_config.wifi_ssid3);
+    cJSON_AddStringToObject(json, "ble_name",     g_debbie_config.ble_device_name);
+    cJSON_AddStringToObject(json, "voice_style",  g_debbie_config.voice_style);
+    cJSON_AddStringToObject(json, "resp_len",     g_debbie_config.response_length);
+    cJSON_AddNumberToObject(json, "volume",       g_debbie_config.speaker_volume);
+    cJSON_AddNumberToObject(json, "vad_threshold",g_debbie_config.vad_threshold);
+    cJSON_AddBoolToObject(json,   "wifi_ok",      wifi_manager_is_connected());
+    cJSON_AddBoolToObject(json,   "bt_en",        g_debbie_config.bluetooth_enabled);
+    cJSON_AddBoolToObject(json,   "bt_on",        g_debbie_config.bluetooth_enabled);
+    cJSON_AddBoolToObject(json,   "use_agent",    g_debbie_config.use_custom_agent);
+    cJSON_AddBoolToObject(json,   "notifs_en",    g_debbie_config.notifications_enabled);
+    cJSON_AddBoolToObject(json,   "notif_wa",     g_debbie_config.notif_whatsapp);
+    cJSON_AddBoolToObject(json,   "notif_em",     g_debbie_config.notif_email);
+    cJSON_AddBoolToObject(json,   "notif_sp",     g_debbie_config.notif_spotify);
+    cJSON_AddBoolToObject(json,   "cam_en",       g_debbie_config.camera_enabled);
+    cJSON_AddBoolToObject(json,   "mem_en",       g_debbie_config.memory_enabled);
+    cJSON_AddBoolToObject(json,   "mem_rag",      g_debbie_config.memory_rag_enabled);
+    cJSON_AddNumberToObject(json, "mem_turns",    g_debbie_config.memory_max_turns);
+    cJSON_AddStringToObject(json, "state",
+        g_debbie_state == DEBBIE_STATE_IDLE      ? "idle"      :
+        g_debbie_state == DEBBIE_STATE_LISTENING ? "listening" :
+        g_debbie_state == DEBBIE_STATE_THINKING  ? "thinking"  :
+        g_debbie_state == DEBBIE_STATE_SPEAKING  ? "speaking"  : "other");
+
+    char *str = cJSON_PrintUnformatted(json);
+    cJSON_Delete(json);
+    httpd_resp_set_type(req, "application/json");
+    httpd_resp_send(req, str, strlen(str));
+    free(str);
+    return ESP_OK;
+}
+
+static esp_err_t handler_configure(httpd_req_t *req)
+{
+    char *buf = malloc(req->content_len + 1);
+    if (!buf) { httpd_resp_send_500(req); return ESP_FAIL; }
+
+    int received = httpd_req_recv(req, buf, req->content_len);
+    if (received <= 0) { free(buf); httpd_resp_send_500(req); return ESP_FAIL; }
+    buf[received] = '\0';
+
+    cJSON *json = cJSON_Parse(buf);
+    free(buf);
+    if (!json) { httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, "Invalid JSON"); return ESP_FAIL; }
+
+#define GET_STR(key, dst) do { \
+    cJSON *j = cJSON_GetObjectItem(json, key); \
+    if (j && cJSON_IsString(j) && strlen(j->valuestring) > 0) \
+        strncpy(dst, j->valuestring, sizeof(dst) - 1); \
+} while (0)
+
+#define GET_BOOL(key, dst) do { \
+    cJSON *j = cJSON_GetObjectItem(json, key); \
+    if (j) dst = cJSON_IsTrue(j); \
+} while (0)
+
+    /* Network */
+    GET_STR("ssid",          g_debbie_config.wifi_ssid);
+    GET_STR("pass",          g_debbie_config.wifi_password);
+    GET_STR("ssid2",         g_debbie_config.wifi_ssid2);
+    GET_STR("pass2",         g_debbie_config.wifi_password2);
+    GET_STR("ssid3",         g_debbie_config.wifi_ssid3);
+    GET_STR("pass3",         g_debbie_config.wifi_password3);
+    GET_STR("ble_name",      g_debbie_config.ble_device_name);
+    GET_STR("companion_url", g_debbie_config.companion_url);
+    GET_BOOL("bt_en",        g_debbie_config.bluetooth_enabled);
+
+    /* LLM */
+    GET_STR("llm_provider",  g_debbie_config.llm_provider);
+    GET_STR("llm_model",     g_debbie_config.llm_model);
+    GET_STR("oai_key",       g_debbie_config.openai_api_key);
+    GET_STR("anthropic_key", g_debbie_config.anthropic_api_key);
+    GET_STR("groq_key",      g_debbie_config.groq_api_key);
+    GET_STR("or_key",        g_debbie_config.openrouter_api_key);
+    GET_STR("local_llm_url", g_debbie_config.local_llm_url);
+    GET_STR("local_llm_model",g_debbie_config.local_llm_model);
+    GET_STR("agent_url",     g_debbie_config.agent_ws_url);
+    GET_BOOL("use_agent",    g_debbie_config.use_custom_agent);
+
+    /* Personality */
+    GET_STR("name",          g_debbie_config.debbie_name);
+    GET_STR("sys_prompt",    g_debbie_config.system_prompt);
+    GET_STR("voice_style",   g_debbie_config.voice_style);
+    GET_STR("resp_len",      g_debbie_config.response_length);
+
+    /* Notifications */
+    GET_BOOL("notifs_en",    g_debbie_config.notifications_enabled);
+    GET_BOOL("notif_wa",     g_debbie_config.notif_whatsapp);
+    GET_BOOL("notif_em",     g_debbie_config.notif_email);
+    GET_BOOL("notif_sp",     g_debbie_config.notif_spotify);
+
+    /* Advanced */
+    cJSON *vol = cJSON_GetObjectItem(json, "volume");
+    if (vol && cJSON_IsNumber(vol))
+        g_debbie_config.speaker_volume = (uint8_t)vol->valuedouble;
+
+    cJSON *vad = cJSON_GetObjectItem(json, "vad_threshold");
+    if (vad && cJSON_IsNumber(vad))
+        g_debbie_config.vad_threshold = (uint16_t)vad->valuedouble;
+
+    GET_BOOL("cam_en",       g_debbie_config.camera_enabled);
+
+    /* Memory */
+    GET_BOOL("mem_en",       g_debbie_config.memory_enabled);
+    GET_BOOL("mem_rag",      g_debbie_config.memory_rag_enabled);
+    {
+        cJSON *mt = cJSON_GetObjectItem(json, "mem_turns");
+        if (mt && cJSON_IsNumber(mt) && mt->valuedouble >= 5 && mt->valuedouble <= 50)
+            g_debbie_config.memory_max_turns = (uint8_t)mt->valuedouble;
+    }
+
+    cJSON_Delete(json);
+    storage_save_config();
+
+    const char *resp = "{\"ok\":true,\"msg\":\"Settings saved!\"}";
+    httpd_resp_set_type(req, "application/json");
+    httpd_resp_send(req, resp, strlen(resp));
+
+    /* Reconnect with new credentials in background */
+    vTaskDelay(pdMS_TO_TICKS(500));
+    wifi_manager_reconnect();
+
+    return ESP_OK;
+}
+
+static esp_err_t handler_reset(httpd_req_t *req)
+{
+    storage_factory_reset();
+    httpd_resp_send(req, "{\"ok\":true}", strlen("{\"ok\":true}"));
+    vTaskDelay(pdMS_TO_TICKS(1000));
+    esp_restart();
+    return ESP_OK;
+}
+
+static esp_err_t handler_snapshot(httpd_req_t *req)
+{
+    if (!g_debbie_config.camera_enabled) {
+        httpd_resp_send_err(req, HTTPD_404_NOT_FOUND, "Camera disabled");
+        return ESP_FAIL;
+    }
+    uint8_t *jpeg = NULL;
+    size_t   len  = 0;
+    if (camera_manager_capture_jpeg(&jpeg, &len) != ESP_OK) {
+        httpd_resp_send_500(req);
+        return ESP_FAIL;
+    }
+    httpd_resp_set_type(req, "image/jpeg");
+    httpd_resp_send(req, (char *)jpeg, len);
+    camera_manager_free_frame(jpeg);
+    return ESP_OK;
+}
+
+static esp_err_t handler_memory_stats(httpd_req_t *req)
+{
+    int fact_count = 0;
+    memory_manager_get_facts(&fact_count);
+    cJSON *json = cJSON_CreateObject();
+    cJSON_AddNumberToObject(json, "turn_count",   memory_manager_turn_count());
+    cJSON_AddNumberToObject(json, "fact_count",   fact_count);
+    cJSON_AddBoolToObject(json,   "memory_enabled", g_debbie_config.memory_enabled);
+    cJSON_AddBoolToObject(json,   "companion_rag",
+        g_debbie_config.memory_rag_enabled &&
+        strlen(g_debbie_config.companion_url) > 0);
+    char *str = cJSON_PrintUnformatted(json);
+    cJSON_Delete(json);
+    httpd_resp_set_type(req, "application/json");
+    httpd_resp_send(req, str, strlen(str));
+    free(str);
+    return ESP_OK;
+}
+
+static esp_err_t handler_memory_clear(httpd_req_t *req)
+{
+    memory_manager_clear();
+    const char *resp = "{\"ok\":true,\"msg\":\"Memory cleared\"}";
+    httpd_resp_set_type(req, "application/json");
+    httpd_resp_send(req, resp, strlen(resp));
+    return ESP_OK;
+}
+
+/* -------------------------------------------------------------------------- */
+
+static httpd_handle_t s_server = NULL;
+
+esp_err_t web_server_start(void)
+{
+    httpd_config_t cfg = HTTPD_DEFAULT_CONFIG();
+    cfg.max_uri_handlers = 10;
+    cfg.stack_size       = 12288;   /* increased for BLE + WiFi coexistence overhead */
+
+    ESP_ERROR_CHECK(httpd_start(&s_server, &cfg));
+
+    const httpd_uri_t routes[] = {
+        { .uri = "/",             .method = HTTP_GET,    .handler = handler_root          },
+        { .uri = "/status",       .method = HTTP_GET,    .handler = handler_status        },
+        { .uri = "/configure",    .method = HTTP_POST,   .handler = handler_configure     },
+        { .uri = "/reset",        .method = HTTP_POST,   .handler = handler_reset         },
+        { .uri = "/snapshot",     .method = HTTP_GET,    .handler = handler_snapshot      },
+        { .uri = "/memory_stats", .method = HTTP_GET,    .handler = handler_memory_stats  },
+        { .uri = "/memory_clear", .method = HTTP_POST,   .handler = handler_memory_clear  },
+    };
+
+    for (int i = 0; i < (int)(sizeof(routes) / sizeof(routes[0])); i++) {
+        ESP_ERROR_CHECK(httpd_register_uri_handler(s_server, &routes[i]));
+    }
+
+    ESP_LOGI(TAG, "Web server started at http://%s/", DEBBIE_AP_IP);
+    return ESP_OK;
+}
+
+esp_err_t web_server_stop(void)
+{
+    if (s_server) {
+        httpd_stop(s_server);
+        s_server = NULL;
+    }
+    return ESP_OK;
+}
diff --git a/firmware/main/web_server.h b/firmware/main/web_server.h
new file mode 100644
index 0000000..c9f37f9
--- /dev/null
+++ b/firmware/main/web_server.h
@@ -0,0 +1,22 @@
+#pragma once
+#include "esp_err.h"
+
+/**
+ * @brief  Start the HTTP configuration server.
+ *
+ *  Serves the captive-portal setup page at http://192.168.4.1/ and provides
+ *  REST endpoints for configuration, status, and device control.
+ *
+ *  Endpoints:
+ *    GET  /          → Setup / status HTML page
+ *    POST /configure → Save WiFi, API key, companion URL, persona
+ *    GET  /status    → JSON device status
+ *    POST /reset     → Factory reset
+ *    GET  /snapshot  → JPEG camera snapshot (if camera enabled)
+ */
+esp_err_t web_server_start(void);
+
+/**
+ * @brief  Stop the HTTP server.
+ */
+esp_err_t web_server_stop(void);
diff --git a/firmware/main/wifi_manager.c b/firmware/main/wifi_manager.c
new file mode 100644
index 0000000..6964946
--- /dev/null
+++ b/firmware/main/wifi_manager.c
@@ -0,0 +1,192 @@
+#include "wifi_manager.h"
+#include "debbie.h"
+#include "settings.h"
+#include "storage_manager.h"
+
+#include "esp_wifi.h"
+#include "esp_event.h"
+#include "esp_log.h"
+#include "esp_netif.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+#include <string.h>
+
+static const char *TAG = "wifi";
+
+#define WIFI_CONNECTED_BIT   BIT0
+#define WIFI_FAIL_BIT        BIT1
+#define WIFI_MAX_RETRY       5
+
+static EventGroupHandle_t s_wifi_event_group;
+static int                s_retry_count = 0;
+static bool               s_connected   = false;
+
+/* -------------------------------------------------------------------------- */
+
+static void event_handler(void *arg, esp_event_base_t base,
+                           int32_t id, void *data)
+{
+    if (base == WIFI_EVENT) {
+        switch (id) {
+        case WIFI_EVENT_STA_START:
+            esp_wifi_connect();
+            break;
+        case WIFI_EVENT_STA_DISCONNECTED:
+            s_connected = false;
+            if (s_retry_count < WIFI_MAX_RETRY) {
+                esp_wifi_connect();
+                s_retry_count++;
+                ESP_LOGI(TAG, "Retrying WiFi… (%d/%d)",
+                         s_retry_count, WIFI_MAX_RETRY);
+            } else {
+                xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
+            }
+            esp_event_post(DEBBIE_EVENT_BASE, DEBBIE_EVT_WIFI_DISCONNECTED,
+                           NULL, 0, portMAX_DELAY);
+            break;
+        case WIFI_EVENT_AP_STACONNECTED:
+            ESP_LOGI(TAG, "Client connected to Debbie AP");
+            break;
+        default:
+            break;
+        }
+    } else if (base == IP_EVENT && id == IP_EVENT_STA_GOT_IP) {
+        ip_event_got_ip_t *evt = (ip_event_got_ip_t *)data;
+        ESP_LOGI(TAG, "Got IP: " IPSTR, IP2STR(&evt->ip_info.ip));
+        s_retry_count = 0;
+        s_connected   = true;
+        xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
+        esp_event_post(DEBBIE_EVENT_BASE, DEBBIE_EVT_WIFI_CONNECTED,
+                       NULL, 0, portMAX_DELAY);
+    }
+}
+
+/* -------------------------------------------------------------------------- */
+
+/**
+ * @brief  Try connecting to a single SSID/password combination.
+ *         Returns ESP_OK if connected within timeout, ESP_FAIL otherwise.
+ */
+static esp_err_t try_connect(const char *ssid, const char *password)
+{
+    if (!ssid || strlen(ssid) == 0) return ESP_FAIL;
+
+    ESP_LOGI(TAG, "Trying WiFi network: %s", ssid);
+    xEventGroupClearBits(s_wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT);
+    s_retry_count = 0;
+
+    wifi_config_t sta_config = { 0 };
+    strncpy((char *)sta_config.sta.ssid,     ssid,     sizeof(sta_config.sta.ssid) - 1);
+    strncpy((char *)sta_config.sta.password, password, sizeof(sta_config.sta.password) - 1);
+    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &sta_config));
+    esp_wifi_disconnect();
+    esp_wifi_connect();
+
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
+                                           WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
+                                           pdFALSE, pdFALSE,
+                                           pdMS_TO_TICKS(10000));
+    return (bits & WIFI_CONNECTED_BIT) ? ESP_OK : ESP_FAIL;
+}
+
+/* -------------------------------------------------------------------------- */
+
+esp_err_t wifi_manager_init(void)
+{
+    s_wifi_event_group = xEventGroupCreate();
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    esp_netif_create_default_wifi_sta();
+    esp_netif_create_default_wifi_ap();
+
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_init(&cfg));
+    ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_RAM));
+
+    ESP_ERROR_CHECK(esp_event_handler_instance_register(
+        WIFI_EVENT, ESP_EVENT_ANY_ID, event_handler, NULL, NULL));
+    ESP_ERROR_CHECK(esp_event_handler_instance_register(
+        IP_EVENT, IP_EVENT_STA_GOT_IP, event_handler, NULL, NULL));
+
+    /* AP config — always on so the config portal is reachable */
+    wifi_config_t ap_config = {
+        .ap = {
+            .ssid            = DEBBIE_AP_SSID,
+            .ssid_len        = strlen(DEBBIE_AP_SSID),
+            .password        = DEBBIE_AP_PASSWORD,
+            .max_connection  = 4,
+            .authmode        = WIFI_AUTH_OPEN,
+        },
+    };
+
+    /* Check if any network is configured */
+    bool has_network = (strlen(g_debbie_config.wifi_ssid)  > 0 ||
+                        strlen(g_debbie_config.wifi_ssid2) > 0 ||
+                        strlen(g_debbie_config.wifi_ssid3) > 0);
+
+    if (has_network) {
+        ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_APSTA));
+        ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_AP, &ap_config));
+        ESP_ERROR_CHECK(esp_wifi_start());
+
+        /* Try each saved network in priority order */
+        const char *ssids[3] = {
+            g_debbie_config.wifi_ssid,
+            g_debbie_config.wifi_ssid2,
+            g_debbie_config.wifi_ssid3,
+        };
+        const char *passwords[3] = {
+            g_debbie_config.wifi_password,
+            g_debbie_config.wifi_password2,
+            g_debbie_config.wifi_password3,
+        };
+
+        for (int i = 0; i < 3; i++) {
+            if (try_connect(ssids[i], passwords[i]) == ESP_OK) {
+                ESP_LOGI(TAG, "Connected to WiFi: %s", ssids[i]);
+                return ESP_OK;
+            }
+        }
+
+        ESP_LOGW(TAG, "All saved networks failed — staying in AP+STA mode");
+    } else {
+        /* AP-only setup mode */
+        ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_AP));
+        ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_AP, &ap_config));
+        ESP_ERROR_CHECK(esp_wifi_start());
+        ESP_LOGI(TAG, "AP-only mode — connect to '%s' and visit http://%s/",
+                 DEBBIE_AP_SSID, DEBBIE_AP_IP);
+    }
+    return ESP_FAIL;
+}
+
+bool wifi_manager_is_connected(void) { return s_connected; }
+
+esp_err_t wifi_manager_reconnect(void)
+{
+    const char *ssids[3] = {
+        g_debbie_config.wifi_ssid,
+        g_debbie_config.wifi_ssid2,
+        g_debbie_config.wifi_ssid3,
+    };
+    const char *passwords[3] = {
+        g_debbie_config.wifi_password,
+        g_debbie_config.wifi_password2,
+        g_debbie_config.wifi_password3,
+    };
+
+    for (int i = 0; i < 3; i++) {
+        if (try_connect(ssids[i], passwords[i]) == ESP_OK)
+            return ESP_OK;
+    }
+    return ESP_FAIL;
+}
+
+esp_err_t wifi_manager_set_credentials(const char *ssid, const char *password)
+{
+    strncpy(g_debbie_config.wifi_ssid,     ssid,     sizeof(g_debbie_config.wifi_ssid) - 1);
+    strncpy(g_debbie_config.wifi_password, password, sizeof(g_debbie_config.wifi_password) - 1);
+    storage_save_config();
+    return wifi_manager_reconnect();
+}
+
diff --git a/firmware/main/wifi_manager.h b/firmware/main/wifi_manager.h
new file mode 100644
index 0000000..e68a6b1
--- /dev/null
+++ b/firmware/main/wifi_manager.h
@@ -0,0 +1,30 @@
+#pragma once
+#include "esp_err.h"
+#include <stdbool.h>
+
+/**
+ * @brief  Initialise WiFi in station + AP (dual) mode.
+ *
+ *  - If WiFi credentials are saved, try to connect immediately.
+ *  - Always start the soft-AP "Debbie" for first-run configuration.
+ *  - Blocks until the STA connection succeeds, or times out and
+ *    leaves the device in AP-only setup mode.
+ *
+ * @return ESP_OK on successful STA connection, ESP_FAIL if setup required.
+ */
+esp_err_t wifi_manager_init(void);
+
+/**
+ * @brief  Return true when the device has an IP address on the STA interface.
+ */
+bool wifi_manager_is_connected(void);
+
+/**
+ * @brief  Attempt to (re)connect using stored credentials.
+ */
+esp_err_t wifi_manager_reconnect(void);
+
+/**
+ * @brief  Store new WiFi credentials and reconnect.
+ */
+esp_err_t wifi_manager_set_credentials(const char *ssid, const char *password);
diff --git a/firmware/partitions.csv b/firmware/partitions.csv
new file mode 100644
index 0000000..8b0f592
--- /dev/null
+++ b/firmware/partitions.csv
@@ -0,0 +1,8 @@
+# Debbie — Custom Partition Table
+# 16 MB flash: app0 + app1 (OTA), NVS, storage
+# Name,   Type, SubType,  Offset,   Size,  Flags
+nvs,      data, nvs,      0x9000,   0x6000,
+otadata,  data, ota,      0xf000,   0x2000,
+app0,     app,  ota_0,    0x20000,  0x5A0000,
+app1,     app,  ota_1,    0x5C0000, 0x5A0000,
+storage,  data, spiffs,   0xB80000, 0x480000,
diff --git a/firmware/sdkconfig.defaults b/firmware/sdkconfig.defaults
new file mode 100644
index 0000000..de3c848
--- /dev/null
+++ b/firmware/sdkconfig.defaults
@@ -0,0 +1,80 @@
+# Debbie — ESP-IDF default configuration
+# Adjust for your specific hardware variant
+
+# Target
+CONFIG_IDF_TARGET="esp32s3"
+
+# Flash
+CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
+
+# PSRAM (required for camera frame buffers)
+CONFIG_SPIRAM=y
+CONFIG_SPIRAM_MODE_OCT=y
+CONFIG_SPIRAM_SPEED_80M=y
+CONFIG_SPIRAM_USE_MALLOC=y
+CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=16384
+
+# CPU
+CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
+
+# WiFi
+CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=16
+CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=64
+CONFIG_ESP_WIFI_TX_BUFFER_TYPE_DYNAMIC=y
+
+# ─── Bluetooth (BLE only — ESP32-S3 does not support Classic BT) ─────────────
+CONFIG_BT_ENABLED=y
+CONFIG_BT_BLE_ENABLED=y
+CONFIG_BT_BLUEDROID_ENABLED=y
+CONFIG_BT_CLASSIC_ENABLED=n
+CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y
+CONFIG_BT_BLE_50_FEATURES_SUPPORTED=n
+CONFIG_BT_GATTS_ENABLE=y
+CONFIG_BT_GATT_MAX_SR_PROFILES=8
+CONFIG_BT_GATT_MAX_SR_ATTRIBUTES=100
+# Reserve enough heap for BLE stack
+CONFIG_BT_CTRL_BLE_MAX_ACT=10
+CONFIG_BT_CTRL_BLE_STATIC_ACL_TX_BUF_NB=0
+
+# ─── TLS ──────────────────────────────────────────────────────────────────────
+# SECURITY WARNING: The settings below are for development only.
+# For production deployments, remove CONFIG_ESP_TLS_INSECURE and
+# CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY to enable full certificate validation.
+# Without these, the device is vulnerable to man-in-the-middle attacks.
+# Development only:
+CONFIG_ESP_TLS_INSECURE=y
+CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY=y
+
+# NVS encryption (disabled for simplicity — enable for production)
+CONFIG_NVS_ENCRYPTION=n
+
+# Stack sizes (increase main task to accommodate BLE + WiFi coexistence)
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=12288
+
+# Logging
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y
+CONFIG_LOG_COLORS=y
+
+# FreeRTOS
+CONFIG_FREERTOS_HZ=1000
+CONFIG_FREERTOS_UNICORE=n
+
+# OTA
+CONFIG_OTA_ALLOW_HTTP=y
+
+# ADC (battery monitoring)
+CONFIG_ADC_CAL_EFUSE_TP_ENABLE=y
+
+# I2S
+CONFIG_I2S_SUPPRESS_DEPRECATE_WARN=y
+
+# HTTP server
+CONFIG_HTTPD_MAX_REQ_HDR_LEN=1024
+CONFIG_HTTPD_MAX_URI_LEN=512
+
+# Camera
+CONFIG_CAMERA_CORE0=n
+CONFIG_CAMERA_CORE1=y
+