From 87399c1484698349a168d44a31967684558c82b0 Mon Sep 17 00:00:00 2001
From: Martin <martin@Martins-Virtual-Machine.local>
Date: Sun, 12 Jul 2026 20:55:32 -0500
Subject: [PATCH] feat: kimi.com support, prompt_file for rich prompts,
 response capture fixes, docs

- Add kimi.com agent alongside grok.com
- Support per-task agent overrides
- Support prompt_file for multi-line/rich prompts
- Fix response capture for streaming completions
- Add GrokAuto_User_Guide.html and README examples
---
 DISCOVERY.md                    | 375 +++++++++++++++++
 GrokAuto_Email_Guide.html       |  12 +-
 GrokAuto_User_Guide.html        | 690 ++++++++++++++++++++++++++++++++
 README.md                       |  77 +++-
 SECURITY.md                     |   6 +-
 examples/config.json            |  34 ++
 examples/prompts/gmail_check.md |  15 +
 main.py                         |  58 ++-
 modules/agents/__init__.py      |  33 ++
 modules/agents/base.py          |  65 +++
 modules/agents/grok.py          | 171 ++++++++
 modules/agents/kimi.py          | 190 +++++++++
 modules/browser_ctl.py          | 108 ++++-
 modules/config_validator.py     | 107 ++++-
 modules/login_validator.py      | 164 +-------
 modules/prompt_resolver.py      | 137 +++++++
 modules/task_executor.py        | 134 +++----
 modules/types.py                |  27 ++
 pytest.ini                      |   3 +
 tests/test_agents.py            | 146 +++++++
 tests/test_browser_ctl.py       | 137 +++++++
 tests/test_config_validator.py  | 448 +++++++++++++++++++++
 tests/test_deps_checker.py      | 169 ++++++++
 tests/test_login_validator.py   |  61 +++
 tests/test_prompt_resolver.py   | 118 ++++++
 tests/test_response_writer.py   | 108 +++++
 tests/test_task_executor.py     | 231 +++++++++++
 27 files changed, 3574 insertions(+), 250 deletions(-)
 create mode 100644 DISCOVERY.md
 create mode 100644 GrokAuto_User_Guide.html
 create mode 100644 examples/config.json
 create mode 100644 examples/prompts/gmail_check.md
 create mode 100644 modules/agents/__init__.py
 create mode 100644 modules/agents/base.py
 create mode 100644 modules/agents/grok.py
 create mode 100644 modules/agents/kimi.py
 create mode 100644 modules/prompt_resolver.py
 create mode 100644 modules/types.py
 create mode 100644 pytest.ini
 create mode 100644 tests/test_agents.py
 create mode 100644 tests/test_browser_ctl.py
 create mode 100644 tests/test_config_validator.py
 create mode 100644 tests/test_deps_checker.py
 create mode 100644 tests/test_login_validator.py
 create mode 100644 tests/test_prompt_resolver.py
 create mode 100644 tests/test_response_writer.py
 create mode 100644 tests/test_task_executor.py

diff --git a/DISCOVERY.md b/DISCOVERY.md
new file mode 100644
index 0000000..5ed4ca4
--- /dev/null
+++ b/DISCOVERY.md
@@ -0,0 +1,375 @@
+# GrokAuto Discovery Notes
+
+**Host:** `dsd.890.be`  
+**User:** `grok`  
+**Project path:** `/home/grok/grokauto`  
+**Local mirror:** `/Users/martin/dsd_890_be/grokauto`
+
+GrokAuto is a headless-browser automation tool that drives `grok.com` through the Chrome DevTools Protocol (CDP). It reads tasks from a JSON config, sends each prompt to Grok, waits for the streaming response to finish, and writes the results to timestamped Markdown files.
+
+---
+
+## 1. Architecture
+
+```
+main.py
+├── modules/deps_checker.py      System dependency checks (Chrome, Python, pip, Xvfb, cron)
+├── modules/config_validator.py  JSON config parsing and validation
+├── modules/browser_ctl.py       Launch Chromium and talk CDP over WebSocket
+├── modules/login_validator.py   Heuristic grok.com login detection
+├── modules/task_executor.py     Send prompts, wait for streaming, capture response text
+└── modules/response_writer.py   Format and persist Markdown output files
+```
+
+### 1.1 `main.py`
+
+CLI orchestrator. Sub-commands:
+
+| Flag | Purpose |
+|------|---------|
+| `--diagnose` | Full dependency + configuration diagnostic |
+| `--check-deps` | Dependency report only |
+| `--validate-config` | Config report only |
+| `--run` | Execute tasks from config (default action) |
+| `--prompt "..."` | Run a single inline prompt |
+| `--task-id ID` | Run only one task from config |
+| `--setup-cron "SCHEDULE"` | Install a crontab entry |
+| `--remove-cron` | Remove the crontab entry |
+| `--list-outputs` | List saved `.md` outputs |
+
+The default action is `--run`. Execution flow:
+
+1. Validate dependencies.
+2. Validate and load config.
+3. Launch Chrome with `--remote-debugging-port=9222`.
+4. Check grok.com login state; abort if not authenticated.
+5. Run selected tasks.
+6. Save responses to `output_dir` with mode `0o600`.
+7. Print summary and close browser.
+
+### 1.2 `modules/browser_ctl.py`
+
+- Launches Chromium with `--remote-debugging-port`, `--user-data-dir`, `--headless=new`, and anti-automation flags.
+- Connects to CDP via `websocket-client`.
+- Exposes `navigate_to`, `execute_js`, `wait_for_element`, `get_page_source`, `close_browser`.
+- Pre-flight port check: refuses to launch if `127.0.0.1:debug_port` is already open.
+- Registers an `atexit` cleanup handler.
+
+### 1.3 `modules/task_executor.py`
+
+- Navigates to `https://grok.com`, waits 4s for React hydration.
+- Finds the chat input using a fallback selector chain (`contenteditable`, `textarea`, etc.).
+- Handles both ProseMirror/tiptap `contenteditable` inputs and plain `<textarea>` inputs.
+- Submits by clicking a dynamically-appearing send button, or falls back to `Enter` key events.
+- Detects completion by:
+  1. Disappearance of stop/streaming indicators.
+  2. Response text remaining stable for 3 seconds.
+  3. Hard task timeout.
+- Captures response text from markdown containers, falling back to `main`/body paragraphs.
+- Pauses 2 seconds between successful tasks.
+
+### 1.4 `modules/login_validator.py`
+
+Heuristic login check on `grok.com`:
+
+1. If a "Sign in" button/link is visible → not logged in.
+2. If account/sign-out/avatar UI is present → logged in.
+3. If auth-like cookies exist → logged in.
+4. Otherwise ambiguous.
+
+### 1.5 `modules/response_writer.py`
+
+- `write_response` → `grok_response_<task_id>_<timestamp>.md`.
+- `write_batch_results` → `grok_batch_<timestamp>.md` plus individual files.
+- All files are created with `0o600` permissions.
+
+---
+
+## 2. Configuration
+
+Live config: `/home/grok/.config/grokauto/config.json`
+
+```json
+{
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    { "id": "gmail_check", "prompt": "...", "wait_for_complete": true, "timeout_seconds": 360 },
+    { "id": "voltrader",   "prompt": "...", "wait_for_complete": true, "timeout_seconds": 360 },
+    { "id": "invest",      "prompt": "...", "wait_for_complete": true, "timeout_seconds": 360 }
+  ]
+}
+```
+
+Validation rules discovered and encoded in tests:
+
+- Required top-level fields: `chrome_profile_path`, `chrome_binary`, `debug_port`, `headless`, `output_dir`, `tasks`.
+- `debug_port` must be an integer.
+- `headless` should be boolean (warned otherwise).
+- `tasks` must be a list.
+- Each task must have a non-empty `id` and `prompt`.
+- Task `timeout_seconds` must be at least 5.
+- Empty task list produces a warning, not a failure.
+
+---
+
+## 3. Tasks
+
+| ID | Purpose | Schedule |
+|----|---------|----------|
+| `gmail_check` | Search unread Gmail, draft/send replies, remove UNREAD label | 09:00 CT daily |
+| `invest` | Screen stocks, compare to Tesla, email analysis to martin@pivetta.be | 07:00 CT daily |
+| `voltrader` | Short-term momentum trading via connected tools (Robinhood, Google Docs) | **Not currently scheduled** |
+
+The `voltrader` task is still defined in config but has been removed from cron. The most recent `voltrader` outputs are from 2026-07-10.
+
+---
+
+## 4. Cron Scheduling
+
+Current crontab for `grok@grok`:
+
+```cron
+CRON_TZ=America/Chicago
+
+# GrokAuto scheduled task
+0 9 * * * cd /home/grok/grokauto && /usr/bin/python3 /home/grok/grokauto/main.py --run --config /home/grok/.config/grokauto/config.json --task-id gmail_check >> /home/grok/.config/grokauto/cron.log 2>&1
+0 7 * * * cd /home/grok/grokauto && /usr/bin/python3 /home/grok/grokauto/main.py --run --config /home/grok/.config/grokauto/config.json --task-id invest >> /home/grok/.config/grokauto/cron.log 2>&1
+```
+
+Cron log: `/home/grok/.config/grokauto/cron.log`  
+Application log: `/home/grok/.config/grokauto/grokauto.log`
+
+Recent cron runs succeeded:
+
+- `gmail_check` on 2026-07-12 09:00 → 63.4s, SUCCESS.
+- `invest` on 2026-07-12 07:02 → SUCCESS.
+
+---
+
+## 5. Live State (as of inspection)
+
+- **Chrome for grokauto:** not running persistently; GrokAuto launches a fresh Chromium for each run and closes it afterwards. No listener on TCP `9222` between runs.
+- **Chrome for gvgrok:** a separate Chromium process is running under the `gvgrok` user with `--remote-debugging-pipe` and `--user-data-dir=/home/gvgrok/.config/chromium`. This belongs to the Google Voice → Grok gateway, not GrokAuto.
+- **Outputs:** `/home/grok/grokauto_outputs` contains timestamped Markdown files, mode `0o600`.
+- **Config dir permissions:** `drwx------` (`0o700`).
+- **Authentication:** grok.com session is valid; login validation reports "Authenticated session detected on grok.com".
+
+---
+
+## 6. Local Test Suite
+
+A `pytest` suite was added under `tests/` to document the discovered behaviour without needing a browser, network, or the remote server.
+
+Run:
+
+```bash
+cd /Users/martin/dsd_890_be/grokauto
+source .venv/bin/activate
+pytest -v
+```
+
+### Coverage
+
+| File | What is tested |
+|------|----------------|
+| `tests/test_config_validator.py` | JSON validation, required fields, type checks, profile health, port availability, task rules, `load_config` |
+| `tests/test_deps_checker.py` | Chrome detection, Python version, pip packages, Xvfb, cron status, profile directory |
+| `tests/test_browser_ctl.py` | CDP dataclasses, `_fetch_json`, `_wait_for_cdp`, `_get_ws_url`, `launch_browser` command shape, cleanup |
+| `tests/test_login_validator.py` | Login heuristics, warning text, browser launch hint |
+| `tests/test_task_executor.py` | Selector builder, `send_prompt` paths, streaming completion heuristics, response capture, task execution |
+| `tests/test_response_writer.py` | Markdown formatting, file permissions, batch summaries |
+
+All 80 tests pass.
+
+---
+
+## 7. Observations and Notes
+
+- The project is intentionally simple: no async framework, no ORM, no external database; just CDP + files.
+- `websocket-client` is imported lazily inside `_send_cdp_cmd` and `launch_browser`, so missing it surfaces as a runtime error rather than an import-time error.
+- `headless=True` combined with `xvfb_display=:99` means the tool relies on Xvfb even in headless mode.
+- Task prompts are long and include tool-calling instructions (`gmail_search`, `gmail_send_message`, `gmail_batch_modify_labels`, `search_connected_tools`, etc.). Grok must have those tools connected in the saved Chrome profile for the prompts to work.
+- The `voltrader` task references a Google Doc named "VolTrader - Current State" and Robinhood schema via `search_connected_tools`. Its removal from cron may be intentional (e.g., market-hours only, manual trigger, or deprecation).
+
+---
+
+## 8. Useful Remote Commands
+
+```bash
+# Diagnose
+ssh -i ~/.ssh/martin_dsd_890_be grok@dsd.890.be 'cd /home/grok/grokauto && python3 main.py --diagnose'
+
+# Validate config
+ssh -i ~/.ssh/martin_dsd_890_be grok@dsd.890.be 'cd /home/grok/grokauto && python3 main.py --validate-config'
+
+# Tail cron log
+ssh -i ~/.ssh/martin_dsd_890_be grok@dsd.890.be 'tail -f ~/.config/grokauto/cron.log'
+
+# List recent outputs
+ssh -i ~/.ssh/martin_dsd_890_be grok@dsd.890.be 'ls -lt ~/grokauto_outputs | head'
+```
+
+---
+
+## 9. Multi-Agent Support (grok.com + kimi.com)
+
+GrokAuto now supports pluggable chat-site agents. The default agent remains
+`grok.com` for full backward compatibility.
+
+### Agent architecture
+
+```
+modules/
+  agents/
+    base.py    # Agent Protocol + shared helpers
+    grok.py    # Grok.com implementation
+    kimi.py    # Kimi.com implementation
+    __init__.py # Registry + factory
+```
+
+Each agent encapsulates:
+
+- `base_url` — the site to navigate to.
+- `input_selectors`, `submit_selectors`, `response_container_selectors`, `streaming_indicator_selectors` — DOM selector chains.
+- `check_login(session)` — heuristic login detection.
+- `warn_not_logged_in(status)` — site-specific login instructions.
+
+New agents can be added by creating a class that satisfies the `Agent` Protocol
+and registering it in `modules/agents/__init__.py`.
+
+### Supported agents
+
+| Name | URL | Notes |
+|------|-----|-------|
+| `grok.com` | https://grok.com | Fully implemented and tested |
+| `kimi.com` | https://kimi.com | Best-effort selectors; verify against live site |
+
+Set the environment variable `KIMI_BASE_URL` to override the Kimi base URL.
+
+### Configuring agents
+
+Global default:
+
+```json
+{
+  "agent": "kimi.com",
+  ...
+}
+```
+
+Per-task override:
+
+```json
+{
+  "id": "grok_summary",
+  "agent": "grok.com",
+  "prompt": "Summarize this..."
+}
+```
+
+If a task omits `agent`, it inherits the global default.
+
+---
+
+## 10. Rich Multi-Line Prompts
+
+Prompts can be supplied in three ways:
+
+### A. Single JSON string (existing behaviour)
+
+```json
+"prompt": "Check email and..."
+```
+
+### B. JSON array of strings
+
+Each array element is trimmed and joined with `\n`:
+
+```json
+"prompt": [
+  "You are a helpful assistant.",
+  "",
+  "Check the user's Gmail for unread messages.",
+  "For each message, draft a polite reply."
+]
+```
+
+### C. External file
+
+The file path is resolved relative to the config file directory (`~` is expanded):
+
+```json
+"prompt_file": "prompts/gmail_check.md"
+```
+
+Rules:
+- A task must provide `prompt` or `prompt_file`.
+- If both are present, `prompt_file` wins.
+- Empty resolved prompts are rejected by the validator.
+
+Example config combining agents and prompt files:
+
+```json
+{
+  "agent": "grok.com",
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "gmail_check",
+      "prompt_file": "prompts/gmail_check.md",
+      "wait_for_complete": true,
+      "timeout_seconds": 360
+    },
+    {
+      "id": "kimi_summary",
+      "agent": "kimi.com",
+      "prompt": [
+        "Read the attached article.",
+        "Produce a 3-bullet summary in English."
+      ],
+      "timeout_seconds": 180
+    }
+  ]
+}
+```
+
+---
+
+## 11. Test Suite After Refactor
+
+The test suite grew from 80 to 115 tests and now covers:
+
+- `tests/test_agents.py` — Agent registry, Grok agent, Kimi agent, Protocol fakes.
+- `tests/test_prompt_resolver.py` — String, list, and file prompt resolution.
+- Updated `tests/test_config_validator.py` — Agent validation and prompt forms.
+- Updated `tests/test_task_executor.py` — Agent-injected execution.
+- Updated `tests/test_login_validator.py` — Agent-delegated login checks.
+
+Run:
+
+```bash
+cd /Users/martin/dsd_890_be/grokauto
+source .venv/bin/activate
+pytest -v
+```
+
+All 115 tests pass.
+
+---
+
+## 12. Backward Compatibility
+
+- Config files without `agent` default to `grok.com`.
+- Existing single-string `prompt` fields work unchanged.
+- Existing `grok.com` selectors and login behaviour were moved, not modified.
+- No changes to CLI arguments, output file naming, or cron format.
diff --git a/GrokAuto_Email_Guide.html b/GrokAuto_Email_Guide.html
index c4f2b54..a10d206 100644
--- a/GrokAuto_Email_Guide.html
+++ b/GrokAuto_Email_Guide.html
@@ -132,7 +132,7 @@ <h1>📧 GrokAuto Email Assistant</h1>
   <section>
     <h2><span class="step-num">1</span> SSH into your server</h2>
     <div class="code-block">
-<span class="cmd">ssh</span> your-server
+<span class="cmd">ssh</span> -i ~/.ssh/martin_dsd_890_be grok@dsd.890.be
     </div>
   </section>
 
