From bb2775769c2dbc1ec28be0a4158af95edade6aba Mon Sep 17 00:00:00 2001 From: fabiorafaelcoutada Date: Sun, 12 Jul 2026 15:05:39 +0100 Subject: [PATCH] plan: omnichannel messaging + social media parity (v3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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-hermes-multiplatform-parity.md | 527 ++++++++++++++++++ 1 file changed, 527 insertions(+) create mode 100644 .aurelio/projects/aurelio/plans/2026-07-12-hermes-multiplatform-parity.md diff --git a/.aurelio/projects/aurelio/plans/2026-07-12-hermes-multiplatform-parity.md b/.aurelio/projects/aurelio/plans/2026-07-12-hermes-multiplatform-parity.md new file mode 100644 index 00000000..f6e5f9bc --- /dev/null +++ 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 ` — 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*