Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Sho'Nuff Inbox Monitoring — Collection + LLM Summary Pattern
+
+## Architecture
+
+Two-tier hybrid: **no_agent collection script** + **agentic cron** for summarization.
+
+### Layer 1: Data collection (no_agent script)
+
+Script at `/root/.hermes/scripts/shonuff-inbox-collect.py` — runs every 15m:
+
+1. Connects to IMAP (shonuff@germainebrown.com)
+2. Fetches UNSEEN messages
+3. For each message NOT from trusted senders (g@germainebrown.com):
+   - Extracts: sender, subject, date, body preview (first 500 chars)
+   - Generates hash from Message-ID for dedup
+   - Outputs JSON with messages array
+4. Marks processed messages as `\\Seen` (prevents re-processing)
+5. Silent (no output) when nothing new
+
+**Trusted senders filter:** Trusted senders (user's own address) are skipped silently — no alert, no output.
+
+**Dedup:** Uses hashed Message-ID in `~/.hermes/scripts/.shonuff-processed.json`. This file persists across reboots. Each message reports exactly once.
+
+### Layer 2: Agentic cron job
+
+Connected to the collection script via `cronjob()`:
+
+```bash
+cronjob(action='create', name='shonuff-inbox-agent',
+  schedule='every 15m',
+  script='shonuff-inbox-collect.py',
+  prompt='Check the collected inbox data above. If there are new messages in ShoNuff's inbox (shonuff@germainebrown.com), summarize each one for Germaine... respond with SILENT.',
+  deliver='origin')
+```
+
+### When collection script is empty
+
+When the collection script exits with no output (no new messages), the agent receives an **empty context**. The prompt must include an explicit instruction: "If no new messages or only messages from trusted senders, respond with SILENT."
+
+## Key design choices
+
+- **Trusted sender list**: Only the user's own email
+- **Body truncation**: First 500 chars only
+- **Hash dedup**: Prevents re-alerting on the same message
+- **Message-ID fallback**: Falls back to IMAP sequence number when missing
+
+## Comparison to bounce-check
+
+| Aspect | shonuff-inbox-agent | bounce-check |
+|---|---|---|
+| Scope | All non-trusted senders | Only delivery-failure emails |
+| Accounts | shonuff only | Both g@ and shonuff@ |
+| Output | JSON → LLM summarizes | Plain text count |
+| Cadence | Every 15m | Every 60m |
+| Cron type | Agentic (LLM) | no_agent |
+
+## Pitfalls
+
+- **Message-ID is optional in the SMTP spec** — duplicate alert risk
+- **IMAP UNSEEN state is sticky** — if LLM call fails between collection and delivery, the message is silently lost. Consider pending-file for reliability.