@@ -146,12 +146,12 @@ <h2><span class="step-num">2</span> Edit the GrokAuto config</h2>
     <p>Paste this configuration (or add the task to your existing config):</p>
     <div class="code-block">
 {<br>
-&nbsp;&nbsp;<span class="arg">"chrome_profile_path"</span>: <span class="arg">"/home/user/.config/chromium/Default"</span>,<br>
+&nbsp;&nbsp;<span class="arg">"chrome_profile_path"</span>: <span class="arg">"/home/grok/.config/chromium/Default"</span>,<br>
 &nbsp;&nbsp;<span class="arg">"chrome_binary"</span>: <span class="arg">"/usr/bin/chromium"</span>,<br>
 &nbsp;&nbsp;<span class="arg">"debug_port"</span>: 9222,<br>
 &nbsp;&nbsp;<span class="arg">"headless"</span>: <span class="cmd">true</span>,<br>
 &nbsp;&nbsp;<span class="arg">"xvfb_display"</span>: <span class="arg">":99"</span>,<br>
-&nbsp;&nbsp;<span class="arg">"output_dir"</span>: <span class="arg">"/home/user/grokauto_outputs"</span>,<br>
+&nbsp;&nbsp;<span class="arg">"output_dir"</span>: <span class="arg">"/home/grok/grokauto_outputs"</span>,<br>
 &nbsp;&nbsp;<span class="arg">"tasks"</span>: [<br>
 &nbsp;&nbsp;&nbsp;&nbsp;{<br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="arg">"id"</span>: <span class="arg">"gmail_check"</span>,<br>
@@ -197,9 +197,9 @@ <h2><span class="step-num">4</span> Schedule it every 10 minutes</h2>
     <div class="code-block">
 <span class="cmd">crontab</span> -e<br><br>
 <span class="comment"># Run all tasks every 10 minutes:</span><br>
-0,10,20,30,40,50 * * * * <span class="cmd">cd</span> /home/user/grokauto && /usr/bin/python3 /home/user/grokauto/main.py --run --config /home/user/.config/grokauto/config.json <span class="cmd">&gt;&gt;</span> /home/user/.config/grokauto/cron.log <span class="cmd">2&gt;&amp;1</span><br><br>
+0,10,20,30,40,50 * * * * <span class="cmd">cd</span> /home/grok/grokauto && /usr/bin/python3 /home/grok/grokauto/main.py --run --config /home/grok/.config/grokauto/config.json <span class="cmd">&gt;&gt;</span> /home/grok/.config/grokauto/cron.log <span class="cmd">2&gt;&amp;1</span><br><br>
 <span class="comment"># OR run only a specific task:</span><br>
-0,10,20,30,40,50 * * * * <span class="cmd">cd</span> /home/user/grokauto && /usr/bin/python3 /home/user/grokauto/main.py --run --config /home/user/.config/grokauto/config.json --task-id gmail_check <span class="cmd">&gt;&gt;</span> /home/user/.config/grokauto/cron.log <span class="cmd">2&gt;&amp;1</span>
+0,10,20,30,40,50 * * * * <span class="cmd">cd</span> /home/grok/grokauto && /usr/bin/python3 /home/grok/grokauto/main.py --run --config /home/grok/.config/grokauto/config.json --task-id gmail_check <span class="cmd">&gt;&gt;</span> /home/grok/.config/grokauto/cron.log <span class="cmd">2&gt;&amp;1</span>
     </div>
 
     <p>Verify the cron job is installed:</p>
@@ -302,7 +302,7 @@ <h2>✅ Summary</h2>
 
 <footer>
   <div class="container">
-    <p>GrokAuto Email Assistant</p>
+    <p>GrokAuto Email Assistant &middot; dsd.890.be</p>
   </div>
 </footer>
 
diff --git a/GrokAuto_User_Guide.html b/GrokAuto_User_Guide.html
new file mode 100644
index 0000000..747e626
--- /dev/null
+++ b/GrokAuto_User_Guide.html
@@ -0,0 +1,690 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>GrokAuto User Guide</title>
+  <style>
+    :root {
+      --bg: #f8f9fa;
+      --text: #212529;
+      --muted: #6c757d;
+      --primary: #0d6efd;
+      --accent: #6610f2;
+      --success: #198754;
+      --warning: #fd7e14;
+      --danger: #dc3545;
+      --code-bg: #f1f3f5;
+      --border: #dee2e6;
+      --shadow: 0 2px 8px rgba(0,0,0,0.06);
+    }
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      line-height: 1.6;
+      color: var(--text);
+      background: var(--bg);
+      margin: 0;
+      padding: 0;
+    }
+    header {
+      background: linear-gradient(135deg, var(--primary), var(--accent));
+      color: white;
+      padding: 3rem 1rem;
+      text-align: center;
+    }
+    header h1 { margin: 0 0 0.5rem; font-size: 2.5rem; }
+    header p { margin: 0; opacity: 0.9; font-size: 1.1rem; }
+    nav {
+      background: white;
+      border-bottom: 1px solid var(--border);
+      padding: 1rem;
+      position: sticky;
+      top: 0;
+      z-index: 10;
+      box-shadow: var(--shadow);
+    }
+    nav ul {
+      list-style: none;
+      max-width: 960px;
+      margin: 0 auto;
+      padding: 0;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.5rem 1.5rem;
+      justify-content: center;
+    }
+    nav a { color: var(--primary); text-decoration: none; font-weight: 500; }
+    nav a:hover { text-decoration: underline; }
+    main { max-width: 960px; margin: 0 auto; padding: 2rem 1rem; }
+    section { background: white; border-radius: 8px; padding: 2rem; margin-bottom: 2rem; box-shadow: var(--shadow); }
+    h2 { color: var(--primary); margin-top: 0; border-bottom: 2px solid var(--border); padding-bottom: 0.5rem; }
+    h3 { color: var(--accent); margin-top: 1.75rem; }
+    h4 { color: var(--text); margin-top: 1.5rem; }
+    p { margin: 0.75rem 0; }
+    ul, ol { margin: 0.75rem 0; padding-left: 1.5rem; }
+    li { margin: 0.35rem 0; }
+    code {
+      background: var(--code-bg);
+      padding: 0.15rem 0.35rem;
+      border-radius: 4px;
+      font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+      font-size: 0.9em;
+    }
+    pre {
+      background: #212529;
+      color: #f8f9fa;
+      padding: 1rem;
+      border-radius: 8px;
+      overflow-x: auto;
+      font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+      font-size: 0.9rem;
+      line-height: 1.5;
+    }
+    pre code { background: transparent; padding: 0; color: inherit; }
+    .file-label {
+      display: block;
+      background: #e9ecef;
+      color: var(--text);
+      padding: 0.35rem 0.75rem;
+      border-radius: 4px 4px 0 0;
+      font-size: 0.85rem;
+      font-weight: 600;
+      margin-bottom: -0.5rem;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 1rem 0;
+      font-size: 0.95rem;
+    }
+    th, td {
+      border: 1px solid var(--border);
+      padding: 0.6rem 0.8rem;
+      text-align: left;
+      vertical-align: top;
+    }
+    th { background: #f1f3f5; font-weight: 600; }
+    .note {
+      background: #e7f3ff;
+      border-left: 4px solid var(--primary);
+      padding: 1rem;
+      border-radius: 4px;
+      margin: 1rem 0;
+    }
+    .warning {
+      background: #fff3cd;
+      border-left: 4px solid var(--warning);
+      padding: 1rem;
+      border-radius: 4px;
+      margin: 1rem 0;
+    }
+    .tip {
+      background: #d1e7dd;
+      border-left: 4px solid var(--success);
+      padding: 1rem;
+      border-radius: 4px;
+      margin: 1rem 0;
+    }
+    .permalink { float: right; font-size: 0.8rem; color: var(--muted); }
+    footer {
+      text-align: center;
+      padding: 2rem 1rem;
+      color: var(--muted);
+      font-size: 0.9rem;
+    }
+    @media (max-width: 600px) {
+      header h1 { font-size: 1.8rem; }
+      section { padding: 1.25rem; }
+      nav ul { justify-content: flex-start; }
+    }
+  </style>
+</head>
+<body>
+
+<header>
+  <h1>GrokAuto User Guide</h1>
+  <p>Headless browser automation for grok.com, kimi.com, and compatible chat sites</p>
+</header>
+
+<nav>
+  <ul>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#install">Install</a></li>
+    <li><a href="#config">Configuration</a></li>
+    <li><a href="#agents">Agents</a></li>
+    <li><a href="#prompts">Prompts</a></li>
+    <li><a href="#auth">Authentication</a></li>
+    <li><a href="#run">Run</a></li>
+    <li><a href="#cron">Cron</a></li>
+    <li><a href="#examples">Examples</a></li>
+    <li><a href="#troubleshoot">Troubleshooting</a></li>
+  </ul>
+</nav>
+
+<main>
+
+<section id="overview">
+  <h2>Overview <a class="permalink" href="#overview">#</a></h2>
+  <p>
+    GrokAuto launches a Chromium browser with the Chrome DevTools Protocol (CDP),
+    verifies that you are logged in to a supported chat site, sends one or more
+    prompts, waits for each streaming response to finish, and saves the results
+    as timestamped Markdown files.
+  </p>
+  <p>
+    It is designed to run unattended on Ubuntu/Debian servers, but works anywhere
+    Chromium and Python 3 are available.
+  </p>
+
+  <h3>Supported chat sites</h3>
+  <table>
+    <tr><th>Agent</th><th>Site</th><th>Notes</th></tr>
+    <tr><td><code>grok.com</code></td><td><a href="https://grok.com">https://grok.com</a></td><td>Requires X (Twitter) login</td></tr>
+    <tr><td><code>kimi.com</code></td><td><a href="https://www.kimi.com">https://www.kimi.com</a></td><td>Requires Kimi/Moonshot login</td></tr>
+  </table>
+</section>
+
+<section id="install">
+  <h2>Installation <a class="permalink" href="#install">#</a></h2>
+
+  <h3>Automated setup</h3>
+  <pre><code>git clone https://github.com/yourname/grokauto.git
+cd grokauto
+bash setup.sh</code></pre>
+  <p><code>setup.sh</code> creates <code>~/.config/grokauto/</code>, <code>~/grokauto_outputs/</code>, a default
+  <code>config.json</code>, and a <code>grokauto</code> wrapper in <code>~/.local/bin/</code>.</p>
+
+  <h3>Manual setup</h3>
+  <pre><code>pip3 install websocket-client requests
+mkdir -p ~/.config/grokauto ~/grokauto_outputs
+cp config.json.template ~/.config/grokauto/config.json
+# Edit ~/.config/grokauto/config.json</code></pre>
+
+  <h3>System requirements</h3>
+  <ul>
+    <li>Ubuntu 22.04+ / Debian 12+ (other Linux distributions may work)</li>
+    <li>Python 3.8+</li>
+    <li>Chromium or Google Chrome</li>
+    <li><code>xvfb</code> for headless operation on a server without a display</li>
+  </ul>
+</section>
+
+<section id="config">
+  <h2>Configuration file <a class="permalink" href="#config">#</a></h2>
+  <p>
+    GrokAuto reads <code>~/.config/grokauto/config.json</code> by default. You can override
+    the path with <code>--config /path/to/config.json</code>.
+  </p>
+
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "chrome_profile_path": "/home/YOURUSER/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/YOURUSER/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "task_001",
+      "prompt": "What are the latest developments in AI?",
+      "wait_for_complete": true,
+      "timeout_seconds": 120
+    }
+  ]
+}</code></pre>
+
+  <h3>Global settings</h3>
+  <table>
+    <tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
+    <tr><td><code>agent</code></td><td>string</td><td>no</td><td>Default agent: <code>grok.com</code> or <code>kimi.com</code>. Defaults to <code>grok.com</code>.</td></tr>
+    <tr><td><code>chrome_profile_path</code></td><td>string</td><td>yes</td><td>Path to the Chrome profile directory (the <code>Default</code> folder).</td></tr>
+    <tr><td><code>chrome_binary</code></td><td>string</td><td>yes</td><td>Path to the Chromium/Chrome executable.</td></tr>
+    <tr><td><code>debug_port</code></td><td>int</td><td>yes</td><td>Local CDP port, e.g. <code>9222</code>.</td></tr>
+    <tr><td><code>headless</code></td><td>bool</td><td>yes</td><td>Run Chrome without a GUI. Set to <code>false</code> if you need to watch the browser.</td></tr>
+    <tr><td><code>xvfb_display</code></td><td>string</td><td>yes*</td><td>Xvfb display, e.g. <code>:99</code>. Required when <code>headless</code> is <code>true</code> on a server.</td></tr>
+    <tr><td><code>output_dir</code></td><td>string</td><td>yes</td><td>Directory for saved Markdown responses.</td></tr>
+    <tr><td><code>tasks</code></td><td>array</td><td>yes</td><td>List of task objects.</td></tr>
+  </table>
+
+  <h3>Task settings</h3>
+  <table>
+    <tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
+    <tr><td><code>id</code></td><td>string</td><td>yes</td><td>Unique task identifier. Used with <code>--task-id</code>.</td></tr>
+    <tr><td><code>prompt</code></td><td>string | array</td><td>yes*</td><td>The prompt text. Use an array for multi-line prompts.</td></tr>
+    <tr><td><code>prompt_file</code></td><td>string</td><td>yes*</td><td>Path to a file containing the prompt. Overrides <code>prompt</code> if both are set.</td></tr>
+    <tr><td><code>agent</code></td><td>string</td><td>no</td><td>Override the global agent for this task only.</td></tr>
+    <tr><td><code>wait_for_complete</code></td><td>bool</td><td>no</td><td>Wait for the streaming response to finish. Default <code>true</code>.</td></tr>
+    <tr><td><code>timeout_seconds</code></td><td>int</td><td>no</td><td>Maximum wait time. Default <code>120</code>.</td></tr>
+  </table>
+  <p class="note">* You must provide either <code>prompt</code> or <code>prompt_file</code> for each task.</p>
+</section>
+
+<section id="agents">
+  <h2>Choosing an agent <a class="permalink" href="#agents">#</a></h2>
+  <p>
+    Set the default agent globally and override it per task when you want to talk
+    to more than one service in the same run.
+  </p>
+
+  <h3>Default agent</h3>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "kimi.com",
+  "tasks": [
+    { "id": "t1", "prompt": "Hello Kimi" }
+  ]
+}</code></pre>
+
+  <h3>Mixed agents in one config</h3>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "tasks": [
+    { "id": "ask_grok", "prompt": "Summarize quantum computing" },
+    { "id": "ask_kimi", "prompt": "Explain the same thing in Chinese", "agent": "kimi.com" }
+  ]
+}</code></pre>
+
+  <h3>Agent-specific cookies</h3>
+  <p>
+    GrokAuto looks for exported cookies named <code>cookies_&lt;agent&gt;.json</code> in the
+    same directory as your config file. For example:
+  </p>
+  <ul>
+    <li><code>~/.config/grokauto/cookies_grok.json</code> for <code>grok.com</code></li>
+    <li><code>~/.config/grokauto/cookies_kimi.json</code> for <code>kimi.com</code></li>
+  </ul>
+  <p>
+    These files are optional. If they exist, GrokAuto injects the cookies into
+    the browser session before checking login state.
+  </p>
+</section>
+
+<section id="prompts">
+  <h2>Prompt formats <a class="permalink" href="#prompts">#</a></h2>
+  <p>
+    A task prompt can be supplied as a single-line string, a JSON array, or an
+    external file. For anything with multiple paragraphs, code blocks, or
+    numbered lists, use a <strong>prompt file</strong> — it keeps the config small
+    and lets you write normal Markdown without JSON quoting or commas.
+  </p>
+
+  <h3>Recommended: external prompt file</h3>
+  <p>
+    Put the prompt in a <code>.md</code> or <code>.txt</code> file next to your config and
+    reference it with <code>prompt_file</code>. The path is relative to the config
+    directory unless absolute.
+  </p>
+
+  <div class="file-label">~/.config/grokauto/prompts/code_review.md</div>
+  <pre><code>You are a senior Python engineer.
+
+Review the function below and suggest one concrete improvement:
+
+```python
+def greet(name):
+    print('Hello, ' + name + '!')
+```</code></pre>
+
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "kimi.com",
+  "tasks": [
+    {
+      "id": "code_review",
+      "prompt_file": "prompts/code_review.md"
+    }
+  ]
+}</code></pre>
+
+  <p>Another example with a detailed system persona:</p>
+
+  <div class="file-label">~/.config/grokauto/prompts/coding_assistant.md</div>
+  <pre><code>You are an expert Python tutor. Your answers follow these rules:
+
+1. Always explain the "why", not just the "how".
+2. Provide a complete, runnable code example.
+3. Mention any common pitfalls.
+
+Now help with the user's question below.</code></pre>
+
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "tasks": [
+    {
+      "id": "tutor_help",
+      "prompt": "How do Python decorators work?",
+      "prompt_file": "prompts/coding_assistant.md"
+    }
+  ]
+}</code></pre>
+
+  <h3>Single-line string</h3>
+  <p>Use this for one-line questions only.</p>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "tasks": [
+    {
+      "id": "simple",
+      "prompt": "What is the capital of France?"
+    }
+  ]
+}</code></pre>
+
+  <h3>Multi-line JSON array (short prompts only)</h3>
+  <p>
+    If a prompt is only a few lines and you want to keep everything in
+    <code>config.json</code>, use a JSON array. Each element becomes one line,
+    empty strings become blank lines, and leading indentation is preserved.
+  </p>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "kimi.com",
+  "tasks": [
+    {
+      "id": "short_review",
+      "prompt": [
+        "You are a senior Python engineer.",
+        "",
+        "Review this function and suggest one improvement:",
+        "",
+        "```python",
+        "def greet(name):",
+        "    print('Hello, ' + name + '!')",
+        "```"
+      ]
+    }
+  ]
+}</code></pre>
+  <div class="tip">
+    For longer or richer prompts, prefer a <code>prompt_file</code>. It avoids JSON
+    quoting, trailing commas, and escaped backticks, and it is much easier to
+    edit and review.
+  </div>
+
+  <h3>Inline prompt vs. file priority</h3>
+  <p>
+    If both <code>prompt</code> and <code>prompt_file</code> are set, the file wins.
+  </p>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "tasks": [
+    {
+      "id": "priority_demo",
+      "prompt": "This is ignored.",
+      "prompt_file": "prompts/code_review.md"
+    }
+  ]
+}</code></pre>
+</section>
+
+<section id="auth">
+  <h2>Authentication <a class="permalink" href="#auth">#</a></h2>
+  <p>
+    GrokAuto needs a logged-in browser session. The recommended approach depends
+    on whether you can log in interactively on the machine where GrokAuto runs.
+  </p>
+
+  <h3>Option A: Log in directly on the server (recommended)</h3>
+  <ol>
+    <li>Launch Chrome on the server's desktop or via X11/VNC:</li>
+  </ol>
+  <pre><code>/usr/bin/chromium \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/home/YOURUSER/.config/chromium \
+  --password-store=basic \
+  --use-mock-keychain</code></pre>
+  <ol start="2">
+    <li>Navigate to the agent's site (e.g. <code>https://www.kimi.com</code>) and sign in.</li>
+    <li>Close the browser so the cookie SQLite store flushes to disk.</li>
+    <li>GrokAuto will reuse the session on the next run.</li>
+  </ol>
+
+  <h3>Option B: Import cookies from another device</h3>
+  <p>
+    If you are already logged in on another computer, you can export the cookies
+    with Chrome DevTools Protocol and copy them to the server.
+  </p>
+  <ol>
+    <li>On the logged-in machine, launch Chrome with remote debugging:</li>
+  </ol>
+  <pre><code>/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-export-profile</code></pre>
+  <ol start="2">
+    <li>Use a CDP script to call <code>Network.getAllCookies</code> for the target site and save the JSON array.</li>
+    <li>Copy the file to the server as <code>~/.config/grokauto/cookies_&lt;agent&gt;.json</code>.</li>
+  </ol>
+  <div class="warning">
+    <strong>Note:</strong> Some services bind sessions to the originating device or IP.
+    If imported cookies are rejected, log in directly on the server instead.
+  </div>
+
+  <h3>Option C: Headless interactive login</h3>
+  <p>
+    Set <code>"headless": false</code> in the config, start an Xvfb or VNC desktop on the
+    server, launch Chrome manually, sign in, then switch back to
+    <code>"headless": true</code> for unattended runs.
+  </p>
+</section>
+
+<section id="run">
+  <h2>Running GrokAuto <a class="permalink" href="#run">#</a></h2>
+
+  <h3>Diagnostic</h3>
+  <pre><code>python3 main.py --diagnose</code></pre>
+
+  <h3>Run all tasks</h3>
+  <pre><code>python3 main.py --run</code></pre>
+  <p>or, if <code>~/.local/bin</code> is on your PATH:</p>
+  <pre><code>grokauto --run</code></pre>
+
+  <h3>Run one task</h3>
+  <pre><code>python3 main.py --run --task-id code_review</code></pre>
+
+  <h3>Single inline prompt</h3>
+  <pre><code>python3 main.py --prompt "Explain recursion"</code></pre>
+
+  <h3>Use a different config file</h3>
+  <pre><code>python3 main.py --run --config /path/to/config.json</code></pre>
+
+  <h3>Output</h3>
+  <p>
+    Results are saved as Markdown files in <code>output_dir</code>:
+  </p>
+  <pre><code>~/grokauto_outputs/
+├── grok_response_task_001_20260712_143022.md
+├── grok_response_code_review_20260712_143145.md
+└── grok_batch_20260712_150000.md</code></pre>
+</section>
+
+<section id="cron">
+  <h2>Scheduling with cron <a class="permalink" href="#cron">#</a></h2>
+
+  <h3>Install a cron job</h3>
+  <pre><code>python3 main.py --setup-cron "0 9 * * *"</code></pre>
+  <p>Runs all tasks every day at 09:00.</p>
+
+  <h3>Schedule one task</h3>
+  <pre><code>python3 main.py --setup-cron "*/10 * * * *" --task-id code_review</code></pre>
+  <p>Runs <code>code_review</code> every 10 minutes.</p>
+
+  <h3>Remove the cron job</h3>
+  <pre><code>python3 main.py --remove-cron</code></pre>
+
+  <h3>Cron logs</h3>
+  <p>
+    Scheduled output is appended to <code>~/.config/grokauto/cron.log</code>.
+  </p>
+</section>
+
+<section id="examples">
+  <h2>Complete configuration examples <a class="permalink" href="#examples">#</a></h2>
+
+  <h3>1. Single Grok task</h3>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "news_summary",
+      "prompt": "Summarize today's top AI news.",
+      "timeout_seconds": 180
+    }
+  ]
+}</code></pre>
+
+  <h3>2. Single Kimi task with a prompt file</h3>
+  <div class="file-label">~/.config/grokauto/prompts/kimi_review.md</div>
+  <pre><code>You are a senior Python engineer.
+
+Review this function and suggest one improvement:
+
+```python
+def greet(name):
+    print('Hello, ' + name + '!')
+```</code></pre>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "kimi.com",
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "kimi_code_review",
+      "prompt_file": "prompts/kimi_review.md",
+      "timeout_seconds": 120
+    }
+  ]
+}</code></pre>
+
+  <h3>3. Mixed agents in one run</h3>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "grok_draft",
+      "prompt": "Draft a one-paragraph email asking for a meeting delay."
+    },
+    {
+      "id": "kimi_translate",
+      "agent": "kimi.com",
+      "prompt": "Translate the following text to Chinese:\n\nHello, could we reschedule our meeting to next week?"
+    }
+  ]
+}</code></pre>
+
+  <h3>4. Prompt file with a long system prompt</h3>
+  <div class="file-label">~/.config/grokauto/prompts/coding_assistant.md</div>
+  <pre><code>You are an expert Python tutor. Your answers follow these rules:
+
+1. Always explain the "why", not just the "how".
+2. Provide a complete, runnable code example.
+3. Mention any common pitfalls.
+
+Now help with the user's question below.</code></pre>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "tasks": [
+    {
+      "id": "tutor_help",
+      "prompt": "How do Python decorators work?",
+      "prompt_file": "prompts/coding_assistant.md"
+    }
+  ]
+}</code></pre>
+
+  <h3>5. Quick task without waiting</h3>
+  <p>
+    For tasks where you only need to send the prompt and do not need to capture
+    the response, set <code>wait_for_complete</code> to <code>false</code>.
+  </p>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "grok.com",
+  "tasks": [
+    {
+      "id": "fire_and_forget",
+      "prompt": "Remind me to review the quarterly report.",
+      "wait_for_complete": false,
+      "timeout_seconds": 30
+    }
+  ]
+}</code></pre>
+
+  <h3>6. Daily cron job</h3>
+  <div class="file-label">~/.config/grokauto/config.json</div>
+  <pre><code>{
+  "agent": "kimi.com",
+  "tasks": [
+    {
+      "id": "daily_summary",
+      "prompt_file": "prompts/daily_summary.md"
+    }
+  ]
+}</code></pre>
+  <pre><code>python3 main.py --setup-cron "0 8 * * *" --task-id daily_summary</code></pre>
+</section>
+
+<section id="troubleshoot">
+  <h2>Troubleshooting <a class="permalink" href="#troubleshoot">#</a></h2>
+
+  <table>
+    <tr><th>Issue</th><th>Cause / fix</th></tr>
+    <tr>
+      <td><code>Not logged in to grok.com</code> / <code>kimi.com</code></td>
+      <td>Sign in manually on the server once, then close the browser. If using imported cookies, the service may have rejected them; log in directly instead.</td>
+    </tr>
+    <tr>
+      <td><code>Port 9222 is already in use</code></td>
+      <td>Kill the existing Chrome: <code>pkill -u $(whoami) chromium</code> or <code>lsof -ti:9222 | xargs kill -9</code>.</td>
+    </tr>
+    <tr>
+      <td>Response is empty or truncated</td>
+      <td>Increase <code>timeout_seconds</code>. Some models stream slowly.</td>
+    </tr>
+    <tr>
+      <td>Chrome fails to start in headless mode</td>
+      <td>Ensure <code>xvfb</code> is installed and running on the configured <code>xvfb_display</code>. Or set <code>headless: false</code> and use a real/VNC display.</td>
+    </tr>
+    <tr>
+      <td>Multi-line prompt loses indentation</td>
+      <td>Use a JSON array, not a single string with <code>\n</code>. Each array element preserves its leading whitespace.</td>
+    </tr>
+    <tr>
+      <td>Task output file is duplicated</td>
+      <td>Update GrokAuto. If a site changes its DOM, the agent selectors may need adjustment in <code>modules/agents/&lt;agent&gt;.py</code>.</td>
+    </tr>
+  </table>
+</section>
+
+</main>
+
+<footer>
+  <p>GrokAuto User Guide &middot; Generated for the dsd_890_be/grokauto project</p>
+</footer>
+
+</body>
+</html>
diff --git a/README.md b/README.md
index b81a64f..09e6de2 100644
--- a/README.md
+++ b/README.md
@@ -123,10 +123,82 @@ Edit `~/.config/grokauto/config.json`:
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | Unique task identifier |
-| `prompt` | string | The message sent to Grok |
+| `prompt` | string \| list[string] | The message sent to the agent. Use a list for multi-line / rich prompts. |
+| `prompt_file` | string | Path to a file containing the prompt (relative to config dir or absolute). Takes priority over `prompt`. |
+| `agent` | string | Optional per-task agent override (e.g. `"grok.com"`, `"kimi.com"`). Defaults to the top-level `agent`. |
 | `wait_for_complete` | boolean | Wait for streaming response to finish |
 | `timeout_seconds` | int | Maximum time to wait for a response |
 
