From 25a45467ac5a61ec92c5276d22ffbd88aadb9d5a Mon Sep 17 00:00:00 2001
From: Ezra <ezra@hermes.local>
Date: Sun, 5 Apr 2026 12:17:16 +0000
Subject: [PATCH] Add QUICKSTART.md for Deep Dive pipeline (#830)

Step-by-step guide for installation, dry-run testing, live
delivery, systemd timer enablement, and Telegram command setup.
---
 intelligence/deepdive/QUICKSTART.md | 79 +++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 intelligence/deepdive/QUICKSTART.md

diff --git a/intelligence/deepdive/QUICKSTART.md b/intelligence/deepdive/QUICKSTART.md
new file mode 100644
index 0000000..dca4a14
--- /dev/null
+++ b/intelligence/deepdive/QUICKSTART.md
@@ -0,0 +1,79 @@
+# Deep Dive Quick Start
+
+> Issue: [#830](http://143.198.27.163:3000/Timmy_Foundation/the-nexus/issues/830)  
+> One-page guide to running the sovereign daily intelligence pipeline.
+
+## Prerequisites
+
+- Python 3.10+
+- `git` and `make`
+- Local LLM endpoint at `http://localhost:4000/v1` (or update `config.yaml`)
+- Telegram bot token in environment (`TELEGRAM_BOT_TOKEN`)
+
+## Install (5 minutes)
+
+```bash
+cd /root/wizards/the-nexus/intelligence/deepdive
+make install
+```
+
+This creates a virtual environment, installs dependencies, and downloads the 80MB embeddings model.
+
+## Run a Dry-Run Test
+
+No delivery, no audio — just aggregation + relevance + synthesis:
+
+```bash
+make test-e2e
+```
+
+Expected output: a JSON briefing saved to `~/.cache/deepdive/briefing_*.json`
+
+## Run with Live Delivery
+
+```bash
+# 1. Copy and edit config
+cp config.yaml config.local.yaml
+# Edit synthesis.llm_endpoint and delivery.bot_token if needed
+
+# 2. Run pipeline
+python pipeline.py --config config.local.yaml --since 24
+```
+
+## Enable Daily 06:00 Delivery
+
+```bash
+make install-systemd
+systemctl --user status deepdive.timer
+```
+
+The timer will run `pipeline.py --config config.yaml` every day at 06:00 with a 5-minute randomized delay.
+
+## Telegram On-Demand Command
+
+For Hermes agents, register `telegram_command.py` as a bot command handler:
+
+```python
+from telegram_command import deepdive_handler
+
+# In your Hermes Telegram gateway:
+commands.register("/deepdive", deepdive_handler)
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `feedparser` not found | Run `make install` |
+| LLM connection refused | Verify llama-server is running on port 4000 |
+| Empty briefing | arXiv RSS may be slow; increase `--since 48` |
+| Telegram not sending | Check `TELEGRAM_BOT_TOKEN` and `channel_id` in config |
+| No audio generated | Set `audio.enabled: true` in config; ensure `piper` is installed |
+
+## Next Steps
+
+1. Run `make test-e2e` to verify the pipeline works on your host
+2. Configure `config.yaml` with your Telegram channel and LLM endpoint
+3. Run one live delivery manually
+4. Enable systemd timer for daily automation
+5. Register `/deepdive` in your Telegram bot for on-demand requests