plan: omnichannel messaging + social media parity (v3)

- Corrected gap analysis against actual codebase state - Signal, WhatsApp, Matrix, Google Chat adapters already exist - Business/professional accounts for all social media - WhatsApp: dual approach (Baileys dev + Cloud API prod) - Native apps: Signal fork (iOS, Android, Desktop) - 7-phase, 24-week implementation plan - Social media: X, Instagram, Facebook, YouTube, Reddit, TikTok - Aurélio surfaces integration: Theia, VS Code, Web portal
2026-07-12 15:05:39 +01:00 · 2026-07-12 15:05:39 +01:00 · bb2775769c
commit bb2775769c
parent b77654484e
1 changed files with 527 additions and 0 deletions
--- a/.aurelio/projects/aurelio/plans/2026-07-12-hermes-multiplatform-parity.md
+++ b/.aurelio/projects/aurelio/plans/2026-07-12-hermes-multiplatform-parity.md
@ -0,0 +1,527 @@
+# Aurélio — Omnichannel Messaging & Social Media Parity Plan (v3)
+
+**Date:** 2026-07-12  
+**Author:** Hermes Agent (CT 217) + opencode research  
+**Status:** DRAFT v3 — corrected for actual codebase state, business accounts, Signal fork strategy  
+**Scope:** Achieve 100% feature parity with Hermes Agent's Telegram gateway across all messaging platforms and social media channels. Native mobile/desktop apps forked from Signal's open-source stack. All social media uses professional/business accounts.
+
+---
+
+## 1. Corrected Current State — What Already Exists
+
+The v1 plan significantly understated existing infrastructure. This section is the accurate baseline.
+
+### 1.1 Hermes Agent Platform Adapters (Already Production-Ready)
+
+| Platform | Adapter Location | Status | Notes |
+|---|---|---|---|
+| **Telegram** | `plugins/platforms/telegram/adapter.py` | ✅ Production | `python-telegram-bot`, MarkdownV2, media, voice, forum threads |
+| **Signal** | `gateway/platforms/signal.py` | ✅ Production | signal-cli JSON-RPC, SSE listener, rate limiting, formatting |
+| **WhatsApp (Cloud)** | `gateway/platforms/whatsapp_cloud.py` | ✅ Production | Meta Cloud API, native JIDs, media via `/send-media` |
+| **WhatsApp (Baileys)** | `plugins/platforms/whatsapp/adapter.py` | ✅ Production | Baileys 7.0.0-rc13, QR auth, IPC bridge |
+| **Matrix** | Built-in adapter | ✅ Production | E2E bootstrap test exists; CT 215 Synapse running |
+| **Google Chat** | `plugins/platforms/google_chat/` | ✅ Production | OAuth, spaces, threads, attachments, setup wizard |
+| **Discord** | Plugin (migrated) | ✅ Production | Full adapter |
+| **Slack** | Plugin (migrated) | ✅ Production | Full adapter |
+| **Email** | Built-in | ✅ Production | SMTP/IMAP |
+| **+ 14 more** | Various | ✅ Production | DingTalk, Feishu, WeCom, Weixin, BlueBubbles, QQBot, Yuanbao, ntfy, SMS, XMPP, etc. |
+
+**Key tool:** `send_message` (`tools/send_message_tool.py`, ~1200 lines) — cross-channel messaging with send/list/react/unreact, media, chunking, name resolution, platform-specific formatting. Supports 15+ platforms natively.
+
+### 1.2 Infrastructure (Already Deployed)
+
+| Component | Location | Status |
+|---|---|---|
+| **signal-cli daemon** | Gigabyte 192.168.0.104:18088 | ✅ Running, Cloudflare tunnel `signal.portugalfuturista.org` |
+| **Signal-Server** | `nervura-electrica/services/signal/Signal-Server/` | ⚠️ Docker Compose staged, not confirmed running |
+| **Signal-Android** | `/home/fabiorafaelcoutada/portugalfuturista/Signal-Android/` | ✅ Cloned (not forked) |
+| **Signal-iOS** | `/home/fabiorafaelcoutada/portugalfuturista/Signal-iOS/` | ✅ Cloned (not forked) |
+| **Signal-Desktop** | `/home/fabiorafaelcoutada/portugalfuturista/Signal-Desktop/` | ✅ Cloned (not forked) |
+| **libsignal** | `/home/fabiorafaelcoutada/portugalfuturista/libsignal/` | ✅ Cloned |
+| **aurelio-ringrtc** | `/home/fabiorafaelcoutada/portugalfuturista/aurelio-ringrtc/` | ✅ Cloned |
+| **Matrix Synapse** | CT 215 (192.168.0.25), `matrix.portugalfuturista.org` | ✅ Running (178 MB RAM) |
+| **Hermes bot** | `@hermes:matrix.portugalfuturista.org` on CT 217 | ✅ Active |
+| **Hermes Desktop** | `hermes-agent/apps/desktop/` | ✅ Production Electron 40.x, React 19 |
+| **Forgejo** | CT 203, `code.portugalfuturista.org` | ✅ Operational |
+| **WhatsApp (Rowboat)** | `rowboat/apps/x/` | ✅ Baileys transport with QR auth |
+
+### 1.3 What's Actually Missing
+
+| Gap | Impact | Priority |
+|---|---|---|
+| **No `aurelio-ios` repo on Forgejo** | Can't build native iOS app | High |
+| **No `aurelio-android` repo on Forgejo** | Can't build native Android app | High |
+| **No `aurelio-desktop` repo on Forgejo** | Can't build branded desktop app | High |
+| **Matrix E2EE not implemented** | Messages transit in plaintext | High |
+| **No Cloudflare tunnel for Matrix** | No public access to Synapse | High |
+| **No social media adapters** | Zero X/Instagram/Facebook/YouTube/Reddit/TikTok presence | Medium |
+| **No Aurélio messaging UI in IDE surfaces** | Theia/VS Code/web can't send/receive Signal/WhatsApp messages | Medium |
+| **No unified config for all platforms** | Each platform configured independently | Low |
+
+---
+
+## 2. Target Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Hermes Agent Core                               │
+│   (LLM loop, tools, memory, skills, cron, subagents, TTS, vision)       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                │
+          ┌─────────────────────┼─────────────────────┐
+          ▼                     ▼                     ▼
+   ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+   │  Messaging  │       │   Social    │       │   Native    │
+   │  Gateways   │       │   Media     │       │   Apps      │
+   │             │       │   Gateways  │       │             │
+   │ • Telegram  │       │ • X         │       │ • iOS       │
+   │ • Signal    │       │ • Instagram │       │   (Signal   │
+   │ • WhatsApp  │       │ • Facebook  │       │    fork)    │
+   │   (Cloud)   │       │ • YouTube   │       │ • Android   │
+   │ • WhatsApp  │       │ • Reddit    │       │   (Signal   │
+   │   (Baileys) │       │ • TikTok    │       │    fork)    │
+   │ • Google    │       └─────────────┘       │ • Desktop   │
+   │   Chat      │                             │   (Signal   │
+   │ • Matrix    │                             │    fork)    │
+   └─────────────┘                             └─────────────┘
+          │                                           │
+          ▼                                           ▼
+   ┌─────────────┐                             ┌─────────────┐
+   │  Platform   │                             │  Aurélio    │
+   │  APIs       │                             │  Surfaces   │
+   │  (Business) │                             │             │
+   └─────────────┘                             │ • Theia IDE │
+                                               │ • VS Code   │
+                                               │ • Web Portal│
+                                               │ • TUI       │
+                                               └─────────────┘
+```
+
+---
+
+## 3. Business/Professional Account Strategy
+
+All platforms use official business/developer accounts. No web scraping, no ToS violations.
+
+### 3.1 Messaging Platforms
+
+| Platform | Account Type | API | Cost |
+|---|---|---|---|
+| **Signal** | Dedicated phone number | signal-cli (self-hosted) | Free |
+| **WhatsApp** | Meta Business Account + WhatsApp Business API | Cloud API (official) | ~$0.005/conversation |
+| **Google Chat** | Google Workspace account | Chat API (REST) | Workspace license |
+| **Matrix** | Self-hosted Synapse | Client-Server API | Free (self-hosted) |
+
+### 3.2 Social Media Platforms
+
+| Platform | Account Type | API | Rate Limits |
+|---|---|---|---|
+| **X (Twitter)** | X Developer Professional | API v2 (OAuth 2.0) | 300 tweets/3h, 1000 DMs/day, 500K tweets/month read |
+| **Instagram** | Meta Business Suite + Instagram Business Account | Instagram Graph API | 25 posts/day, 100 comments/hour |
+| **Facebook** | Meta Business Suite + Facebook Page | Facebook Graph API | 200 calls/user/hour |
+| **YouTube** | YouTube Partner Program / Brand Account | Data API v3 | 10,000 units/day |
+| **Reddit** | Reddit API (professional app) | Reddit API (OAuth 2.0) | 60 requests/minute |
+| **TikTok** | TikTok for Business + Content Posting API | Marketing API + Content API | 1000 requests/day (marketing) |
+
+### 3.3 Meta Ecosystem Advantage
+
+One Meta Business Account unlocks **three platforms** simultaneously:
+- WhatsApp Business API (customer messaging)
+- Instagram Graph API (visual content)
+- Facebook Graph API (page management)
+
+This is the highest-leverage account to set up first.
+
+---
+
+## 4. Native Apps Strategy — Signal Fork (Rebranded)
+
+### 4.1 Why Signal Fork
+
+- **E2EE by default** — Signal Protocol / libsignal is battle-tested
+- **Proven UX** — Signal's interface is clean, fast, familiar
+- **Open source** — AGPL-3.0 (iOS/Android), full source available
+- **Self-hostable** — Signal-Server exists (Java + FoundationDB)
+
+### 4.2 App Forks
+
+| Platform | Base Repo | Target Repo on Forgejo | Build Requirements |
+|---|---|---|---|
+| **iOS** | `signalapp/Signal-iOS` | `portugalfuturista/aurelio-ios` | macOS + Xcode 15+, Swift 5.9+ |
+| **Android** | `signalapp/Signal-Android` | `portugalfuturista/aurelio-android` | Android SDK/NDK, Gradle, JDK 17+ |
+| **Desktop** | `signalapp/Signal-Desktop` | `portugalfuturista/aurelio-desktop` | Node 20+, Electron 30+, npm |
+
+### 4.3 Customizations Per App
+
+| Customization | iOS | Android | Desktop |
+|---|---|---|---|
+| **Branding** (logo, colors, splash) | ✅ | ✅ | ✅ |
+| **Server endpoint** → `matrix.portugalfuturista.org` | ✅ | ✅ | ✅ |
+| **Aurélio bot chat** (always-available agent) | ✅ | ✅ | ✅ |
+| **Voice notes** (TTS from Aurélio) | ✅ | ✅ | ✅ |
+| **Rich media** (code blocks, tables, math) | ✅ | ✅ | ✅ |
+| **Plugin system** (Aurélio triggers app actions) | ✅ | ✅ | ✅ |
+
+### 4.4 Implementation Phases
+
+| Phase | Duration | Deliverable |
+|---|---|---|
+| **4.1** — Fork repos + CI/CD | 2 weeks | 3 repos on Forgejo, build pipelines, basic branding |
+| **4.2** — Custom server endpoint | 3 weeks | All apps connect to Matrix/Hermes backend |
+| **4.3** — Aurélio bot integration | 2 weeks | Agent chat always available in all apps |
+| **4.4** — Voice + rich media | 2 weeks | TTS voice notes, code/table rendering |
+| **4.5** — Plugin system | 2 weeks | Aurélio can trigger in-app actions |
+| **4.6** — Store submission | 1 week | App Store / Play Store / direct distribution |
+
+---
+
+## 5. Implementation Phases (Revised)
+
+### Phase 0: Foundation Cleanup (Week 1)
+**Goal:** Correct infrastructure gaps before building on top.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 0.1 | Audit CT 217 Hermes gateway — confirm Signal, WhatsApp, Matrix adapters are connected and healthy | 0.5d | None |
+| 0.2 | Configure Cloudflare tunnel for Matrix (CT 215 → `matrix.portugalfuturista.org`) | 0.5d | CT 215 access |
+| 0.3 | Create `aurelio-ios`, `aurelio-android`, `aurelio-desktop` repos on Forgejo | 0.5d | Forgejo admin |
+| 0.4 | Set up Meta Business Account (unlocks WhatsApp + Instagram + Facebook) | 1d | Meta Business verification |
+| 0.5 | Apply for X Developer Professional account | 0.5d | X developer portal |
+| 0.6 | Apply for YouTube Data API quota increase | 0.5d | Google Cloud Console |
+| 0.7 | Create Reddit professional app | 0.5d | Reddit developer portal |
+| 0.8 | Unified `~/.hermes/config.yaml` with all platform sections | 1d | None |
+
+**Deliverable:** All accounts applied for, repos created, Matrix publicly accessible.
+
+### Phase 1: Matrix E2EE + Messaging Consolidation (Weeks 2–3)
+**Goal:** Matrix fully operational with E2EE; all existing messaging adapters verified.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 1.1 | Implement E2EE key management (Olm/Megolm) in Hermes Matrix adapter | 3d | Matrix spec study |
+| 1.2 | Cross-signing and device verification | 2d | Task 1.1 |
+| 1.3 | End-to-end test: send encrypted message from Hermes to Element client | 1d | Tasks 1.1-1.2 |
+| 1.4 | Audit Signal adapter — verify inbound/outbound, media, rate limiting | 0.5d | None |
+| 1.5 | Audit WhatsApp Cloud adapter — verify webhook, media, business API flow | 0.5d | Meta Business Account |
+| 1.6 | Audit Google Chat adapter — verify OAuth, spaces, card rendering | 0.5d | Workspace account |
+| 1.7 | Write integration tests for all 4 messaging platforms | 2d | Tasks 1.1-1.6 |
+| 1.8 | Document platform setup in `~/.hermes/config.yaml` with examples | 0.5d | None |
+
+**Deliverable:** Matrix E2EE working; all 4 messaging platforms audited and tested.
+
+### Phase 2: WhatsApp Business API (Weeks 4–5)
+**Goal:** WhatsApp fully operational via both dev (Baileys) and prod (Cloud API) paths.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 2.1 | Set up WhatsApp Business API via Meta Cloud API (phone number, display name, profile) | 1d | Meta Business Account |
+| 2.2 | Configure webhook endpoint (Cloud API → Hermes) | 1d | CT 217 access |
+| 2.3 | Test `whatsapp_cloud.py` adapter against real Business API | 1d | Tasks 2.1-2.2 |
+| 2.4 | Set up Baileys bridge for local dev/testing (`whatsapp-web.js` / Rowboat) | 1d | None |
+| 2.5 | Media pipeline: send/receive images, audio, video, documents via Cloud API | 1d | Task 2.3 |
+| 2.6 | Rich-text converter: Markdown → WhatsApp formatting (bold, italic, monospace) | 0.5d | None |
+| 2.7 | Group chat support via Business API | 1d | Task 2.3 |
+| 2.8 | Integration tests: Baileys (dev) + Cloud API (prod) | 1d | Tasks 2.4, 2.7 |
+| 2.9 | Rate limiting and error handling for Cloud API | 0.5d | Task 2.3 |
+
+**Deliverable:** WhatsApp working in both dev (Baileys) and prod (Cloud API) modes.
+
+### Phase 3: Social Media Gateways (Weeks 6–10)
+**Goal:** All 6 social media platforms connected for publishing and monitoring.
+
+#### Week 6–7: X + Instagram + Facebook (Meta ecosystem)
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 3.1 | X gateway: OAuth 2.0, tweet posting, thread support | 2d | X Developer Professional |
+| 3.2 | X gateway: mention monitoring, DM handling | 1d | Task 3.1 |
+| 3.3 | X gateway: media upload (images, videos, GIFs) | 1d | Task 3.1 |
+| 3.4 | Instagram gateway: Meta Business linkage, photo/carousel posting | 2d | Meta Business Account |
+| 3.5 | Instagram gateway: comment monitoring, story updates | 1d | Task 3.4 |
+| 3.6 | Facebook gateway: page management, post publishing | 2d | Meta Business Account |
+| 3.7 | Facebook gateway: comment monitoring, group engagement | 1d | Task 3.6 |
+| 3.8 | Unified Meta API client (shared auth, rate limiting) | 1d | Tasks 3.4-3.7 |
+
+#### Week 8–9: YouTube + Reddit + TikTok
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 3.9 | YouTube gateway: OAuth, video upload, thumbnail management | 2d | YouTube API quota |
+| 3.10 | YouTube gateway: comment monitoring, community posts | 1d | Task 3.9 |
+| 3.11 | YouTube gateway: live stream integration (if API allows) | 1d | Task 3.9 |
+| 3.12 | Reddit gateway: OAuth, post creation, subreddit monitoring | 2d | Reddit professional app |
+| 3.13 | Reddit gateway: comment monitoring, mod tools | 1d | Task 3.12 |
+| 3.14 | TikTok gateway: Marketing API setup, video posting | 2d | TikTok for Business |
+| 3.15 | TikTok gateway: comment monitoring (if API allows) | 1d | Task 3.14 |
+
+#### Week 10: Unified Scheduler + Testing
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 3.16 | Social media scheduler (cron-based posting pipeline) | 2d | Tasks 3.1-3.15 |
+| 3.17 | Integration tests for all 6 platforms | 2d | Tasks 3.1-3.16 |
+| 3.18 | Rate limit dashboard (all platforms) | 1d | Tasks 3.1-3.16 |
+
+**Deliverable:** All 6 social media platforms publishing, monitoring, and rate-limited.
+
+### Phase 4: Native Apps — Signal Fork (Weeks 11–18)
+**Goal:** Aurélio-branded iOS, Android, and Desktop apps based on Signal's codebase.
+
+#### Week 11–12: Fork + CI/CD + Branding
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 4.1 | Fork Signal-iOS → `aurelio-ios` on Forgejo | 0.5d | Forgejo repo |
+| 4.2 | Fork Signal-Android → `aurelio-android` on Forgejo | 0.5d | Forgejo repo |
+| 4.3 | Fork Signal-Desktop → `aurelio-desktop` on Forgejo | 0.5d | Forgejo repo |
+| 4.4 | Set up CI/CD: iOS (Xcode Cloud or GitHub Actions), Android (Gradle), Desktop (Electron Builder) | 3d | Tasks 4.1-4.3 |
+| 4.5 | Basic branding: logo, colors, splash screens, app names | 3d | Tasks 4.1-4.3 |
+| 4.6 | Configure server endpoint: `matrix.portugalfuturista.org` | 2d | Tasks 4.1-4.3, Matrix running |
+
+#### Week 13–14: Server Endpoint + Bot Integration
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 4.7 | Point all apps at Matrix homeserver (not Signal servers) | 2d | Task 4.6 |
+| 4.8 | Implement Aurélio bot chat — always-available agent conversation | 3d | Tasks 4.7, Hermes gateway |
+| 4.9 | Session persistence across devices | 2d | Task 4.7 |
+| 4.10 | Push notifications via Matrix | 2d | Task 4.7 |
+
+#### Week 15–16: Voice + Rich Media
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 4.11 | Voice notes: TTS from Aurélio → voice bubble in app | 2d | Hermes TTS tool |
+| 4.12 | Rich media: code blocks, tables, math rendering | 3d | Task 4.7 |
+| 4.13 | Media pipeline: send/receive images, video, documents | 2d | Task 4.7 |
+| 4.14 | Image understanding: vision_analyze for user-sent photos | 1d | Hermes vision tool |
+
+#### Week 17–18: Polish + Distribution
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 4.15 | Plugin system: Aurélio can trigger in-app actions | 3d | Tasks 4.8-4.14 |
+| 4.16 | App Store submission (iOS) | 1d | Apple Developer account |
+| 4.17 | Play Store submission (Android) | 1d | Google Play account |
+| 4.18 | Desktop distribution: DMG/MSI/AppImage + auto-updater | 2d | Task 4.3 |
+| 4.19 | End-to-end testing: all 3 apps against Matrix/Hermes | 2d | Tasks 4.1-4.18 |
+
+**Deliverable:** 3 native apps in stores, all connected to Matrix/Hermes backend.
+
+### Phase 5: Aurélio Surfaces Integration (Weeks 19–21)
+**Goal:** Theia, VS Code, and web portal can send/receive messages across all platforms.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 5.1 | Theia messaging widget — unified inbox across all platforms | 3d | Phase 1-3 complete |
+| 5.2 | VS Code extension — messaging sidebar (Signal, WhatsApp, Matrix) | 2d | Phase 1-3 complete |
+| 5.3 | Web portal — messaging panel | 2d | Phase 1-3 complete |
+| 5.4 | Cross-surface message sync (read receipts, typing indicators) | 2d | Tasks 5.1-5.3 |
+| 5.5 | Social media posting from IDE surfaces | 2d | Phase 3 complete |
+| 5.6 | Unified notification system (all platforms) | 1d | Tasks 5.1-5.5 |
+
+**Deliverable:** Full messaging + social media integration in all Aurélio surfaces.
+
+### Phase 6: Unified Config + Operations (Week 22)
+**Goal:** Single config surface, CLI commands, monitoring.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 6.1 | Extend `~/.hermes/config.yaml` with all platform + social media sections | 0.5d | None |
+| 6.2 | `hermes gateway status` — show all platforms health | 0.5d | None |
+| 6.3 | `hermes gateway restart <platform>` — restart individual gateways | 0.5d | None |
+| 6.4 | Health dashboard (all platforms, rate limits, uptime) | 1d | Tasks 6.1-6.3 |
+| 6.5 | Documentation: setup guides for each platform | 1.5d | All phases complete |
+
+**Deliverable:** Unified operations surface for all platforms.
+
+### Phase 7: Testing + Hardening (Weeks 23–24)
+**Goal:** Production-ready across all platforms.
+
+| Task | Description | Effort | Dependencies |
+|---|---|---|---|
+| 7.1 | Load testing: 100 messages/minute per platform | 2d | All phases complete |
+| 7.2 | Chaos testing: kill gateway mid-conversation, verify recovery | 1d | All phases complete |
+| 7.3 | Security audit: pen testing on all gateways | 2d | All phases complete |
+| 7.4 | E2EE verification: Matrix + Signal key exchange validation | 1d | Phase 1, 4 complete |
+| 7.5 | App testing: Firebase Test Lab (Android), TestFlight (iOS), automated UI | 2d | Phase 4 complete |
+
+**Deliverable:** Production-hardened system ready for deployment.
+
+---
+
+## 6. Configuration Schema
+
+```yaml
+# ~/.hermes/config.yaml — full platform config
+gateways:
+  telegram:
+    enabled: true
+    bot_token: "${TELEGRAM_BOT_TOKEN}"
+    home_channel: "6105354046"
+    polling: true
+
+  signal:
+    enabled: true
+    cli_url: "http://192.168.0.104:18088"
+    phone_number: "${SIGNAL_PHONE_NUMBER}"
+    home_channel: "+351XXXXXXXXX"
+
+  whatsapp:
+    enabled: true
+    mode: "cloud"  # "cloud" (prod) or "baileys" (dev)
+    cloud:
+      phone_number_id: "${WHATSAPP_PHONE_NUMBER_ID}"
+      access_token: "${WHATSAPP_ACCESS_TOKEN}"
+      verify_token: "${WHATSAPP_VERIFY_TOKEN}"
+      app_secret: "${WHATSAPP_APP_SECRET}"
+    baileys:
+      session_path: "~/.hermes/whatsapp-session"
+    home_channel: "+351XXXXXXXXX"
+
+  google-chat:
+    enabled: false
+    credentials_path: "~/.hermes/google-chat-credentials.json"
+    home_channel: "spaces/AAAA..."
+
+  matrix:
+    enabled: true
+    homeserver: "https://matrix.portugalfuturista.org"
+    access_token: "${MATRIX_ACCESS_TOKEN}"
+    home_channel: "!room:portugalfuturista.org"
+    e2ee:
+      enabled: true
+      device_id: "HERMES"
+
+social_media:
+  x:
+    enabled: false
+    api_key: "${X_API_KEY}"
+    api_secret: "${X_API_SECRET}"
+    access_token: "${X_ACCESS_TOKEN}"
+    access_token_secret: "${X_ACCESS_TOKEN_SECRET}"
+
+  instagram:
+    enabled: false
+    business_account_id: "${INSTAGRAM_BUSINESS_ACCOUNT_ID}"
+    access_token: "${INSTAGRAM_ACCESS_TOKEN}"
+
+  facebook:
+    enabled: false
+    page_id: "${FACEBOOK_PAGE_ID}"
+    access_token: "${FACEBOOK_ACCESS_TOKEN}"
+
+  tiktok:
+    enabled: false
+    client_key: "${TIKTOK_CLIENT_KEY}"
+    client_secret: "${TIKTOK_CLIENT_SECRET}"
+    access_token: "${TIKTOK_ACCESS_TOKEN}"
+
+  youtube:
+    enabled: false
+    credentials_path: "~/.hermes/youtube-credentials.json"
+    channel_id: "${YOUTUBE_CHANNEL_ID}"
+
+  reddit:
+    enabled: false
+    client_id: "${REDDIT_CLIENT_ID}"
+    client_secret: "${REDDIT_CLIENT_SECRET}"
+    username: "${REDDIT_USERNAME}"
+    password: "${REDDIT_PASSWORD}"
+
+native_apps:
+  ios:
+    enabled: false
+    bundle_id: "org.portugalfuturista.aurelio"
+    team_id: "${APPLE_TEAM_ID}"
+  android:
+    enabled: false
+    package_name: "org.portugalfuturista.aurelio"
+  desktop:
+    enabled: false
+    auto_update_url: "https://updates.portugalfuturista.org/aurelio-desktop"
+```
+
+---
+
+## 7. Timeline Summary
+
+| Weeks | Phase | Focus | Status |
+|---|---|---|---|
+| 1 | Phase 0 | Foundation cleanup, account setup, repos | ⬜ Pending |
+| 2–3 | Phase 1 | Matrix E2EE + messaging audit | ⬜ Pending |
+| 4–5 | Phase 2 | WhatsApp Business API (Cloud + Baileys) | ⬜ Pending |
+| 6–10 | Phase 3 | Social media gateways (6 platforms) | ⬜ Pending |
+| 11–18 | Phase 4 | Native apps (Signal fork: iOS, Android, Desktop) | ⬜ Pending |
+| 19–21 | Phase 5 | Aurélio surfaces integration (Theia, VS Code, Web) | ⬜ Pending |
+| 22 | Phase 6 | Unified config + operations | ⬜ Pending |
+| 23–24 | Phase 7 | Testing + hardening | ⬜ Pending |
+
+**Total: 24 weeks (6 months)**
+
+---
+
+## 8. Security & Operational Considerations
+
+| Concern | Mitigation |
+|---|---|
+| **Single-owner polling** | Only one gateway instance per platform; use file locks or Redis |
+| **Token storage** | All tokens in environment variables or `~/.hermes/secrets/` (mode 600) |
+| **Rate limiting** | Per-platform rate limiters; exponential backoff on errors |
+| **Session hijacking** | WhatsApp Web sessions tied to paired phone; monitor for unexpected logouts |
+| **Message ordering** | Per-chat sequence numbers; SQLite-backed queue for outbound |
+| **Crash recovery** | Systemd services with `Restart=always`; health checks every 30s |
+| **E2EE keys** | Matrix E2EE keys in `~/.hermes/matrix-keys/` (mode 700); backup to encrypted volume |
+| **Social media tokens** | OAuth tokens with refresh rotation; store in encrypted secrets manager |
+| **App signing** | iOS/Android signing keys in HSM or secure enclave; never in repo |
+| **ToS compliance** | Business APIs only (Cloud API, Graph API, X API v2); no scraping |
+
+---
+
+## 9. Testing Strategy
+
+| Level | Approach |
+|---|---|
+| **Unit** | Mock platform APIs; test message normalization, rich-text conversion |
+| **Integration** | Real platform sandboxes (Telegram test bot, Signal test number, Meta sandbox) |
+| **E2E** | Automated message round-trips: send → receive → respond → verify |
+| **Load** | 100 messages/minute per platform; measure latency and memory |
+| **Chaos** | Kill gateway mid-conversation; verify session recovery |
+| **Security** | Pen testing on all gateways; E2EE key exchange verification |
+| **App testing** | Firebase Test Lab (Android), TestFlight (iOS), automated UI tests |
+
+---
+
+## 10. Open Questions
+
+1. **Signal-Server:** Do we run our own Signal-Server (Java + FoundationDB) for the native apps, or use Matrix as the transport backend? The Docker Compose exists but isn't running.
+2. **Apple Developer account:** Do we have one, or need to create one for iOS distribution?
+3. **Google Play account:** Same question for Android.
+4. **TikTok API access:** The official Content Posting API is limited. Do we apply for elevated access or skip TikTok for v1?
+5. **Social media persona:** Should Aurélio have a distinct voice/persona on social media, or mirror the user's style?
+6. **WhatsApp Business verification:** Meta requires business verification (may take 1-2 weeks). Should we start this in Phase 0?
+7. **Live stream integration:** YouTube live streams via API — is this in scope for v1?
+
+---
+
+## 11. References
+
+- [Hermes Agent Docs](https://hermes-agent.nousresearch.com/docs)
+- [signal-cli REST API](https://github.com/AsamK/signal-cli/blob/master/man/signal-cli.1.adoc)
+- [Meta WhatsApp Business API](https://developers.facebook.com/docs/whatsapp)
+- [Google Chat API](https://developers.google.com/chat)
+- [Matrix Client-Server API](https://spec.matrix.org/latest/client-server-api/)
+- [Signal-iOS](https://github.com/signalapp/Signal-iOS)
+- [Signal-Android](https://github.com/signalapp/Signal-Android)
+- [Signal-Desktop](https://github.com/signalapp/Signal-Desktop)
+- [X API v2](https://developer.twitter.com/en/docs/twitter-api)
+- [Instagram Graph API](https://developers.facebook.com/docs/instagram-api)
+- [YouTube Data API](https://developers.google.com/youtube/v3)
+- [Reddit API](https://www.reddit.com/dev/api)
+- [TikTok Marketing API](https://business-api.tiktok.com/)
+
+---
+
+*Plan created: 2026-07-12*  
+*Supersedes: v1 (ae9945ca), v2 (f1bd6c42)*  
+*Next review: After Phase 0 completion*