+### Multi-line / rich prompts
+
+For prompts with paragraphs, code blocks, or numbered lists, the easiest option
+is a **prompt file**. Write normal Markdown in a separate file and reference it
+with `prompt_file`:
+
+`~/.config/grokauto/prompts/code_review.md`:
+```markdown
+You are a senior Python engineer.
+
+Review the function below and suggest one concrete improvement:
+
+```python
+def greet(name):
+    print('Hello, ' + name + '!')
+```
+```
+
+`~/.config/grokauto/config.json`:
+```json
+{
+  "agent": "kimi.com",
+  "tasks": [
+    {
+      "id": "code_review",
+      "prompt_file": "prompts/code_review.md"
+    }
+  ]
+}
+```
+
+If a prompt is only a few lines, you can also use a JSON array inline. Each
+element becomes one line, empty strings become blank lines, and leading
+indentation is preserved:
+
+```json
+{
+  "agent": "kimi.com",
+  "tasks": [
+    {
+      "id": "short_review",
+      "prompt": [
+        "You are a senior Python engineer.",
+        "",
+        "Review this function and suggest one improvement:",
+        "",
+        "```python",
+        "def greet(name):",
+        "    print('Hello, ' + name + '!')",
+        "```"
+      ]
+    }
+  ]
+}
+```
+
+### Selecting the agent
+
+Set the default agent at the top level of `config.json` and override per task when needed:
+
+```json
+{
+  "agent": "grok.com",
+  "tasks": [
+    { "id": "t1", "prompt": "Hello Grok" },
+    { "id": "t2", "prompt": "Hello Kimi", "agent": "kimi.com" }
+  ]
+}
+```
+
 ---
 
 ## Usage
@@ -202,7 +274,8 @@ Cron Scheduler ──► main.py (orchestrator)
 See [SECURITY.md](SECURITY.md) for the full security review, threat model, and deployment checklist.
 
 Key points:
-- Chrome profile credentials are **never modified or extracted**
+- Chrome profile credentials are **never transmitted off the machine**.
+- GrokAuto can optionally import exported CDP cookies from `cookies_<agent>.json` files in the config directory; these files are created with restrictive permissions.
 - CDP port binds to **localhost only** (127.0.0.1)
 - Output files are created with `chmod 600`
 - No credentials are stored in config files
diff --git a/SECURITY.md b/SECURITY.md
index d1c1ba7..f918314 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -75,8 +75,8 @@ GrokAuto is a headless browser automation tool that controls Chrome/Chromium via
 - **Mitigation:** Add a `MAX_TASKS_PER_RUN` constant (e.g., 10) and reject configs that exceed it. Document responsible usage.
 
 #### MED-003: Weak VNC Password (Deployment Artifact)
-- **Location:** Deployment artifact — VNC setup
-- **Issue:** The TigerVNC server was configured with a weak password during installation. This is a dictionary-attacking candidate.
+- **Location:** `DSD_890_BE-ACTIONS-TAKEN` — VNC setup for dsd.890.be
+- **Issue:** The TigerVNC server was configured with password `grokpwd` during installation. This is a dictionary-attacking candidate.
 - **Risk:** Unauthorized remote desktop access if the VNC tunnel is misconfigured or the SSH key is compromised.
 - **Mitigation:** Rotate the VNC password to a strong random string:
   ```bash
@@ -123,7 +123,7 @@ GrokAuto is a headless browser automation tool that controls Chrome/Chromium via
 | **P1** | Restrict log file permissions to 600 | 10 min |
 | **P1** | Use `shlex.quote()` for cron command paths | 10 min |
 | **P1** | Add `MAX_TASKS_PER_RUN` limit | 15 min |
-| **P2** | Rotate VNC password on your server | 5 min |
+| **P2** | Rotate VNC password on dsd.890.be | 5 min |
 | **P2** | Harden Chrome profile directory permissions | 5 min |
 | **P2** | Replace `shell=True` in `_run_shell` | 10 min |
 
diff --git a/examples/config.json b/examples/config.json
new file mode 100644
index 0000000..96a3417
--- /dev/null
+++ b/examples/config.json
@@ -0,0 +1,34 @@
+{
+  "agent": "grok.com",
+  "chrome_profile_path": "/home/grok/.config/chromium/Default",
+  "chrome_binary": "/usr/bin/chromium",
+  "debug_port": 9222,
+  "headless": true,
+  "xvfb_display": ":99",
+  "output_dir": "/home/grok/grokauto_outputs",
+  "tasks": [
+    {
+      "id": "gmail_check",
+      "prompt_file": "prompts/gmail_check.md",
+      "wait_for_complete": true,
+      "timeout_seconds": 360
+    },
+    {
+      "id": "invest",
+      "prompt": [
+        "Screen X for stocks promising imminent fast growth.",
+        "Analyze the recommended tickers and compare them to Tesla.",
+        "Draft a rich email with references and charts, then send it to martin@pivetta.be."
+      ],
+      "wait_for_complete": true,
+      "timeout_seconds": 360
+    },
+    {
+      "id": "kimi_summary",
+      "agent": "kimi.com",
+      "prompt": "Summarize the main points of today's AI news in three bullets.",
+      "wait_for_complete": true,
+      "timeout_seconds": 180
+    }
+  ]
+}
diff --git a/examples/prompts/gmail_check.md b/examples/prompts/gmail_check.md
new file mode 100644
index 0000000..91fe6b0
--- /dev/null
+++ b/examples/prompts/gmail_check.md
@@ -0,0 +1,15 @@
+Check if there are any new emails received by my connected Google email address.
+
+If there are new emails, list them with sender and subject, and draft + send an
+appropriate response to each one within the following rules:
+
+1. Reply to martin@pivetta.be, celine@normandin.be, or stella@pivetta.be.
+2. For all other messages, create a list with a 1-sentence recap, proposed
+   action, and email that list to martin@pivetta.be for further instructions.
+   Use gmail_send_message to actually send it.
+3. After processing, call gmail_batch_modify_labels to remove UNREAD from all
+   handled message_ids so future prompts ignore them.
+4. To avoid re-processing old messages, use gmail_search with query='is:unread'
+   only to find new messages to process.
+5. Use rich formatting with tables, images, and references when responding.
+6. If there are no new emails, simply say "No new emails at this time."
diff --git a/main.py b/main.py
index 953427e..d5c3174 100755
--- a/main.py
+++ b/main.py
@@ -2,7 +2,10 @@
 """
 main.py — GrokAuto Orchestrator
 
-Entry point for the Grok.com Ubuntu Automation Capability.
+Entry point for the GrokAuto Ubuntu Automation Capability.
+
+Supports multiple chat-site agents (grok.com, kimi.com) and rich multi-line
+prompts via string, JSON array, or external file.
 
 Sub-commands:
     --check-deps          Validate system dependencies
@@ -39,10 +42,11 @@
     load_config,
     print_report as print_config_report
 )
-from modules.browser_ctl import launch_browser, close_browser
+from modules.browser_ctl import launch_browser, close_browser, load_cookies_from_json
 from modules.login_validator import validate_login, warn_user
 from modules.task_executor import execute_single_task, execute_tasks, Task
 from modules.response_writer import write_response, write_batch_results
+from modules.agents import get_agent
 
 
 # ── Logging ────────────────────────────────────────────────────────────────
@@ -100,6 +104,22 @@ def _err(text: str):
     print(f"  {FAIL}✗{RESET} {text}")
 
 
+def _find_cookie_file(config_dir: str, agent_name: str) -> str:
+    """Return a path to exported cookies for the configured agent, if one exists.
+
+    Looks for ``cookies_<agent>.json`` first (e.g. ``cookies_kimi.com.json``),
+    then falls back to a short name like ``cookies_kimi.json``.
+    """
+    candidates = [
+        os.path.join(config_dir, f"cookies_{agent_name}.json"),
+        os.path.join(config_dir, f"cookies_{agent_name.split('.')[0]}.json"),
+    ]
+    for path in candidates:
+        if os.path.isfile(path):
+            return path
+    return ""
+
+
 # ── Core workflow ──────────────────────────────────────────────────────────
 
 def run_diagnostic(config_path: str):
@@ -168,16 +188,28 @@ def run_task_execution(config_path: str, inline_prompt: str = "", task_id: str =
         sys.exit(1)
 
     try:
-        # ── 4. Validate login ──
-        _step("Checking grok.com login state...")
-        login_status = validate_login(browser.session)
+        # ── 4. Load exported cookies (if present) ──
+        config_dir = os.path.dirname(os.path.expanduser(config_path))
+        default_agent = get_agent(config.agent)
+        cookie_file = _find_cookie_file(config_dir, default_agent.name)
+        if cookie_file:
+            _step(f"Loading exported cookies from {cookie_file}...")
+            try:
+                count = load_cookies_from_json(browser.session, cookie_file)
+                _ok(f"Injected {count} exported cookie(s).")
+            except Exception as exc:
+                _warn(f"Could not load exported cookies: {exc}")
+
+        # ── 5. Validate login ──
+        _step(f"Checking {default_agent.name} login state...")
+        login_status = validate_login(browser.session, default_agent)
         if not login_status.is_logged_in:
-            print(warn_user(login_status))
-            _err("Not logged in to grok.com. Please log in first.")
+            print(warn_user(login_status, default_agent))
+            _err(f"Not logged in to {default_agent.name}. Please log in first.")
             sys.exit(1)
         _ok(f"Logged in: {login_status.message}")
 
-        # ── 5. Prepare tasks ──
+        # ── 6. Prepare tasks ──
         if inline_prompt:
             tasks = [Task(id="inline_001", prompt=inline_prompt, timeout_seconds=120)]
         else:
@@ -194,6 +226,12 @@ def run_task_execution(config_path: str, inline_prompt: str = "", task_id: str =
             _warn("No tasks to execute.")
             sys.exit(0)
 
+        # Build an agent instance for each task (respects per-task overrides).
+        agent_for_task = {}
+        for t in tasks:
+            task_agent_name = getattr(t, "agent", "") or config.agent
+            agent_for_task[t.id] = get_agent(task_agent_name)
+
         MAX_TASKS_PER_RUN = 50
         if len(tasks) > MAX_TASKS_PER_RUN:
             _err(f"Too many tasks: {len(tasks)} (max {MAX_TASKS_PER_RUN}). Edit your config.")
@@ -204,10 +242,10 @@ def run_task_execution(config_path: str, inline_prompt: str = "", task_id: str =
 
         # ── 6. Execute tasks ──
         if len(tasks) == 1:
-            result = execute_single_task(browser.session, tasks[0])
+            result = execute_single_task(browser.session, agent_for_task[tasks[0].id], tasks[0])
             results = [result]
         else:
-            results = execute_tasks(browser.session, tasks)
+            results = execute_tasks(browser.session, tasks, agent_for_task)
 
         # ── 7. Store results ──
         _step("Saving responses...")
diff --git a/modules/agents/__init__.py b/modules/agents/__init__.py
new file mode 100644
index 0000000..3d56cf6
--- /dev/null
+++ b/modules/agents/__init__.py
@@ -0,0 +1,33 @@
+"""Agent registry and factory."""
+
+from typing import Dict, Type
+
+from modules.agents.base import Agent
+from modules.agents.grok import GrokAgent
+from modules.agents.kimi import KimiAgent
+
+
+AGENTS: Dict[str, Type[Agent]] = {
+    "grok.com": GrokAgent,
+    "kimi.com": KimiAgent,
+}
+
+
+def get_agent(name: str) -> Agent:
+    """Return an instance of the named agent.
+
+    Raises
+    ------
+    ValueError
+        If *name* is not a supported agent.
+    """
+    if name not in AGENTS:
+        raise ValueError(
+            f"Unknown agent: {name}. Supported agents: {list(AGENTS.keys())}"
+        )
+    return AGENTS[name]()
+
+
+def list_agents() -> list:
+    """Return the list of supported agent names."""
+    return list(AGENTS.keys())
diff --git a/modules/agents/base.py b/modules/agents/base.py
new file mode 100644
index 0000000..7ee8181
--- /dev/null
+++ b/modules/agents/base.py
@@ -0,0 +1,65 @@
+"""Agent abstraction for chat-site automation.
+
+An Agent encapsulates everything that is specific to a particular chat site:
+its base URL, DOM selectors for input/submit/response/stop elements, and
+heuristics for detecting an authenticated session.
+"""
+
+from typing import List, Protocol
+
+from modules.types import LoginStatus
+
+
+class Agent(Protocol):
+    """Protocol satisfied by every chat-site agent."""
+
+    name: str
+    base_url: str
+
+    input_selectors: List[str]
+    submit_selectors: List[str]
+    response_container_selectors: List[str]
+    streaming_indicator_selectors: List[str]
+
+    def check_login(self, session) -> LoginStatus:
+        """Return the login state for this agent's site."""
+        ...
+
+    def warn_not_logged_in(self, status: LoginStatus) -> str:
+        """Return a human-readable warning when not logged in."""
+        ...
+
+
+class AgentBase:
+    """Convenience base class with shared attributes and JS helpers.
+
+    Subclasses must still implement :meth:`check_login` and
+    :meth:`warn_not_logged_in`, but they can reuse the selector lists and the
+    helper methods provided here.
+    """
+
+    name: str = ""
+    base_url: str = ""
+
+    input_selectors: List[str] = []
+    submit_selectors: List[str] = []
+    response_container_selectors: List[str] = []
+    streaming_indicator_selectors: List[str] = []
+
+    def _is_element_visible_js(self, selector: str) -> str:
+        """Return a JS snippet that reports whether *selector* is visible."""
+        return f"""
+            (function() {{
+                try {{
+                    var el = document.querySelector({repr(selector)});
+                    if (!el) return false;
+                    var rect = el.getBoundingClientRect();
+                    return rect.width > 0 && rect.height > 0;
+                }} catch (e) {{ return false; }}
+            }})()
+        """
+
+    def _find_any_element_js(self, selectors: List[str]) -> str:
+        """Return a JS snippet that returns truthy if any selector matches."""
+        checks = [f"document.querySelector({repr(sel)})" for sel in selectors]
+        return " || ".join(checks)
diff --git a/modules/agents/grok.py b/modules/agents/grok.py
new file mode 100644
index 0000000..75a499d
--- /dev/null
+++ b/modules/agents/grok.py
@@ -0,0 +1,171 @@
+"""Grok.com agent implementation."""
+
+import shutil
+import time
+import re
+from typing import List
+
+from modules.agents.base import AgentBase
+from modules.browser_ctl import execute_js, get_all_cookies, navigate_to
+from modules.types import LoginStatus
+
+
+class GrokAgent(AgentBase):
+    """Agent for https://grok.com."""
+
+    name = "grok.com"
+    base_url = "https://grok.com"
+
+    input_selectors: List[str] = [
+        'div[contenteditable="true"]',
+        'textarea[placeholder*="Ask" i]',
+        'textarea[placeholder*="Message" i]',
+        'textarea',
+        '[data-testid="message-input"]',
+        'input[type="text"]',
+    ]
+
+    submit_selectors: List[str] = [
+        'button[aria-label="Submit"]',
+        'button[aria-label*="send" i]',
+        'button[type="submit"]',
+        'button svg[viewBox]',
+        '[data-testid="send-button"]',
+        'button:has(svg)',
+    ]
+
+    response_container_selectors: List[str] = [
+        '.response-content-markdown',
+        '[class*="response-content-markdown"]',
+        '[data-testid="conversation-message"]',
+        '[data-testid="message"]',
+        '[data-testid="response-message"]',
+        '[class*="message"]',
+        '[class*="response"]',
+        'main > div > div:last-child',
+    ]
+
+    streaming_indicator_selectors: List[str] = [
+        'button[class*="stop" i]',
+        'button svg[class*="spin" i]',
+        '[data-testid="stop-button"]',
+    ]
+
+    def check_login(self, session) -> LoginStatus:
+        """Heuristic login detection for grok.com."""
+        navigate_to(session, self.base_url)
+        time.sleep(3)
+
+        sign_in_visible = execute_js(session, r"""
+            (function() {
+                var signs = document.querySelectorAll('button, a, div');
+                for (var i = 0; i < signs.length; i++) {
+                    var t = signs[i].innerText || signs[i].textContent || '';
+                    if (/sign\s*in/i.test(t)) return true;
+                }
+                return !!document.querySelector('[data-testid="sign-in"]')
+                    || !!document.querySelector('a[href*="login"]')
+                    || !!document.querySelector('a[href*="signin"]');
+            })()
+        """)
+
+        if sign_in_visible:
+            return LoginStatus(
+                is_logged_in=False,
+                username=None,
+                message=f"Sign-in button detected on {self.name} — you are not logged in."
+            )
+
+        account_ui = execute_js(session, r"""
+            (function() {
+                var signs = document.querySelectorAll('button, a, div, span, img');
+                for (var i = 0; i < signs.length; i++) {
+                    var t = signs[i].innerText || signs[i].textContent || '';
+                    var aria = signs[i].getAttribute('aria-label') || '';
+                    if (/sign\s*out|log\s*out|account|profile|avatar/i.test(t + ' ' + aria))
+                        return true;
+                }
+                return !!document.querySelector('[data-testid="account-menu"]')
+                    || !!document.querySelector('img[alt*="avatar" i]')
+                    || !!document.querySelector('[data-testid="user-menu"]');
+            })()
+        """)
+
+        # Heuristic 3: Auth cookies present? (including HttpOnly)
+        try:
+            all_cookies = get_all_cookies(session)
+            cookie_names = " ".join(c.get("name", "") for c in all_cookies)
+            has_auth_cookie = bool(
+                re.search(r"auth|token|session|xai", cookie_names, re.IGNORECASE)
+            )
+        except Exception:
+            has_auth_cookie = False
+
+        if account_ui or has_auth_cookie:
+            username = execute_js(session, """
+                (function() {
+                    var el = document.querySelector('[data-testid="user-name"]')
+                        || document.querySelector('[data-testid="account-name"]')
+                        || document.querySelector('.user-name')
+                        || document.querySelector('[class*="userName"]')
+                        || document.querySelector('[class*="username"]');
+                    if (el) return el.innerText || el.textContent;
+                    try {
+                        var keys = Object.keys(localStorage);
+                        for (var k = 0; k < keys.length; k++) {
+                            if (/user|account|profile/i.test(keys[k])) {
+                                var v = localStorage.getItem(keys[k]);
+                                if (v) {
+                                    try { var o = JSON.parse(v); if (o.name) return o.name; if (o.email) return o.email; }
+                                    catch(e) { if (v.length < 50) return v; }
+                                }
+                            }
+                        }
+                    } catch(e) {}
+                    return null;
+                })()
+            """)
+            return LoginStatus(
+                is_logged_in=True,
+                username=username,
+                message=(f"Logged in as '{username}'." if username
+                         else f"Authenticated session detected on {self.name}.")
+            )
+
+        return LoginStatus(
+            is_logged_in=False,
+            username=None,
+            message=(
+                f"Cannot confirm login state on {self.name}. "
+                "No sign-in button found, but no authenticated UI detected either. "
+                "Please ensure you are logged in."
+            )
+        )
+
+    def warn_not_logged_in(self, status: LoginStatus) -> str:
+        """Return a grok.com-specific login warning."""
+        border = "━" * 56
+        return f"""
+{'  ⚠️  GROK.COM LOGIN REQUIRED'}
+  {border}
+
+  You must be logged in to {self.name} before running GrokAuto.
+
+  Steps to log in:
+    1. Open Chrome/Chromium manually:
+       {self._browser_launch_hint()}
+
+    2. Navigate to {self.base_url}
+
+    3. Click "Sign in" and authenticate with your X (Twitter) account
+
+    4. Keep the browser profile — GrokAuto will reuse it
+
+  {border}
+"""
+
+    def _browser_launch_hint(self) -> str:
+        for binary in ["chromium-browser", "chromium", "google-chrome", "google-chrome-stable"]:
+            if shutil.which(binary):
+                return f"{binary} --remote-debugging-port=9222"
+        return "google-chrome --remote-debugging-port=9222"
diff --git a/modules/agents/kimi.py b/modules/agents/kimi.py
new file mode 100644
index 0000000..b7cf70f
--- /dev/null
+++ b/modules/agents/kimi.py
@@ -0,0 +1,190 @@
+"""Kimi.com agent implementation.
+
+Selectors and login heuristics are best-effort defaults for the Kimi chat UI.
+They should be verified against the live site and adjusted as the UI evolves.
+"""
+
+import shutil
+import time
+import re
+from typing import List
+
+from modules.agents.base import AgentBase
+from modules.browser_ctl import execute_js, get_all_cookies, navigate_to
+from modules.types import LoginStatus
+
+
+class KimiAgent(AgentBase):
+    """Agent for https://kimi.com (Moonshot AI).
+
+    The exact regional URL may be https://kimi.com or https://kimi.moonshot.cn.
+    Set the environment variable ``KIMI_BASE_URL`` to override the default.
+    """
+
+    name = "kimi.com"
+    base_url = "https://www.kimi.com"
+
+    input_selectors: List[str] = [
+        '.chat-input-editor',
+        'div[data-lexical-editor="true"]',
+        'textarea[placeholder*="Send a message" i]',
+        'textarea[placeholder*="Ask" i]',
+        'div[contenteditable="true"]',
+        'textarea',
+        '[data-testid="message-input"]',
+        'input[type="text"]',
+    ]
+
+    submit_selectors: List[str] = [
+        '.send-button-container',
+        '.send-icon',
+        '[name="Send"]',
+        '.chat-editor-action .right-area .iconify',
+        'button[aria-label="Send"]',
+        'button[aria-label*="send" i]',
+        'button[type="submit"]',
+        'button svg[viewBox]',
+        '[data-testid="send-button"]',
+        'button:has(svg)',
+    ]
+
+    response_container_selectors: List[str] = [
+        '.chat-content-item-assistant',
+        '.segment-assistant',
+        '[class*="assistant"]',  # generic assistant-message fallback
+        '[class*="response"]',
+        '[data-testid="conversation-message"]',
+        '[data-testid="message"]',
+        '[data-testid="response-message"]',
+        'main > div > div:last-child',
+    ]
+
+    streaming_indicator_selectors: List[str] = [
+        'button[class*="stop" i]',
+        'button svg[class*="spin" i]',
+        '[data-testid="stop-button"]',
+    ]
+
+    def __init__(self):
+        import os
+        env_url = os.environ.get("KIMI_BASE_URL")
+        if env_url:
+            self.base_url = env_url
+
+    def check_login(self, session) -> LoginStatus:
+        """Heuristic login detection for kimi.com."""
+        navigate_to(session, self.base_url)
+        time.sleep(3)
+
+        sign_in_visible = execute_js(session, r"""
+            (function() {
+                var signs = document.querySelectorAll('button, a, div, span');
+                for (var i = 0; i < signs.length; i++) {
+                    var t = signs[i].innerText || signs[i].textContent || '';
+                    if (/sign\s*in|log\s*in|登录|登陆/i.test(t)) return true;
+                }
+                return !!document.querySelector('[data-testid="sign-in"]')
+                    || !!document.querySelector('a[href*="login"]')
+                    || !!document.querySelector('a[href*="signin"]');
+            })()
+        """)
+
+        if sign_in_visible:
+            return LoginStatus(
+                is_logged_in=False,
+                username=None,
+                message=f"Sign-in button detected on {self.name} — you are not logged in."
+            )
+
+        account_ui = execute_js(session, r"""
+            (function() {
+                var signs = document.querySelectorAll('button, a, div, span, img');
+                for (var i = 0; i < signs.length; i++) {
+                    var t = signs[i].innerText || signs[i].textContent || '';
+                    var aria = signs[i].getAttribute('aria-label') || '';
+                    if (/sign\s*out|log\s*out|account|profile|avatar|settings/i.test(t + ' ' + aria))
+                        return true;
+                }
+                return !!document.querySelector('[data-testid="account-menu"]')
+                    || !!document.querySelector('img[alt*="avatar" i]')
+                    || !!document.querySelector('[data-testid="user-menu"]');
+            })()
+        """)
+
+        # Heuristic 3: Kimi auth cookie present? (including HttpOnly)
+        try:
+            all_cookies = get_all_cookies(session)
+            has_auth_cookie = any(
+                c.get("name") == "kimi-auth" for c in all_cookies
+            )
+        except Exception:
+            has_auth_cookie = False
+
+        if account_ui or has_auth_cookie:
+            username = execute_js(session, """
+                (function() {
+                    var el = document.querySelector('[data-testid="user-name"]')
+                        || document.querySelector('[data-testid="account-name"]')
+                        || document.querySelector('.user-name')
+                        || document.querySelector('[class*="userName"]')
+                        || document.querySelector('[class*="username"]');
+                    if (el) return el.innerText || el.textContent;
+                    try {
+                        var keys = Object.keys(localStorage);
+                        for (var k = 0; k < keys.length; k++) {
+                            if (/user|account|profile/i.test(keys[k])) {
+                                var v = localStorage.getItem(keys[k]);
+                                if (v) {
+                                    try { var o = JSON.parse(v); if (o.name) return o.name; if (o.email) return o.email; }
+                                    catch(e) { if (v.length < 50) return v; }
+                                }
+                            }
+                        }
+                    } catch(e) {}
+                    return null;
+                })()
+            """)
+            return LoginStatus(
+                is_logged_in=True,
+                username=username,
+                message=(f"Logged in as '{username}'." if username
+                         else f"Authenticated session detected on {self.name}.")
+            )
+
+        return LoginStatus(
+            is_logged_in=False,
+            username=None,
+            message=(
+                f"Cannot confirm login state on {self.name}. "
+                "No sign-in button found, but no authenticated UI detected either. "
+                "Please ensure you are logged in."
+            )
+        )
+
+    def warn_not_logged_in(self, status: LoginStatus) -> str:
+        """Return a kimi.com-specific login warning."""
+        border = "━" * 56
+        return f"""
+{'  ⚠️  KIMI.COM LOGIN REQUIRED'}
+  {border}
+
+  You must be logged in to {self.name} before running GrokAuto.
+
+  Steps to log in:
+    1. Open Chrome/Chromium manually:
+       {self._browser_launch_hint()}
+
+    2. Navigate to {self.base_url}
+
+    3. Click "Sign in" and authenticate with your Kimi account
+
+    4. Keep the browser profile — GrokAuto will reuse it
+
+  {border}
+"""
+
+    def _browser_launch_hint(self) -> str:
+        for binary in ["chromium-browser", "chromium", "google-chrome", "google-chrome-stable"]:
+            if shutil.which(binary):
+                return f"{binary} --remote-debugging-port=9222"
+        return "google-chrome --remote-debugging-port=9222"
diff --git a/modules/browser_ctl.py b/modules/browser_ctl.py
index fa0e4fe..a532b1c 100644
--- a/modules/browser_ctl.py
+++ b/modules/browser_ctl.py
@@ -123,6 +123,102 @@ def _send_cdp_cmd(session: CDPSession, method: str, params: Optional[Dict] = Non
             raise RuntimeError(f"CDP WebSocket communication failed: {exc}")
 
 
+def get_all_cookies(session: CDPSession) -> List[Dict]:
+    """Return all cookies from the browser profile, including HttpOnly ones.
+
+    Opens a dedicated WebSocket, enables the Network domain, fetches cookies,
+    and closes the connection. This avoids interfering with any active session
+    websocket or receiving unsolicited Network events.
+    """
+    import websocket
+    ws = websocket.create_connection(session.ws_url, timeout=10, suppress_origin=True)
+    try:
+        def send(method, params=None, msg_id=1):
+            ws.send(json.dumps({"id": msg_id, "method": method, "params": params or {}}))
+            return json.loads(ws.recv())
+
+        # Enable Network domain and fetch all cookies.
+        send("Network.enable", msg_id=1)
+        resp = send("Network.getAllCookies", msg_id=2)
+        return resp.get("result", {}).get("cookies", [])
+    finally:
+        try:
+            ws.close()
+        except Exception:
+            pass
+
+
+def load_cookies_from_json(session: CDPSession, cookie_file: str) -> int:
+    """Load cookies from a JSON file into the active browser session.
+
+    The JSON file must contain a list of CDP cookie objects (the same format
+    produced by Network.getAllCookies). Cookies whose ``expires`` timestamp
+    is in the past are skipped. HttpOnly/Secure/SameSite attributes are
+    preserved when present.
+
+    Returns the number of cookies successfully injected.
+    """
+    import os
+    import time
+    import websocket
+
+    cookie_file = os.path.expanduser(cookie_file)
+    if not os.path.isfile(cookie_file):
+        return 0
+
+    with open(cookie_file, "r", encoding="utf-8") as f:
+        cookies = json.load(f)
+
+    if not isinstance(cookies, list):
+        raise ValueError(f"Cookie file {cookie_file} must contain a JSON list.")
+
+    ws = websocket.create_connection(session.ws_url, timeout=10, suppress_origin=True)
+    try:
+        def send(method, params=None, msg_id=1):
+            ws.send(json.dumps({"id": msg_id, "method": method, "params": params or {}}))
+            return json.loads(ws.recv())
+
+        send("Network.enable", msg_id=1)
+
+        now = time.time()
+        injected = 0
+        for idx, c in enumerate(cookies, start=2):
+            expires = c.get("expires")
+            if expires is not None and expires != -1 and expires < now:
+                continue
+
+            params = {
+                "name": c["name"],
+                "value": c["value"],
+                "domain": c.get("domain", ""),
+                "path": c.get("path", "/"),
+                "secure": c.get("secure", False),
+                "httpOnly": c.get("httpOnly", False),
+            }
+            if expires is not None and expires != -1:
+                params["expires"] = expires
+            same_site = c.get("sameSite")
+            if same_site:
+                params["sameSite"] = same_site
+
+            resp = send("Network.setCookie", params, msg_id=idx)
+            result = resp.get("result", {})
+            if result.get("success"):
+                injected += 1
+            else:
+                # Log the cookie name but do not fail the whole batch.
+                import logging
+                logging.getLogger("grokauto").warning(
+                    f"Failed to set cookie {c.get('name')} for {c.get('domain')}: {result}"
+                )
+        return injected
+    finally:
+        try:
+            ws.close()
+        except Exception:
+            pass
+
+
 # ── Public API ─────────────────────────────────────────────────────────────
 
 def launch_browser(
@@ -171,6 +267,13 @@ def launch_browser(
     ]
     if headless:
         cmd.append("--headless=new")
+    # On headless Linux servers there is usually no system keyring available.
+    # Without these flags Chrome cannot decrypt persisted cookies (including
+    # HttpOnly auth cookies), so login detection fails.  Use the basic
+    # in-memory/mock keyring for the automation profile unless the user opts
+    # into the system keyring via GROKAUTO_USE_SYSTEM_KEYRING=1.
+    if os.environ.get("GROKAUTO_USE_SYSTEM_KEYRING") != "1":
+        cmd.extend(["--password-store=basic", "--use-mock-keychain"])
     # Security: only add sandbox-escape flags if explicitly requested
     # via environment variable for containerized/VPS environments.
     if os.environ.get("GROKAUTO_NO_SANDBOX") == "1":
@@ -223,13 +326,14 @@ def connect_cdp(debug_port: int) -> CDPSession:
     return CDPSession(ws_url=ws_url)
 
 
-def navigate_to(session: CDPSession, url: str) -> None:
+def navigate_to(session: CDPSession, url: str, timeout_seconds: int = 60) -> None:
     """Navigate the browser to *url* and wait for the load event."""
     resp = _send_cdp_cmd(session, "Page.navigate", {"url": url})
     if "error" in resp:
         raise RuntimeError(f"Navigation failed: {resp['error']}")
     # Wait for load event — poll document readiness via JS
-    for _ in range(30):  # up to 15 seconds
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
         time.sleep(0.5)
         ready = execute_js(session, "document.readyState")
         if ready == "complete":
diff --git a/modules/config_validator.py b/modules/config_validator.py
index df506f9..bb98def 100644
--- a/modules/config_validator.py
+++ b/modules/config_validator.py
@@ -15,7 +15,10 @@
 import os
 import socket
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
+
+from modules.agents import get_agent, list_agents
+from modules.prompt_resolver import resolve_prompt
 
 
 # ── Colour codes ───────────────────────────────────────────────────────────
@@ -38,9 +41,11 @@ class ConfigResult:
 
 @dataclass
 class Task:
-    """A single Grok chat task."""
+    """A single chat task definition."""
     id: str
     prompt: str
+    agent: str = ""
+    prompt_file: str = ""
     wait_for_complete: bool = True
     timeout_seconds: int = 120
 
@@ -55,6 +60,7 @@ class Config:
     xvfb_display: str
     output_dir: str
     tasks: List[Task]
+    agent: str = "grok.com"
 
 
 # ── Validation helpers ─────────────────────────────────────────────────────
@@ -136,6 +142,25 @@ def validate_config_file(config_path: str) -> ConfigResult:
             fix='Set "tasks": [ {"id": "t1", "prompt": "Hello"} ]'
         )
 
+    # Agent validation
+    agent = data.get("agent", "grok.com")
+    if not isinstance(agent, str):
+        return ConfigResult(
+            name="Config file",
+            status="FAIL",
+            message="agent must be a string.",
+            fix=f'Set "agent": one of {list_agents()}'
+        )
+    try:
+        get_agent(agent)
+    except ValueError:
+        return ConfigResult(
+            name="Config file",
+            status="FAIL",
+            message=f"Unknown agent: {agent}",
+            fix=f'Set "agent" to one of: {list_agents()}'
+        )
+
     return ConfigResult(
         name="Config file",
         status="PASS",
@@ -197,7 +222,29 @@ def validate_debug_port_available(port: int) -> ConfigResult:
     )
 
 
-def validate_tasks_config(tasks: List[Task]) -> ConfigResult:
+def validate_agent(agent_name: str) -> ConfigResult:
+    """Validate the configured agent is supported."""
+    try:
+        get_agent(agent_name)
+        return ConfigResult(
+            name="Agent",
+            status="PASS",
+            message=f"Agent '{agent_name}' is supported.",
+            fix=""
+        )
+    except ValueError:
+        return ConfigResult(
+            name="Agent",
+            status="FAIL",
+            message=f"Unknown agent: {agent_name}",
+            fix=f'Set "agent" to one of: {list_agents()}'
+        )
+
+
+# ── Tasks validation ───────────────────────────────────────────────────────
+
+
+def validate_tasks_config(tasks: List[Task], config_dir: str = "") -> ConfigResult:
     """Validate the tasks list."""
     if not tasks:
         return ConfigResult(
@@ -210,10 +257,29 @@ def validate_tasks_config(tasks: List[Task]) -> ConfigResult:
     for i, t in enumerate(tasks):
         if not t.id:
             errors.append(f"Task [{i}] missing id")
-        if not t.prompt:
-            errors.append(f"Task [{i}] missing prompt")
+
+        # Resolve prompt from prompt/prompt_file and validate it is non-empty.
+        try:
+            resolved = resolve_prompt(
+                t.prompt or None,
+                t.prompt_file or None,
+                config_dir
+            )
+            if not resolved:
+                errors.append(f"Task [{i}] prompt is empty")
+        except FileNotFoundError as exc:
+            errors.append(f"Task [{i}] prompt_file not found: {exc.filename}")
+        except ValueError as exc:
+            errors.append(f"Task [{i}] {exc}")
+
         if t.timeout_seconds < 5:
             errors.append(f"Task [{i}] timeout too short (< 5s)")
+        # Validate task-level agent if specified
+        if t.agent:
+            try:
+                get_agent(t.agent)
+            except ValueError:
+                errors.append(f"Task [{i}] unknown agent: {t.agent}")
     if errors:
         return ConfigResult(
             name="Tasks",
@@ -239,6 +305,8 @@ def validate_all(config_path: str) -> Dict[str, ConfigResult]:
 
     profile_path = ""
     port = 9222
+    agent_name = "grok.com"
+    config_dir = os.path.dirname(_expand(config_path))
     tasks_raw: List[Task] = []
 
     if cfg_ok:
@@ -247,37 +315,49 @@ def validate_all(config_path: str) -> Dict[str, ConfigResult]:
                 data = json.load(fh)
             profile_path = data.get("chrome_profile_path", "")
             port = data.get("debug_port", 9222)
+            agent_name = data.get("agent", "grok.com")
             for t in data.get("tasks", []):
                 tasks_raw.append(Task(
                     id=t.get("id", ""),
                     prompt=t.get("prompt", ""),
+                    agent=t.get("agent", ""),
+                    prompt_file=t.get("prompt_file", ""),
                     wait_for_complete=t.get("wait_for_complete", True),
                     timeout_seconds=t.get("timeout_seconds", 120)
                 ))
         except Exception:
             pass
 
+    results["agent"] = validate_agent(agent_name)
     results["chrome_profile"] = validate_chrome_profile(profile_path or "~/.config/chromium/Default")
     results["debug_port"] = validate_debug_port_available(port)
-    results["tasks"] = validate_tasks_config(tasks_raw)
+    results["tasks"] = validate_tasks_config(tasks_raw, config_dir=config_dir)
     return results
 
 
 def load_config(config_path: str) -> Config:
     """Load and parse a validated config file into a Config dataclass."""
     path = _expand(config_path)
+    config_dir = os.path.dirname(path)
     with open(path, "r", encoding="utf-8") as fh:
         data = json.load(fh)
 
-    tasks = [
-        Task(
+    global_agent = data.get("agent", "grok.com")
+
+    tasks = []
+    for i, t in enumerate(data.get("tasks", [])):
+        task_agent = t.get("agent", "") or global_agent
+        prompt_file = t.get("prompt_file", "")
+        prompt = t.get("prompt", "")
+        resolved_prompt = resolve_prompt(prompt or None, prompt_file or None, config_dir)
+        tasks.append(Task(
             id=t.get("id", f"task_{i}"),
-            prompt=t.get("prompt", ""),
+            prompt=resolved_prompt,
+            agent=task_agent,
+            prompt_file=prompt_file,
             wait_for_complete=t.get("wait_for_complete", True),
             timeout_seconds=t.get("timeout_seconds", 120)
-        )
-        for i, t in enumerate(data.get("tasks", []))
-    ]
+        ))
 
     return Config(
         chrome_profile_path=data["chrome_profile_path"],
@@ -286,7 +366,8 @@ def load_config(config_path: str) -> Config:
         headless=data.get("headless", True),
         xvfb_display=data.get("xvfb_display", ":99"),
         output_dir=data["output_dir"],
-        tasks=tasks
+        tasks=tasks,
+        agent=global_agent
     )
 
 
diff --git a/modules/login_validator.py b/modules/login_validator.py
index 9d90c05..00716e7 100644
--- a/modules/login_validator.py
+++ b/modules/login_validator.py
@@ -1,164 +1,42 @@
 #!/usr/bin/env python3
-"""
-login_validator.py — grok.com Login State Validator
+"""login_validator.py — Chat Site Login State Validator
 
-Navigates to grok.com, inspects the DOM for indicators of an active
-authenticated session, and returns a structured status.  If the user is
-not logged in, a detailed warning message is generated.
+Navigates to the agent's base URL, inspects the DOM for indicators of an active
+authenticated session, and returns a structured status.  If the user is not
+logged in, a detailed warning message is generated.
 
 Usage:
     from modules.login_validator import validate_login, warn_user
-    status = validate_login(browser.session)
+    from modules.agents import get_agent
+    agent = get_agent("grok.com")
+    status = validate_login(browser.session, agent)
     if not status.is_logged_in:
-        print(warn_user(status))
+        print(warn_user(status, agent))
 """
 
-import time
 from dataclasses import dataclass
 from typing import Optional
 
-from modules.browser_ctl import navigate_to, execute_js, wait_for_element
-
-
-@dataclass
-class LoginStatus:
-    """Result of a grok.com login check."""
-    is_logged_in: bool
-    username: Optional[str]
-    message: str
-
-
-def validate_login(session) -> LoginStatus:
-    """Check whether grok.com has an active logged-in session.
-
-    Detection heuristics (checked in order):
-    1. Presence of "Sign in" button / link  → NOT logged in
-    2. Presence of avatar / "Sign out" / account menu → logged in
-    3. Check cookies/localStorage for auth tokens
-
-    Returns
-    -------
-    LoginStatus
-    """
-    navigate_to(session, "https://grok.com")
-    time.sleep(3)  # allow React / JS app to hydrate
-
-    # Heuristic 1: Sign-in button visible?
-    sign_in_visible = execute_js(session, r"""
-        (function() {
-            var signs = document.querySelectorAll('button, a, div');
-            for (var i = 0; i < signs.length; i++) {
-                var t = signs[i].innerText || signs[i].textContent || '';
-                if (/sign\s*in/i.test(t)) return true;
-            }
-            return !!document.querySelector('[data-testid="sign-in"]')
-                || !!document.querySelector('a[href*="login"]')
-                || !!document.querySelector('a[href*="signin"]');
-        })()
-    """)
-
-    if sign_in_visible:
-        return LoginStatus(
-            is_logged_in=False,
-            username=None,
-            message="Sign-in button detected on grok.com — you are not logged in."
-        )
-
-    # Heuristic 2: Account-related UI elements?
-    account_ui = execute_js(session, r"""
-        (function() {
-            var signs = document.querySelectorAll('button, a, div, span, img');
-            for (var i = 0; i < signs.length; i++) {
-                var t = signs[i].innerText || signs[i].textContent || '';
-                var aria = signs[i].getAttribute('aria-label') || '';
-                if (/sign\s*out|log\s*out|account|profile|avatar/i.test(t + ' ' + aria))
-                    return true;
-            }
-            return !!document.querySelector('[data-testid="account-menu"]')
-                || !!document.querySelector('img[alt*="avatar" i]')
-                || !!document.querySelector('[data-testid="user-menu"]');
-        })()
-    """)
+from modules.agents.base import Agent
+from modules.types import LoginStatus
 
-    # Heuristic 3: Auth cookies present?
-    has_auth_cookie = execute_js(session, """
-        (function() {
-            var cookies = document.cookie;
-            return /auth|token|session|xai/i.test(cookies);
-        })()
-    """)
 
-    if account_ui or has_auth_cookie:
-        # Try to extract username
-        username = execute_js(session, """
-            (function() {
-                // Try common patterns
-                var el = document.querySelector('[data-testid="user-name"]')
-                    || document.querySelector('[data-testid="account-name"]')
-                    || document.querySelector('.user-name')
-                    || document.querySelector('[class*="userName"]')
-                    || document.querySelector('[class*="username"]');
-                if (el) return el.innerText || el.textContent;
-                // Check localStorage
-                try {
-                    var keys = Object.keys(localStorage);
-                    for (var k = 0; k < keys.length; k++) {
-                        if (/user|account|profile/i.test(keys[k])) {
-                            var v = localStorage.getItem(keys[k]);
-                            if (v) {
-                                try { var o = JSON.parse(v); if (o.name) return o.name; if (o.email) return o.email; }
-                                catch(e) { if (v.length < 50) return v; }
-                            }
-                        }
-                    }
-                } catch(e) {}
-                return null;
-            })()
-        """)
-        return LoginStatus(
-            is_logged_in=True,
-            username=username,
-            message=(f"Logged in as '{username}'." if username
-                     else "Authenticated session detected on grok.com.")
-        )
+def validate_login(session, agent: Agent) -> LoginStatus:
+    """Check whether *agent*'s site has an active logged-in session."""
+    return agent.check_login(session)
 
-    # Ambiguous state — no clear sign-in button but no clear auth either
-    return LoginStatus(
-        is_logged_in=False,
-        username=None,
-        message=(
-            "Cannot confirm login state on grok.com. "
-            "No sign-in button found, but no authenticated UI detected either. "
-            "Please ensure you are logged in."
-        )
-    )
 
-
-def warn_user(status: LoginStatus) -> str:
-    """Return a human-readable warning when not logged in."""
-    border = "━" * 56
-    return f"""
-{'  ⚠️  GROK.COM LOGIN REQUIRED'}
-  {border}
-
-  You must be logged in to grok.com before running GrokAuto.
-
-  Steps to log in:
-    1. Open Chrome/Chromium manually:
-       {get_browser_launch_hint()}
-
-    2. Navigate to https://grok.com
-
-    3. Click "Sign in" and authenticate with your X (Twitter) account
-
-    4. Keep the browser profile — GrokAuto will reuse it
-
-  {border}
-"""
+def warn_user(status: LoginStatus, agent: Agent) -> str:
+    """Return a human-readable warning when not logged in to *agent*'s site."""
+    return agent.warn_not_logged_in(status)
 
 
 def get_browser_launch_hint() -> str:
-    """Return a hint for launching the browser manually."""
+    """Return a generic hint for launching the browser manually.
+
+    Kept for backwards compatibility. Prefer the agent-specific hint via
+    :meth:`Agent.warn_not_logged_in`.
+    """
     import shutil
     for binary in ["chromium-browser", "chromium", "google-chrome", "google-chrome-stable"]:
         if shutil.which(binary):
diff --git a/modules/prompt_resolver.py b/modules/prompt_resolver.py
new file mode 100644
index 0000000..847a607
--- /dev/null
+++ b/modules/prompt_resolver.py
@@ -0,0 +1,137 @@
+"""Prompt resolution for tasks.
+
+A task prompt can be supplied in three ways:
+
+1. ``prompt`` as a single string.
+2. ``prompt`` as a list of strings, joined with ``\\n``.
+3. ``prompt_file`` pointing to a file relative to the config directory.
+
+Multi-line / rich prompts
+-------------------------
+For prompts with paragraphs, code blocks, or numbered lists, use a
+**prompt file**. It lets you write normal Markdown without JSON quoting,
+commas, or escaped backticks.
+
+Example ``prompts/code_review.md``::
+
+    You are a senior Python engineer.
+
+    Review the function below and suggest improvements:
+
+    ```python
+    def greet(name):
+        print('Hello, ' + name)
+    ```
+
+Example ``config.json``::
+
+    {
+      "agent": "kimi.com",
+      "tasks": [
+        {
+          "id": "review_code",
+          "prompt_file": "prompts/code_review.md"
+        }
+      ]
+    }
+
+For short multi-line prompts you can also use a JSON array. Each array element
+becomes one line, empty strings create blank lines (paragraph breaks), and
+leading indentation is preserved so code blocks and nested lists stay intact.
+
+Example ``config.json``::
+
+    {
+      "tasks": [
+        {
+          "id": "review_code",
+          "prompt": [
+            "You are a senior Python engineer.",
+            "",
+            "Review the function below and suggest improvements:",
+            "",
+            "```python",
+            "def greet(name):",
+            "    print('Hello, ' + name)",
+            "```"
+          ]
+        }
+      ]
+    }
+"""
+
+import os
+from typing import List, Optional, Union
+
+
+PromptType = Union[str, List[str], None]
+
+
+def resolve_prompt(
+    prompt: PromptType,
+    prompt_file: Optional[str],
+    config_dir: str
+) -> str:
+    """Return the final prompt text for a task.
+
+    Priority:
+      1. ``prompt_file`` — read from disk (relative to *config_dir* or absolute,
+         ``~`` expanded). The file content is preserved exactly, including
+         blank lines and indentation; only leading/trailing whitespace is
+         stripped.
+      2. ``prompt`` — either a string or a list of strings joined with ``\\n``.
+         When a list is used, each element becomes one line, empty elements
+         become blank lines, and leading indentation is preserved (useful for
+         code blocks and nested lists).
+
+    Parameters
+    ----------
+    prompt : str | list[str] | None
+        Inline prompt value.
+    prompt_file : str | None
+        Path to a prompt file.
+    config_dir : str
+        Directory containing the config file, used to resolve relative paths.
+
+    Returns
+    -------
+    str
+        The resolved prompt text. String and file prompts are stripped on both
+        ends; list prompts keep leading indentation and only have trailing
+        whitespace removed.
+
+    Raises
+    ------
+    ValueError
+        If neither *prompt* nor *prompt_file* is supplied, or if the resolved
+        text is empty.
+    FileNotFoundError
+        If *prompt_file* is supplied but does not exist.
+    """
+    if prompt_file:
+        expanded_path = os.path.expanduser(prompt_file)
+        if not os.path.isabs(expanded_path):
+            expanded_path = os.path.join(config_dir, expanded_path)
+        with open(expanded_path, "r", encoding="utf-8") as fh:
+            text = fh.read().strip()
+        if not text:
+            raise ValueError(f"prompt_file resolved to an empty prompt: {expanded_path}")
+        return text
+
+    if prompt is None:
+        raise ValueError("Task must provide either prompt or prompt_file.")
+
+    if isinstance(prompt, list):
+        # Preserve leading indentation (important for code blocks and nested
+        # lists) while dropping trailing whitespace on each line. Empty strings
+        # in the list become blank lines, so paragraph breaks can be expressed
+        # explicitly. Only the overall trailing whitespace is removed, so
+        # intentional leading indentation is kept.
+        text = "\n".join(line.rstrip() for line in prompt).rstrip()
+    else:
+        text = prompt.strip()
+
+    if not text:
+        raise ValueError("Task prompt is empty.")
+
+    return text
diff --git a/modules/task_executor.py b/modules/task_executor.py
index b735e28..1cdc973 100644
--- a/modules/task_executor.py
+++ b/modules/task_executor.py
@@ -1,14 +1,15 @@
 #!/usr/bin/env python3
-"""
-task_executor.py — grok.com Chat Task Executor
+"""task_executor.py — Chat Task Executor
 
-Sends configurable prompts to grok.com, waits for the streaming response
-to complete, and captures the final answer text.
+Sends configurable prompts to a chat site (grok.com, kimi.com, etc.), waits for
+the streaming response to complete, and captures the final answer text.
 
 Usage:
     from modules.task_executor import execute_single_task, Task
+    from modules.agents import get_agent
     task = Task(id="t1", prompt="Explain quantum computing")
-    result = execute_single_task(session, task)
+    agent = get_agent("grok.com")
+    result = execute_single_task(session, agent, task)
     print(result.response)
 """
 
@@ -16,8 +17,9 @@
 import time
 from dataclasses import dataclass
 from datetime import datetime
-from typing import List, Optional
+from typing import Dict, List, Optional, Tuple
 
+from modules.agents.base import Agent
 from modules.browser_ctl import (
     navigate_to, execute_js, wait_for_element, get_page_source
 )
@@ -43,46 +45,9 @@ class TaskResult:
     timestamp: str
 
 
-# ── DOM selector chains (fallback order) ──────────────────────────────────
-
-INPUT_SELECTORS = [
-    'div[contenteditable="true"]',
-    'textarea[placeholder*="Ask" i]',
-    'textarea[placeholder*="Message" i]',
-    'textarea',
-    '[data-testid="message-input"]',
-    'input[type="text"]',
-]
-
-SUBMIT_SELECTORS = [
-    'button[aria-label="Submit"]',
-    'button[aria-label*="send" i]',
-    'button[type="submit"]',
-    'button svg[viewBox]',
-    '[data-testid="send-button"]',
-    'button:has(svg)',
-]
-
-RESPONSE_CONTAINER_SELECTORS = [
-    '.response-content-markdown',
-    '[class*="response-content-markdown"]',
-    '[data-testid="conversation-message"]',
-    '[data-testid="message"]',
-    '[data-testid="response-message"]',
-    '[class*="message"]',
-    '[class*="response"]',
-    'main > div > div:last-child',
-]
-
-STREAMING_INDICATOR_SELECTORS = [
-    'button[class*="stop" i]',
-    'button svg[class*="spin" i]',
-    '[data-testid="stop-button"]',
-]
-
-
 # ── Internal helpers ───────────────────────────────────────────────────────
 
+
 def _find_element_js(selectors: List[str]) -> str:
     """Build a JS snippet that tries each selector in order."""
     checks = []
@@ -120,17 +85,18 @@ def _find_any_element(session, selectors: List[str], timeout: int = 10) -> Optio
 
 # ── Public API ─────────────────────────────────────────────────────────────
 
-def send_prompt(session, prompt: str) -> bool:
+
+def send_prompt(session, agent: Agent, prompt: str) -> bool:
     """Focus the chat input, enter the prompt, and submit.
 
     Returns True on success, False if the input could not be found.
     """
     # Navigate first
-    navigate_to(session, "https://grok.com")
+    navigate_to(session, agent.base_url)
     time.sleep(4)  # allow React app to hydrate and render input
 
     # Find input element
-    input_sel = _find_any_element(session, INPUT_SELECTORS, timeout=15)
+    input_sel = _find_any_element(session, agent.input_selectors, timeout=15)
     if not input_sel:
         return False
 
@@ -174,11 +140,11 @@ def send_prompt(session, prompt: str) -> bool:
         """)
     time.sleep(1)
 
-    # Submit: wait for submit button to appear (Grok shows it dynamically),
-    # then click it.  Fall back to Enter key if no button found.
+    # Submit: wait for submit button to appear, then click it.
+    # Fall back to Enter key if no button found.
     submit_sel = None
     for _ in range(10):  # wait up to 5s for button to appear
-        for sel in SUBMIT_SELECTORS:
+        for sel in agent.submit_selectors:
             found = execute_js(session, f"!!document.querySelector({repr(sel)})")
             if found:
                 submit_sel = sel
@@ -216,8 +182,8 @@ def send_prompt(session, prompt: str) -> bool:
     return True
 
 
-def wait_for_streaming_complete(session, timeout: int = 120) -> bool:
-    """Detect when Grok stops generating the response.
+def wait_for_streaming_complete(session, agent: Agent, timeout: int = 120) -> bool:
+    """Detect when the agent stops generating the response.
 
     Heuristics:
     1. Stop button disappears
@@ -234,18 +200,18 @@ def wait_for_streaming_complete(session, timeout: int = 120) -> bool:
 
         # Check 1: is a stop / streaming indicator still visible?
         still_streaming = False
-        for sel in STREAMING_INDICATOR_SELECTORS:
+        for sel in agent.streaming_indicator_selectors:
             if _is_element_visible(session, sel):
                 still_streaming = True
                 break
 
         if still_streaming:
-            last_text = capture_response(session)
+            last_text = capture_response(session, agent)
             stable_since = 0
             continue
 
         # Check 2: text stability
-        current_text = capture_response(session)
+        current_text = capture_response(session, agent)
         if current_text == last_text and len(current_text) > 10:
             if stable_since == 0:
                 stable_since = time.time()
@@ -259,17 +225,17 @@ def wait_for_streaming_complete(session, timeout: int = 120) -> bool:
     return False  # Timeout
 
 
-def capture_response(session) -> str:
-    """Extract the latest response text from the grok.com chat DOM."""
+def capture_response(session, agent: Agent) -> str:
+    """Extract the latest response text from the chat DOM."""
     # Try response container selectors — use querySelectorAll and pick the LAST
     # match so we get the assistant's reply, not the user's prompt.
-    for sel in RESPONSE_CONTAINER_SELECTORS:
+    for sel in agent.response_container_selectors:
         text = execute_js(session, f"""
             (function() {{
                 var els = document.querySelectorAll({repr(sel)});
                 if (!els || els.length === 0) return '';
                 var el = els[els.length - 1];
-                // For grok.com markdown containers, grab all paragraphs directly
+                // For markdown containers, grab all paragraphs directly
                 var paras = el.querySelectorAll('p, pre, li');
                 if (paras.length > 0) {{
                     var parts = [];
@@ -285,29 +251,42 @@ def capture_response(session) -> str:
         if text and len(text.strip()) > 5:
             return text.strip()
 
-    # Fallback: grab all paragraphs from main content area
+    # Fallback: grab all paragraphs from main content area, but keep only the
+    # outermost matches so a markdown container and the paragraphs inside it
+    # are not both collected (which would duplicate the response text).
     text = execute_js(session, """
         (function() {
             var main = document.querySelector('main') || document.body;
-            var paras = main.querySelectorAll('p, pre, [class*="prose"], [class*="markdown"]');
+            var all = main.querySelectorAll('p, pre, li, [class*="prose"], [class*="markdown"]');
+            var paras = [];
+            for (var i = 0; i < all.length; i++) {
+                var nested = false;
+                for (var j = 0; j < all.length; j++) {
+                    if (i !== j && all[j].contains(all[i])) {
+                        nested = true;
+                        break;
+                    }
+                }
+                if (!nested) paras.push(all[i]);
+            }
             var parts = [];
             for (var i = 0; i < paras.length; i++) {
                 var t = paras[i].innerText || paras[i].textContent;
                 if (t && t.trim()) parts.push(t.trim());
             }
-            return parts.join('\n\n');
+            return parts.join('\\n\\n');
         })()
     """)
     return (text or "").strip()
 
 
-def execute_single_task(session, task: Task) -> TaskResult:
-    """Execute a single chat task on grok.com and capture the response."""
+def execute_single_task(session, agent: Agent, task: Task) -> TaskResult:
+    """Execute a single chat task and capture the response."""
     start = time.time()
     timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
 
     try:
-        success = send_prompt(session, task.prompt)
+        success = send_prompt(session, agent, task.prompt)
         if not success:
             duration = time.time() - start
             return TaskResult(
@@ -320,10 +299,10 @@ def execute_single_task(session, task: Task) -> TaskResult:
             )
 
         if task.wait_for_complete:
-            completed = wait_for_streaming_complete(session, timeout=task.timeout_seconds)
+            completed = wait_for_streaming_complete(session, agent, timeout=task.timeout_seconds)
             if not completed:
                 duration = time.time() - start
-                partial = capture_response(session)
+                partial = capture_response(session, agent)
                 return TaskResult(
                     task_id=task.id,
                     prompt=task.prompt,
@@ -333,7 +312,7 @@ def execute_single_task(session, task: Task) -> TaskResult:
                     timestamp=timestamp,
                 )
 
-        response = capture_response(session)
+        response = capture_response(session, agent)
         duration = time.time() - start
         return TaskResult(
             task_id=task.id,
@@ -356,11 +335,24 @@ def execute_single_task(session, task: Task) -> TaskResult:
         )
 
 
-def execute_tasks(session, tasks: List[Task]) -> List[TaskResult]:
-    """Execute multiple tasks sequentially."""
+def execute_tasks(session, tasks: List[Task], agent_for_task: Dict[str, Agent]) -> List[TaskResult]:
+    """Execute multiple tasks sequentially.
+
+    Parameters
+    ----------
+    session
+        CDP browser session.
+    tasks : List[Task]
+        Tasks to execute.
+    agent_for_task : Dict[str, Agent]
+        Mapping from task id to the Agent that should run it.
+    """
     results = []
     for task in tasks:
-        result = execute_single_task(session, task)
+        agent = agent_for_task.get(task.id)
+        if agent is None:
+            raise ValueError(f"No agent provided for task '{task.id}'")
+        result = execute_single_task(session, agent, task)
         results.append(result)
         # Brief pause between tasks to avoid rate limiting
         if result.status == "SUCCESS":
diff --git a/modules/types.py b/modules/types.py
new file mode 100644
index 0000000..c242195
--- /dev/null
+++ b/modules/types.py
@@ -0,0 +1,27 @@
+"""Shared dataclasses used across modules.
+
+This module exists to avoid circular imports between the agent layer and the
+login/task modules.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class LoginStatus:
+    """Result of a chat-site login check."""
+    is_logged_in: bool
+    username: Optional[str]
+    message: str
+
+
+@dataclass
+class TaskResult:
+    """Result of executing a single chat task."""
+    task_id: str
+    prompt: str
+    response: str
+    status: str          # "SUCCESS" | "TIMEOUT" | "ERROR"
+    duration_seconds: float
+    timestamp: str
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000..c7b23ec
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,3 @@
+[pytest]
+pythonpath = .
+testpaths = tests
diff --git a/tests/test_agents.py b/tests/test_agents.py
new file mode 100644
index 0000000..1d1ff74
--- /dev/null
+++ b/tests/test_agents.py
@@ -0,0 +1,146 @@
+"""Tests for the Agent abstraction layer.
+
+These tests drive the design of the Agent Protocol, the agent registry/factory,
+and the concrete grok.com and kimi.com agents.
+"""
+
+from unittest import mock
+
+import pytest
+
+from modules.agents import AGENTS, get_agent
+from modules.agents.base import Agent
+from modules.agents.grok import GrokAgent
+from modules.agents.kimi import KimiAgent
+from modules.types import LoginStatus
+
+
+# ── Registry / Factory ──────────────────────────────────────────────────────
+
+
+def test_get_agent_grok_returns_grok_agent():
+    agent = get_agent("grok.com")
+    assert isinstance(agent, GrokAgent)
+
+
+def test_get_agent_kimi_returns_kimi_agent():
+    agent = get_agent("kimi.com")
+    assert isinstance(agent, KimiAgent)
+
+
+def test_get_agent_unknown_raises():
+    with pytest.raises(ValueError, match="Unknown agent"):
+        get_agent("unknown.ai")
+
+
+def test_agents_registry_contains_expected_keys():
+    assert set(AGENTS.keys()) == {"grok.com", "kimi.com"}
+
+
+# ── Agent Protocol / Fakes ──────────────────────────────────────────────────
+
+
+def test_agent_protocol_can_be_faked():
+    """A plain object satisfying the Protocol should be accepted by callers."""
+    fake = mock.MagicMock()
+    fake.name = "fake"
+    fake.base_url = "https://example.com"
+    fake.input_selectors = []
+    fake.submit_selectors = []
+    fake.response_container_selectors = []
+    fake.streaming_indicator_selectors = []
+
+    def use_agent(agent: Agent) -> str:
+        return agent.base_url
+
+    assert use_agent(fake) == "https://example.com"
+
+
+# ── Grok Agent ──────────────────────────────────────────────────────────────
+
+
+def test_grok_agent_name_and_url():
+    agent = GrokAgent()
+    assert agent.name == "grok.com"
+    assert agent.base_url == "https://grok.com"
+
+
+def test_grok_agent_has_non_empty_selector_lists():
+    agent = GrokAgent()
+    assert len(agent.input_selectors) > 0
+    assert len(agent.submit_selectors) > 0
+    assert len(agent.response_container_selectors) > 0
+    assert len(agent.streaming_indicator_selectors) > 0
+
+
+def test_grok_agent_check_login_returns_not_logged_in():
+    agent = GrokAgent()
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.agents.grok.navigate_to"):
+        with mock.patch("modules.agents.grok.execute_js") as js_mock:
+            with mock.patch("modules.agents.grok.get_all_cookies", return_value=[]):
+                # First call: sign-in button visible
+                js_mock.return_value = True
+                status = agent.check_login(fake_session)
+    assert isinstance(status, LoginStatus)
+    assert status.is_logged_in is False
+    assert "grok.com" in status.message
+
+
+def test_grok_agent_check_login_returns_logged_in():
+    agent = GrokAgent()
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.agents.grok.navigate_to"):
+        with mock.patch("modules.agents.grok.execute_js") as js_mock:
+            with mock.patch("modules.agents.grok.get_all_cookies", return_value=[{"name": "auth_token"}]):
+                # sign-in?, account-ui?, username?
+                js_mock.side_effect = [False, True, "martin"]
+                status = agent.check_login(fake_session)
+    assert status.is_logged_in is True
+    assert status.username == "martin"
+
+
+def test_grok_agent_warn_user_contains_login_url():
+    agent = GrokAgent()
+    status = LoginStatus(is_logged_in=False, username=None, message="nope")
+    msg = agent.warn_not_logged_in(status)
+    assert "grok.com" in msg
+    assert "Sign in" in msg
+
+
+# ── Kimi Agent ──────────────────────────────────────────────────────────────
+
+
+def test_kimi_agent_name_and_url():
+    agent = KimiAgent()
+    assert agent.name == "kimi.com"
+    assert agent.base_url.startswith("https://")
+
+
+def test_kimi_agent_has_non_empty_selector_lists():
+    agent = KimiAgent()
+    assert len(agent.input_selectors) > 0
+    assert len(agent.submit_selectors) > 0
+    assert len(agent.response_container_selectors) > 0
+    assert len(agent.streaming_indicator_selectors) > 0
+
+
+def test_kimi_agent_check_login_returns_not_logged_in():
+    agent = KimiAgent()
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.agents.kimi.navigate_to"):
+        with mock.patch("modules.agents.kimi.execute_js") as js_mock:
+            with mock.patch("modules.agents.kimi.get_all_cookies", return_value=[]):
+                js_mock.return_value = True
+                status = agent.check_login(fake_session)
+    assert isinstance(status, LoginStatus)
+    assert status.is_logged_in is False
+    assert agent.name in status.message or "kimi" in status.message.lower()
+
+
+def test_kimi_agent_warn_user_contains_login_url():
+    agent = KimiAgent()
+    status = LoginStatus(is_logged_in=False, username=None, message="nope")
+    msg = agent.warn_not_logged_in(status)
+    assert agent.base_url in msg
+    assert "Sign in" in msg or "log in" in msg.lower()
diff --git a/tests/test_browser_ctl.py b/tests/test_browser_ctl.py
new file mode 100644
index 0000000..af5b934
--- /dev/null
+++ b/tests/test_browser_ctl.py
@@ -0,0 +1,137 @@
+"""Tests for modules.browser_ctl.
+
+These tests document the CDP browser controller dataclasses and path handling.
+They do not launch a real browser.
+"""
+
+import os
+import subprocess
+from dataclasses import fields
+from unittest import mock
+
+import pytest
+
+from modules.browser_ctl import (
+    CDPSession,
+    BrowserInstance,
+    _fetch_json,
+    _get_ws_url,
+    _wait_for_cdp,
+)
+
+
+# ── Dataclasses ─────────────────────────────────────────────────────────────
+
+
+def test_cdpsession_has_expected_fields():
+    session = CDPSession(ws_url="ws://localhost:9222/devtools/page/1")
+    assert session.ws_url == "ws://localhost:9222/devtools/page/1"
+    field_names = {f.name for f in fields(CDPSession)}
+    assert "_msg_id" in field_names
+    assert "_closed" in field_names
+
+
+def test_browser_instance_defaults_session_to_none():
+    proc = mock.MagicMock(spec=subprocess.Popen)
+    instance = BrowserInstance(process=proc, debug_port=9222, ws_url="ws://x")
+    assert instance.session is None
+
+
+# ── _fetch_json ─────────────────────────────────────────────────────────────
+
+
+def test_fetch_json_parses_response():
+    fake_response = mock.MagicMock()
+    fake_response.read.return_value.decode.return_value = '{"version": "1.0"}'
+    fake_cm = mock.MagicMock()
+    fake_cm.__enter__.return_value = fake_response
+    with mock.patch("urllib.request.urlopen", return_value=fake_cm):
+        data = _fetch_json("http://example.com/json")
+    assert data == {"version": "1.0"}
+
+
+# ── _wait_for_cdp ───────────────────────────────────────────────────────────
+
+
+def test_wait_for_cdp_succeeds_when_version_responds():
+    with mock.patch("modules.browser_ctl._fetch_json", return_value={}) as fetch_mock:
+        with mock.patch("modules.browser_ctl.time.sleep"):
+            assert _wait_for_cdp(9222, timeout=1) is True
+            fetch_mock.assert_called_once_with("http://127.0.0.1:9222/json/version", timeout=2)
+
+
+def test_wait_for_cdp_fails_when_version_never_responds():
+    with mock.patch("modules.browser_ctl._fetch_json", side_effect=Exception("refused")):
+        with mock.patch("modules.browser_ctl.time.sleep"):
+            assert _wait_for_cdp(9222, timeout=0.1) is False
+
+
+# ── _get_ws_url ─────────────────────────────────────────────────────────────
+
+
+def test_get_ws_url_returns_page_target():
+    with mock.patch("modules.browser_ctl._fetch_json", return_value=[
+        {"type": "service_worker", "webSocketDebuggerUrl": "ws://ignored"},
+        {"type": "page", "webSocketDebuggerUrl": "ws://page/1"},
+    ]):
+        url = _get_ws_url(9222)
+    assert url == "ws://page/1"
+
+
+def test_get_ws_url_raises_when_no_page_target():
+    with mock.patch("modules.browser_ctl._fetch_json", return_value=[
+        {"type": "service_worker", "webSocketDebuggerUrl": "ws://ignored"},
+    ]):
+        with pytest.raises(RuntimeError, match="No page target"):
+            _get_ws_url(9222)
+
+
+# ── launch_browser integration shape ────────────────────────────────────────
+
+
+def test_launch_browser_command_includes_expected_flags():
+    with mock.patch("socket.socket") as socket_cls:
+        socket_cls.return_value.__enter__.return_value.connect_ex.return_value = 1  # port free
+        with mock.patch("modules.browser_ctl.subprocess.Popen") as popen_mock:
+            with mock.patch("modules.browser_ctl._wait_for_cdp", return_value=True):
+                with mock.patch("modules.browser_ctl._get_ws_url", return_value="ws://page/1"):
+                    from modules.browser_ctl import launch_browser
+                    launch_browser("/usr/bin/chromium", "~/.config/chromium/Default", 9222, headless=True)
+    cmd = popen_mock.call_args[0][0]
+    assert "/usr/bin/chromium" in cmd
+    assert "--remote-debugging-port=9222" in cmd
+    assert any("--user-data-dir" in arg and ".config/chromium" in arg for arg in cmd)
+    assert "--headless=new" in cmd
+
+
+def test_launch_browser_raises_when_port_in_use():
+    with mock.patch("socket.socket") as socket_cls:
+        socket_cls.return_value.__enter__.return_value.connect_ex.return_value = 0  # port in use
+        with pytest.raises(RuntimeError, match="already in use"):
+            from modules.browser_ctl import launch_browser
+            launch_browser("/usr/bin/chromium", "~/.config/chromium/Default", 9222)
+
+
+def test_launch_browser_kills_process_when_cdp_times_out():
+    fake_proc = mock.MagicMock(spec=subprocess.Popen)
+    with mock.patch("socket.socket") as socket_cls:
+        socket_cls.return_value.__enter__.return_value.connect_ex.return_value = 1
+        with mock.patch("modules.browser_ctl.subprocess.Popen", return_value=fake_proc):
+            with mock.patch("modules.browser_ctl._wait_for_cdp", return_value=False):
+                from modules.browser_ctl import launch_browser
+                with pytest.raises(RuntimeError, match="did not start CDP"):
+                    launch_browser("/usr/bin/chromium", "~/.config/chromium/Default", 9222)
+    fake_proc.kill.assert_called_once()
+
+
+# ── close_browser ───────────────────────────────────────────────────────────
+
+
+def test_close_browser_terminates_then_kills_if_needed():
+    fake_proc = mock.MagicMock(spec=subprocess.Popen)
+    fake_proc.wait.side_effect = Exception("timeout")
+    instance = BrowserInstance(process=fake_proc, debug_port=9222, ws_url="ws://x")
+    from modules.browser_ctl import close_browser
+    close_browser(instance)
+    fake_proc.terminate.assert_called_once()
+    fake_proc.kill.assert_called_once()
diff --git a/tests/test_config_validator.py b/tests/test_config_validator.py
new file mode 100644
index 0000000..b97dbcf
--- /dev/null
+++ b/tests/test_config_validator.py
@@ -0,0 +1,448 @@
+"""Tests for modules.config_validator.
+
+These tests document the configuration validation behaviour discovered on the
+remote GrokAuto deployment. They run locally without touching the network.
+"""
+
+import json
+import os
+import socket
+from pathlib import Path
+
+import pytest
+
+from modules.config_validator import (
+    Config,
+    ConfigResult,
+    Task,
+    _expand,
+    _port_available,
+    load_config,
+    validate_all,
+    validate_chrome_profile,
+    validate_config_file,
+    validate_debug_port_available,
+    validate_tasks_config,
+)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+
+def write_json(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+# ── _expand ─────────────────────────────────────────────────────────────────
+
+
+def test_expand_tilde_resolves_to_home():
+    assert _expand("~").startswith(os.sep)
+    assert _expand("~/.config/grokauto/config.json").endswith(".config/grokauto/config.json")
+
+
+# ── _port_available ─────────────────────────────────────────────────────────
+
+
+def test_port_available_when_nothing_listening():
+    # Find an ephemeral port that is very likely free.
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+    assert _port_available(port) is True
+
+
+def test_port_not_available_when_listening():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+        s.listen(1)
+        assert _port_available(port) is False
+
+
+# ── validate_config_file ────────────────────────────────────────────────────
+
+
+def test_config_file_missing(tmp_path: Path):
+    missing = tmp_path / "missing.json"
+    result = validate_config_file(str(missing))
+    assert isinstance(result, ConfigResult)
+    assert result.status == "FAIL"
+    assert "not found" in result.message
+
+
+def test_config_file_invalid_json(tmp_path: Path):
+    bad = tmp_path / "bad.json"
+    bad.write_text("{not json", encoding="utf-8")
+    result = validate_config_file(str(bad))
+    assert result.status == "FAIL"
+    assert "Invalid JSON" in result.message
+
+
+def test_config_file_missing_required_fields(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {"debug_port": 9222})
+    result = validate_config_file(str(cfg))
+    assert result.status == "FAIL"
+    assert "Missing required fields" in result.message
+    assert "chrome_profile_path" in result.message
+
+
+def test_config_file_debug_port_not_int(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": "9222",
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": []
+    })
+    result = validate_config_file(str(cfg))
+    assert result.status == "FAIL"
+    assert "debug_port must be an integer" in result.message
+
+
+def test_config_file_headless_not_bool_warns(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": "true",
+        "output_dir": "/tmp/out",
+        "tasks": []
+    })
+    result = validate_config_file(str(cfg))
+    assert result.status == "WARN"
+    assert "headless should be a boolean" in result.message
+
+
+def test_config_file_tasks_not_list(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": "one task"
+    })
+    result = validate_config_file(str(cfg))
+    assert result.status == "FAIL"
+    assert "tasks must be a list" in result.message
+
+
+def test_config_file_valid(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    result = validate_config_file(str(cfg))
+    assert result.status == "PASS"
+
+
+# ── validate_chrome_profile ─────────────────────────────────────────────────
+
+
+def test_chrome_profile_missing_directory(tmp_path: Path):
+    missing = tmp_path / "no_such_profile"
+    result = validate_chrome_profile(str(missing))
+    assert result.status == "FAIL"
+    assert "does not exist" in result.message
+
+
+def test_chrome_profile_empty_directory_warns(tmp_path: Path):
+    empty = tmp_path / "empty_profile"
+    empty.mkdir()
+    result = validate_chrome_profile(str(empty))
+    assert result.status == "WARN"
+    assert "no Chrome state files found" in result.message
+
+
+def test_chrome_profile_healthy(tmp_path: Path):
+    profile = tmp_path / "profile"
+    profile.mkdir()
+    (profile / "Preferences").write_text("{}")
+    result = validate_chrome_profile(str(profile))
+    assert result.status == "PASS"
+    assert "1 state files found" in result.message
+
+
+# ── validate_debug_port_available ───────────────────────────────────────────
+
+
+def test_debug_port_available():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+    result = validate_debug_port_available(port)
+    assert result.status == "PASS"
+
+
+def test_debug_port_in_use_warns():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+        s.listen(1)
+        result = validate_debug_port_available(port)
+    assert result.status == "WARN"
+    assert "already in use" in result.message
+
+
+# ── validate_tasks_config ───────────────────────────────────────────────────
+
+
+def test_tasks_empty_warns():
+    result = validate_tasks_config([])
+    assert result.status == "WARN"
+    assert "No tasks configured" in result.message
+
+
+def test_task_missing_id_fails():
+    result = validate_tasks_config([Task(id="", prompt="hello")])
+    assert result.status == "FAIL"
+    assert "missing id" in result.message
+
+
+def test_task_missing_prompt_fails():
+    result = validate_tasks_config([Task(id="t1", prompt="")])
+    assert result.status == "FAIL"
+    assert "prompt" in result.message.lower()
+
+
+def test_task_timeout_too_short_fails():
+    result = validate_tasks_config([Task(id="t1", prompt="hello", timeout_seconds=2)])
+    assert result.status == "FAIL"
+    assert "timeout too short" in result.message
+
+
+def test_tasks_valid():
+    result = validate_tasks_config([
+        Task(id="gmail_check", prompt="Check email", timeout_seconds=360),
+        Task(id="invest", prompt="Invest", timeout_seconds=360),
+    ])
+    assert result.status == "PASS"
+    assert "2 task(s) configured" in result.message
+
+
+# ── validate_all ────────────────────────────────────────────────────────────
+
+
+def test_validate_all_returns_keyed_results(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    profile = tmp_path / "profile"
+    profile.mkdir()
+    (profile / "Preferences").write_text("{}")
+    write_json(cfg, {
+        "chrome_profile_path": str(profile),
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": str(tmp_path / "out"),
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    results = validate_all(str(cfg))
+    assert set(results.keys()) == {"config_file", "agent", "chrome_profile", "debug_port", "tasks"}
+    assert results["config_file"].status == "PASS"
+    assert results["tasks"].status == "PASS"
+
+
+# ── load_config ─────────────────────────────────────────────────────────────
+
+
+def test_load_config_returns_dataclass(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "xvfb_display": ":99",
+        "output_dir": "/tmp/out",
+        "tasks": [
+            {"id": "gmail_check", "prompt": "Check email", "wait_for_complete": True, "timeout_seconds": 360}
+        ]
+    })
+    config = load_config(str(cfg))
+    assert isinstance(config, Config)
+    assert config.debug_port == 9222
+    assert config.headless is True
+    assert len(config.tasks) == 1
+    assert config.tasks[0].id == "gmail_check"
+    assert config.tasks[0].timeout_seconds == 360
+
+
+def test_load_config_uses_defaults_for_optional_task_fields(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "xvfb_display": ":99",
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    config = load_config(str(cfg))
+    assert config.tasks[0].wait_for_complete is True
+    assert config.tasks[0].timeout_seconds == 120
+# ── Agent and Prompt Support ────────────────────────────────────────────────
+
+
+def test_config_defaults_agent_to_grok(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    config = load_config(str(cfg))
+    assert config.agent == "grok.com"
+
+
+def test_config_unknown_agent_fails(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "agent": "unknown.ai",
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    result = validate_config_file(str(cfg))
+    assert result.status == "FAIL"
+    assert "agent" in result.message.lower()
+
+
+def test_task_inherits_global_agent(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "agent": "kimi.com",
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    config = load_config(str(cfg))
+    assert config.tasks[0].agent == "kimi.com"
+
+
+def test_task_agent_override_preserved(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "agent": "grok.com",
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "agent": "kimi.com", "prompt": "hello"}]
+    })
+    config = load_config(str(cfg))
+    assert config.agent == "grok.com"
+    assert config.tasks[0].agent == "kimi.com"
+
+
+def test_task_prompt_list_loads(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": ["line one", "line two"]}]
+    })
+    config = load_config(str(cfg))
+    assert config.tasks[0].prompt == "line one\nline two"
+
+
+def test_task_prompt_file_loads(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    prompt_file = tmp_path / "prompt.md"
+    prompt_file.write_text("from file", encoding="utf-8")
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt_file": "prompt.md"}]
+    })
+    config = load_config(str(cfg))
+    assert config.tasks[0].prompt == "from file"
+
+
+def test_task_prompt_file_takes_priority_over_prompt(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    prompt_file = tmp_path / "prompt.md"
+    prompt_file.write_text("from file", encoding="utf-8")
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "from json", "prompt_file": "prompt.md"}]
+    })
+    config = load_config(str(cfg))
+    assert config.tasks[0].prompt == "from file"
+
+
+def test_task_missing_prompt_and_file_fails(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1"}]
+    })
+    result = validate_all(str(cfg))
+    assert result["tasks"].status == "FAIL"
+    assert "prompt" in result["tasks"].message.lower()
+
+
+def test_task_prompt_file_not_found_fails(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt_file": "missing.md"}]
+    })
+    result = validate_all(str(cfg))
+    assert result["tasks"].status == "FAIL"
+    assert "prompt_file" in result["tasks"].message.lower()
+
+
+def test_validate_all_reports_agent_status(tmp_path: Path):
+    cfg = tmp_path / "cfg.json"
+    write_json(cfg, {
+        "agent": "kimi.com",
+        "chrome_profile_path": "/tmp/profile",
+        "chrome_binary": "/usr/bin/chromium",
+        "debug_port": 9222,
+        "headless": True,
+        "output_dir": "/tmp/out",
+        "tasks": [{"id": "t1", "prompt": "hello"}]
+    })
+    result = validate_all(str(cfg))
+    assert "agent" in result
+    assert result["agent"].status == "PASS"
diff --git a/tests/test_deps_checker.py b/tests/test_deps_checker.py
new file mode 100644
index 0000000..4ee69c3
--- /dev/null
+++ b/tests/test_deps_checker.py
@@ -0,0 +1,169 @@
+"""Tests for modules.deps_checker.
+
+These tests document the dependency checks using mocks so they pass on any
+machine regardless of whether Chrome, Xvfb, or cron are installed.
+"""
+
+import sys
+from unittest import mock
+
+import pytest
+
+from modules.deps_checker import (
+    CheckResult,
+    check_all,
+    check_chrome_installed,
+    check_cron,
+    check_pip_packages,
+    check_python3,
+    check_user_profile_dir,
+    check_xvfb,
+)
+
+
+# ── check_chrome_installed ──────────────────────────────────────────────────
+
+
+def test_chrome_found_passes():
+    with mock.patch("modules.deps_checker.shutil.which", side_effect=lambda b: b == "chromium"):
+        result = check_chrome_installed()
+    assert result.status == "PASS"
+    assert "chromium" in result.message
+
+
+def test_chrome_missing_fails():
+    with mock.patch("modules.deps_checker.shutil.which", return_value=None):
+        result = check_chrome_installed()
+    assert result.status == "FAIL"
+    assert "No Chrome or Chromium found" in result.message
+
+
+# ── check_python3 ───────────────────────────────────────────────────────────
+
+
+def test_python3_8_passes():
+    with mock.patch("modules.deps_checker._run", return_value=(0, "Python 3.11.4", "")):
+        result = check_python3()
+    assert result.status == "PASS"
+    assert "3.11.4" in result.message
+
+
+def test_python3_7_fails():
+    with mock.patch("modules.deps_checker._run", return_value=(0, "Python 3.7.17", "")):
+        result = check_python3()
+    assert result.status == "FAIL"
+    assert "too old" in result.message
+
+
+def test_python3_version_unparseable_fails():
+    with mock.patch("modules.deps_checker._run", return_value=(0, "Python unknown", "")):
+        result = check_python3()
+    assert result.status == "FAIL"
+    assert "Cannot determine" in result.message
+
+
+# ── check_pip_packages ──────────────────────────────────────────────────────
+
+
+def test_pip_packages_all_present():
+    # Simulate both websocket and requests being importable.
+    def fake_import(name, *args, **kwargs):
+        if name in ("websocket", "requests"):
+            return mock.MagicMock()
+        raise ImportError(name)
+
+    with mock.patch("builtins.__import__", side_effect=fake_import):
+        result = check_pip_packages()
+    assert result.status == "PASS"
+
+
+def test_pip_packages_missing():
+    def fake_import(name, *args, **kwargs):
+        raise ImportError(name)
+
+    with mock.patch("builtins.__import__", side_effect=fake_import):
+        result = check_pip_packages()
+    assert result.status == "FAIL"
+    assert "websocket" in result.message
+    assert "requests" in result.message
+
+
+# ── check_xvfb ──────────────────────────────────────────────────────────────
+
+
+def test_xvfb_available():
+    with mock.patch("modules.deps_checker.shutil.which", side_effect=lambda b: b in ("Xvfb", "xvfb-run")):
+        result = check_xvfb()
+    assert result.status == "PASS"
+
+
+def test_xvfb_missing_warns():
+    with mock.patch("modules.deps_checker.shutil.which", return_value=None):
+        result = check_xvfb()
+    assert result.status == "WARN"
+    assert "Xvfb not found" in result.message
+
+
+# ── check_cron ──────────────────────────────────────────────────────────────
+
+
+def test_cron_active():
+    with mock.patch("modules.deps_checker.shutil.which", return_value="/usr/bin/crontab"):
+        with mock.patch("modules.deps_checker._run", return_value=(0, "active", "")):
+            result = check_cron()
+    assert result.status == "PASS"
+    assert "active" in result.message
+
+
+def test_cron_binary_missing_fails():
+    with mock.patch("modules.deps_checker.shutil.which", return_value=None):
+        result = check_cron()
+    assert result.status == "FAIL"
+    assert "crontab binary not found" in result.message
+
+
+def test_cron_installed_but_inactive_warns():
+    with mock.patch("modules.deps_checker.shutil.which", return_value="/usr/bin/crontab"):
+        with mock.patch("modules.deps_checker._run", return_value=(1, "inactive", "")):
+            result = check_cron()
+    assert result.status == "WARN"
+    assert "does not appear to be active" in result.message
+
+
+# ── check_user_profile_dir ──────────────────────────────────────────────────
+
+
+def test_profile_dir_exists(tmp_path):
+    result = check_user_profile_dir(str(tmp_path))
+    assert result.status == "PASS"
+    assert "exists" in result.message
+
+
+def test_profile_dir_missing_fails(tmp_path):
+    missing = tmp_path / "missing"
+    result = check_user_profile_dir(str(missing))
+    assert result.status == "FAIL"
+    assert "not found" in result.message
+
+
+def test_profile_dir_default_found(tmp_path, monkeypatch):
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    profile = fake_home / ".config" / "chromium" / "Default"
+    profile.mkdir(parents=True)
+    monkeypatch.setenv("HOME", str(fake_home))
+    result = check_user_profile_dir("")
+    assert result.status == "PASS"
+    assert "Found profile" in result.message
+
+
+# ── check_all ───────────────────────────────────────────────────────────────
+
+
+def test_check_all_returns_keyed_results():
+    with mock.patch("modules.deps_checker.shutil.which", return_value="/usr/bin/chromium"):
+        with mock.patch("modules.deps_checker._run", return_value=(0, "Python 3.11.4", "")):
+            with mock.patch("modules.deps_checker.check_pip_packages", return_value=CheckResult("pip packages", "PASS", "")):
+                with mock.patch("modules.deps_checker.check_user_profile_dir", return_value=CheckResult("Chrome profile", "PASS", "")):
+                    results = check_all("/tmp/profile")
+    assert set(results.keys()) == {"chrome", "python3", "pip_packages", "xvfb", "cron", "profile"}
diff --git a/tests/test_login_validator.py b/tests/test_login_validator.py
new file mode 100644
index 0000000..0a1f8a2
--- /dev/null
+++ b/tests/test_login_validator.py
@@ -0,0 +1,61 @@
+"""Tests for modules.login_validator.
+
+These tests document the heuristic login detection for any agent.
+They mock the browser layer.
+"""
+
+from unittest import mock
+
+import pytest
+
+from modules.login_validator import LoginStatus, validate_login, warn_user
+
+
+@pytest.fixture
+def fake_agent():
+    agent = mock.MagicMock()
+    agent.name = "fake.com"
+    agent.base_url = "https://fake.com"
+    agent.check_login = mock.MagicMock(return_value=LoginStatus(
+        is_logged_in=True, username="user", message="Logged in."
+    ))
+    agent.warn_not_logged_in = mock.MagicMock(return_value="Please log in to fake.com")
+    return agent
+
+
+# ── validate_login ──────────────────────────────────────────────────────────
+
+
+def test_validate_login_delegates_to_agent(fake_agent):
+    fake_session = mock.MagicMock()
+    status = validate_login(fake_session, fake_agent)
+    fake_agent.check_login.assert_called_once_with(fake_session)
+    assert status.is_logged_in is True
+    assert status.username == "user"
+
+
+# ── warn_user ───────────────────────────────────────────────────────────────
+
+
+def test_warn_user_delegates_to_agent(fake_agent):
+    status = LoginStatus(is_logged_in=False, username=None, message="nope")
+    msg = warn_user(status, fake_agent)
+    fake_agent.warn_not_logged_in.assert_called_once_with(status)
+    assert msg == "Please log in to fake.com"
+
+
+# ── get_browser_launch_hint ─────────────────────────────────────────────────
+
+
+def test_get_browser_launch_hint_prefers_chromium():
+    with mock.patch("shutil.which", side_effect=lambda b: b if b == "chromium" else None):
+        from modules.login_validator import get_browser_launch_hint
+        hint = get_browser_launch_hint()
+    assert hint == "chromium --remote-debugging-port=9222"
+
+
+def test_get_browser_launch_hint_falls_back_to_chrome():
+    with mock.patch("shutil.which", return_value=None):
+        from modules.login_validator import get_browser_launch_hint
+        hint = get_browser_launch_hint()
+    assert "google-chrome --remote-debugging-port=9222" in hint
diff --git a/tests/test_prompt_resolver.py b/tests/test_prompt_resolver.py
new file mode 100644
index 0000000..8eac0c4
--- /dev/null
+++ b/tests/test_prompt_resolver.py
@@ -0,0 +1,118 @@
+"""Tests for modules.prompt_resolver.
+
+These tests document how a task's prompt can be supplied as a string, a list of
+strings, or an external file, and how those forms are resolved to a single text.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from modules.prompt_resolver import resolve_prompt
+
+
+def test_resolve_prompt_string():
+    assert resolve_prompt("hello", None, "/tmp") == "hello"
+
+
+def test_resolve_prompt_list_joins_with_newlines():
+    assert resolve_prompt(["line one", "line two"], None, "/tmp") == "line one\nline two"
+
+
+def test_resolve_prompt_list_preserves_indentation():
+    """Leading whitespace is kept so code blocks and nested lists stay intact."""
+    assert resolve_prompt(["  line one", "    line two"], None, "/tmp") == "  line one\n    line two"
+
+
+def test_resolve_prompt_list_preserves_blank_lines():
+    """Empty list items become blank lines, creating paragraph breaks."""
+    prompt = ["paragraph one", "", "paragraph two"]
+    assert resolve_prompt(prompt, None, "/tmp") == "paragraph one\n\nparagraph two"
+
+
+def test_resolve_prompt_list_preserves_code_indentation():
+    prompt = [
+        "Review this Python function:",
+        "",
+        "```python",
+        "def hello():",
+        "    print('hello')",
+        "```",
+    ]
+    expected = (
+        "Review this Python function:\n\n"
+        "```python\n"
+        "def hello():\n"
+        "    print('hello')\n"
+        "```"
+    )
+    assert resolve_prompt(prompt, None, "/tmp") == expected
+
+
+def test_resolve_prompt_list_trims_whitespace_only_lines():
+    """Lines containing only whitespace are treated as blank lines."""
+    assert resolve_prompt(["one", "   ", "two"], None, "/tmp") == "one\n\ntwo"
+
+
+def test_resolve_prompt_file_takes_priority(tmp_path: Path):
+    prompt_file = tmp_path / "prompt.md"
+    prompt_file.write_text("from file", encoding="utf-8")
+    result = resolve_prompt("from string", str(prompt_file), str(tmp_path))
+    assert result == "from file"
+
+
+def test_resolve_prompt_file_relative_to_config_dir(tmp_path: Path):
+    prompt_file = tmp_path / "prompts" / "task.md"
+    prompt_file.parent.mkdir()
+    prompt_file.write_text("relative file", encoding="utf-8")
+    result = resolve_prompt(None, "prompts/task.md", str(tmp_path))
+    assert result == "relative file"
+
+
+def test_resolve_prompt_file_absolute_path(tmp_path: Path):
+    prompt_file = tmp_path / "task.md"
+    prompt_file.write_text("absolute file", encoding="utf-8")
+    result = resolve_prompt(None, str(prompt_file), str(tmp_path))
+    assert result == "absolute file"
+
+
+def test_resolve_prompt_file_expands_tilde(tmp_path: Path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    prompt_file = tmp_path / "task.md"
+    prompt_file.write_text("home file", encoding="utf-8")
+    result = resolve_prompt(None, "~/task.md", str(tmp_path))
+    assert result == "home file"
+
+
+def test_resolve_prompt_file_strips_trailing_whitespace(tmp_path: Path):
+    prompt_file = tmp_path / "prompt.md"
+    prompt_file.write_text("content\n\n", encoding="utf-8")
+    result = resolve_prompt(None, str(prompt_file), str(tmp_path))
+    assert result == "content"
+
+
+def test_resolve_prompt_missing_raises():
+    with pytest.raises(ValueError, match="prompt or prompt_file"):
+        resolve_prompt(None, None, "/tmp")
+
+
+def test_resolve_prompt_empty_string_raises():
+    with pytest.raises(ValueError, match="empty"):
+        resolve_prompt("", None, "/tmp")
+
+
+def test_resolve_prompt_empty_list_raises():
+    with pytest.raises(ValueError, match="empty"):
+        resolve_prompt([], None, "/tmp")
+
+
+def test_resolve_prompt_empty_file_raises(tmp_path: Path):
+    prompt_file = tmp_path / "empty.md"
+    prompt_file.write_text("   \n\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="empty"):
+        resolve_prompt(None, str(prompt_file), str(tmp_path))
+
+
+def test_resolve_prompt_file_not_found_raises(tmp_path: Path):
+    with pytest.raises(FileNotFoundError):
+        resolve_prompt(None, "missing.md", str(tmp_path))
diff --git a/tests/test_response_writer.py b/tests/test_response_writer.py
new file mode 100644
index 0000000..534ac21
--- /dev/null
+++ b/tests/test_response_writer.py
@@ -0,0 +1,108 @@
+"""Tests for modules.response_writer.
+
+These tests document how GrokAuto formats and persists task results to disk.
+"""
+
+import os
+import stat
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from modules.response_writer import (
+    format_batch_output,
+    format_output,
+    write_batch_results,
+    write_response,
+)
+from modules.task_executor import TaskResult
+
+
+@pytest.fixture
+def result() -> TaskResult:
+    return TaskResult(
+        task_id="gmail_check",
+        prompt="Check email",
+        response="No new emails at this time.",
+        status="SUCCESS",
+        duration_seconds=12.34,
+        timestamp="2026-07-12 09:01:16",
+    )
+
+
+# ── format_output ───────────────────────────────────────────────────────────
+
+
+def test_format_output_contains_metadata(result: TaskResult):
+    md = format_output(result)
+    assert "# GrokAuto Task Result" in md
+    assert "gmail_check" in md
+    assert "2026-07-12 09:01:16" in md
+    assert "SUCCESS" in md
+    assert "12.34s" in md
+
+
+def test_format_output_contains_prompt_and_response(result: TaskResult):
+    md = format_output(result)
+    assert "## Prompt" in md
+    assert "Check email" in md
+    assert "## Response" in md
+    assert "No new emails" in md
+
+
+# ── format_batch_output ─────────────────────────────────────────────────────
+
+
+def test_format_batch_output_summary_table():
+    r1 = TaskResult("t1", "p1", "ok", "SUCCESS", 1.0, "now")
+    r2 = TaskResult("t2", "p2", "", "ERROR", 2.0, "now")
+    md = format_batch_output([r1, r2])
+    assert "# GrokAuto Batch Results" in md
+    assert "Total Tasks" in md
+    assert "Successful" in md
+    assert "Errors" in md
+    assert "| t1 | SUCCESS |" in md
+    assert "| t2 | ERROR |" in md
+
+
+def test_format_batch_output_includes_individual_results():
+    r1 = TaskResult("t1", "p1", "ok", "SUCCESS", 1.0, "now")
+    md = format_batch_output([r1])
+    assert "## Prompt" in md
+    assert "## Response" in md
+
+
+# ── write_response ──────────────────────────────────────────────────────────
+
+
+def test_write_response_creates_file_with_restrictive_permissions(result: TaskResult, tmp_path: Path):
+    out = tmp_path / "out"
+    path = write_response(result, str(out))
+    assert Path(path).exists()
+    assert Path(path).read_text(encoding="utf-8") == format_output(result)
+    mode = stat.S_IMODE(os.stat(path).st_mode)
+    assert mode == 0o600
+
+
+def test_write_response_uses_task_id_in_filename(result: TaskResult, tmp_path: Path):
+    path = write_response(result, str(tmp_path))
+    assert Path(path).name.startswith("grok_response_gmail_check_")
+    assert Path(path).suffix == ".md"
+
+
+# ── write_batch_results ─────────────────────────────────────────────────────
+
+
+def test_write_batch_results_creates_summary_and_individual_files(tmp_path: Path):
+    r1 = TaskResult("t1", "p1", "ok", "SUCCESS", 1.0, "now")
+    r2 = TaskResult("t2", "p2", "", "ERROR", 2.0, "now")
+    summary_path = write_batch_results([r1, r2], str(tmp_path))
+    assert Path(summary_path).exists()
+    assert Path(summary_path).name.startswith("grok_batch_")
+    assert Path(summary_path).suffix == ".md"
+    # Individual files are also written.
+    files = list(tmp_path.glob("grok_response_*.md"))
+    assert len(files) == 2
+    mode = stat.S_IMODE(os.stat(summary_path).st_mode)
+    assert mode == 0o600
diff --git a/tests/test_task_executor.py b/tests/test_task_executor.py
new file mode 100644
index 0000000..659d743
--- /dev/null
+++ b/tests/test_task_executor.py
@@ -0,0 +1,231 @@
+"""Tests for modules.task_executor.
+
+These tests document the task execution helper functions and the dataclasses.
+They mock the browser layer so no real browser is needed.
+"""
+
+from unittest import mock
+
+import pytest
+
+from modules.task_executor import (
+    Task,
+    TaskResult,
+    _find_element_js,
+    capture_response,
+    execute_single_task,
+    execute_tasks,
+    send_prompt,
+    wait_for_streaming_complete,
+)
+
+
+def _make_fake_agent():
+    """Return a lightweight fake Agent for unit tests."""
+    agent = mock.MagicMock()
+    agent.name = "fake"
+    agent.base_url = "https://example.com"
+    agent.input_selectors = ['div[contenteditable="true"]', 'textarea']
+    agent.submit_selectors = ['button[type="submit"]', 'button']
+    agent.response_container_selectors = ['.response', '.message']
+    agent.streaming_indicator_selectors = ['.stop']
+    return agent
+
+
+@pytest.fixture
+def fake_agent():
+    return _make_fake_agent()
+
+
+# ── Dataclasses ─────────────────────────────────────────────────────────────
+
+
+def test_task_defaults():
+    t = Task(id="t1", prompt="hello")
+    assert t.wait_for_complete is True
+    assert t.timeout_seconds == 120
+
+
+def test_task_result_creation():
+    r = TaskResult(
+        task_id="t1",
+        prompt="hello",
+        response="world",
+        status="SUCCESS",
+        duration_seconds=1.23,
+        timestamp="now",
+    )
+    assert r.status == "SUCCESS"
+
+
+# ── _find_element_js ────────────────────────────────────────────────────────
+
+
+def test_find_element_js_joins_selectors():
+    script = _find_element_js(["a", "b", "c"])
+    assert "document.querySelector('a')" in script
+    assert "document.querySelector('b')" in script
+    assert " || " in script
+
+
+def test_find_element_js_uses_single_quotes_for_selectors():
+    agent = _make_fake_agent()
+    script = _find_element_js(agent.input_selectors[:2])
+    assert 'document.querySelector(\'div[contenteditable="true"]\')' in script
+
+
+# ── send_prompt ─────────────────────────────────────────────────────────────
+
+
+def test_send_prompt_returns_false_when_input_not_found(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.navigate_to"):
+        with mock.patch("modules.task_executor._find_any_element", return_value=None):
+            assert send_prompt(fake_session, fake_agent, "hello") is False
+
+
+def test_send_prompt_submits_when_input_found_and_button_found(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.navigate_to"):
+        with mock.patch("modules.task_executor._find_any_element", side_effect=["textarea", "button"]):
+            with mock.patch("modules.task_executor.execute_js") as js_mock:
+                js_mock.return_value = False  # not contenteditable
+                assert send_prompt(fake_session, fake_agent, "hello") is True
+                # Focus/clear/fill, wait loop checks, then click submit.
+                assert js_mock.call_count >= 3
+
+
+def test_send_prompt_falls_back_to_enter_key(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.navigate_to"):
+        with mock.patch("modules.task_executor._find_any_element", side_effect=["textarea", None]):
+            with mock.patch("modules.task_executor.execute_js") as js_mock:
+                js_mock.return_value = False
+                assert send_prompt(fake_session, fake_agent, "hello") is True
+                # The fallback path dispatches KeyboardEvents.
+                calls = [str(c) for c in js_mock.call_args_list]
+                assert any("KeyboardEvent" in c for c in calls)
+
+
+# ── wait_for_streaming_complete ─────────────────────────────────────────────
+
+
+def test_wait_for_streaming_complete_returns_true_when_stable(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.time") as mock_time:
+        # Values consumed: deadline(0), loop checks (1,2,3,4,5,6,7).
+        mock_time.time.side_effect = [0, 1, 2, 3, 4, 5, 6, 7]
+        mock_time.sleep = mock.MagicMock()
+        with mock.patch("modules.task_executor._is_element_visible", return_value=False):
+            with mock.patch("modules.task_executor.capture_response", return_value="long enough text"):
+                assert wait_for_streaming_complete(fake_session, fake_agent, timeout=10) is True
+
+
+def test_wait_for_streaming_complete_returns_false_on_timeout(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.time") as mock_time:
+        # Deadline = 0 + 5 = 5; provide enough ticks to exhaust the loop.
+        mock_time.time.side_effect = [0, 1, 2, 3, 4, 5, 6]
+        mock_time.sleep = mock.MagicMock()
+        with mock.patch("modules.task_executor._is_element_visible", return_value=False):
+            # Vary the captured text so stability is never reached.
+            with mock.patch("modules.task_executor.capture_response", side_effect=["a", "b", "c"] * 10):
+                assert wait_for_streaming_complete(fake_session, fake_agent, timeout=5) is False
+
+
+# ── capture_response ────────────────────────────────────────────────────────
+
+
+def test_capture_response_tries_selectors_in_order(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.execute_js") as js_mock:
+        # First selector returns short text, second returns meaningful text.
+        js_mock.side_effect = ["hi", "This is the assistant reply."]
+        result = capture_response(fake_session, fake_agent)
+        assert "assistant reply" in result
+        assert js_mock.call_count == 2
+
+
+def test_capture_response_falls_back_to_main_content(fake_agent):
+    fake_session = mock.MagicMock()
+    with mock.patch("modules.task_executor.execute_js") as js_mock:
+        js_mock.side_effect = [""] * len(fake_agent.response_container_selectors) + ["fallback paragraph"]
+        result = capture_response(fake_session, fake_agent)
+        assert result == "fallback paragraph"
+
+
+# ── execute_single_task ─────────────────────────────────────────────────────
+
+
+def test_execute_single_task_error_when_send_fails(fake_agent):
+    fake_session = mock.MagicMock()
+    task = Task(id="t1", prompt="hello")
+    with mock.patch("modules.task_executor.send_prompt", return_value=False):
+        result = execute_single_task(fake_session, fake_agent, task)
+    assert isinstance(result, TaskResult)
+    assert result.status == "ERROR"
+    assert result.response == ""
+
+
+def test_execute_single_task_success(fake_agent):
+    fake_session = mock.MagicMock()
+    task = Task(id="t1", prompt="hello")
+    with mock.patch("modules.task_executor.send_prompt", return_value=True):
+        with mock.patch("modules.task_executor.wait_for_streaming_complete", return_value=True):
+            with mock.patch("modules.task_executor.capture_response", return_value="done"):
+                result = execute_single_task(fake_session, fake_agent, task)
+    assert result.status == "SUCCESS"
+    assert result.response == "done"
+
+
+def test_execute_single_task_timeout_returns_partial(fake_agent):
+    fake_session = mock.MagicMock()
+    task = Task(id="t1", prompt="hello")
+    with mock.patch("modules.task_executor.send_prompt", return_value=True):
+        with mock.patch("modules.task_executor.wait_for_streaming_complete", return_value=False):
+            with mock.patch("modules.task_executor.capture_response", return_value="partial..."):
+                result = execute_single_task(fake_session, fake_agent, task)
+    assert result.status == "TIMEOUT"
+    assert result.response == "partial..."
+
+
+# ── execute_tasks ────────────────────────────────────────────────────────────
+
+
+def test_execute_tasks_runs_sequentially(fake_agent):
+    fake_session = mock.MagicMock()
+    tasks = [Task(id="t1", prompt="a"), Task(id="t2", prompt="b")]
+    agent_map = {"t1": fake_agent, "t2": fake_agent}
+    with mock.patch("modules.task_executor.execute_single_task") as single_mock:
+        single_mock.side_effect = [
+            TaskResult("t1", "a", "ra", "SUCCESS", 1.0, "now"),
+            TaskResult("t2", "b", "rb", "SUCCESS", 1.0, "now"),
+        ]
+        with mock.patch("modules.task_executor.time.sleep"):
+            results = execute_tasks(fake_session, tasks, agent_map)
+    assert len(results) == 2
+    assert results[0].task_id == "t1"
+    assert results[1].task_id == "t2"
+
+
+def test_execute_tasks_pauses_between_successes(fake_agent):
+    fake_session = mock.MagicMock()
+    tasks = [Task(id="t1", prompt="a"), Task(id="t2", prompt="b")]
+    agent_map = {"t1": fake_agent, "t2": fake_agent}
+    with mock.patch("modules.task_executor.execute_single_task") as single_mock:
+        single_mock.side_effect = [
+            TaskResult("t1", "a", "ra", "SUCCESS", 1.0, "now"),
+            TaskResult("t2", "b", "rb", "SUCCESS", 1.0, "now"),
+        ]
+        with mock.patch("modules.task_executor.time.sleep") as sleep_mock:
+            execute_tasks(fake_session, tasks, agent_map)
+            # Code sleeps after every SUCCESS, including the last task.
+            assert sleep_mock.call_count == 2
+            sleep_mock.assert_called_with(2)
+
+
+def test_execute_tasks_raises_when_agent_missing(fake_agent):
+    fake_session = mock.MagicMock()
+    tasks = [Task(id="t1", prompt="a")]
+    with pytest.raises(ValueError, match="No agent provided"):
+        execute_tasks(fake_session, tasks, {})