feat: initial project scaffold

- Android Auto CarAppService, Session, Screen - Voice pipeline: STT (SpeechManager), TTS (TTSManager), VoiceStateMachine - Matrix REST client (login, send, sync) - no E2EE, raw API - FCM push receiver with response dedup - Network monitor + offline message queue - Phone setup activity stub - Full architecture spec in docs/ARCHITECTURE.md
2026-03-05 22:07:30 +00:00
parent 6c76d18f58
commit 318867b133
23 changed files with 1371 additions and 2 deletions
@@ -1,3 +1,104 @@
-# clippy-auto
+# ClippyAuto 📎🚗

-Voice-first Android Auto app for Clippy via Matrix
+Voice-first Android Auto app for talking to Clippy via Matrix.
+
+## Overview
+
+ClippyAuto gives Jeremy a hands-free voice conversation with Clippy (AI Chief of Staff) during his commute. No typing, no "Hey Google," no Element — just tap and talk.
+
+**How it works:** You talk → on-device STT → Matrix message to Clippy → Claude responds → FCM push → car speakers read it back. Target: under 5 seconds to first audio.
+
+## Prerequisites
+
+- Android Studio Ladybug (2024.2+)
+- JDK 17
+- Android device with Android Auto support (or Desktop Head Unit for testing)
+- Firebase project with FCM enabled
+- Access to `mess.hobbs.farm` Matrix homeserver
+
+## Setup
+
+### 1. Clone & Open
+```bash
+git clone https://git.hobbs.farm/spirit/clippy-auto.git
+cd clippy-auto
+# Open in Android Studio
+```
+
+### 2. Firebase
+1. Create a Firebase project at https://console.firebase.google.com
+2. Add an Android app with package name `farm.hobbs.clippyauto`
+3. Download `google-services.json` → place in `app/`
+4. Enable Cloud Messaging (v1 API)
+
+### 3. Matrix Homeserver
+- `mess.hobbs.farm` must be reachable externally (HTTPS via Traefik) ✅
+- Jeremy's account needs access to `#clippy-voice:hobbs.farm` room
+
+### 4. n8n FCM Bridge
+- Import `n8n/clippy-fcm-bridge.json` workflow into n8n
+- Register Matrix pusher on Jeremy's account pointing to n8n webhook
+- Configure FCM server key in n8n credentials
+
+### 5. Build & Run
+```bash
+./gradlew installDebug
+```
+
+### Testing with Desktop Head Unit (DHU)
+```bash
+$ANDROID_HOME/extras/google/auto/desktop-head-unit
+```
+
+## Project Structure
+
+```
+app/src/main/java/farm/hobbs/clippyauto/
+├── ClippyAutoApp.kt              # Application entry, DI
+├── auto/
+│   ├── ClippyCarAppService.kt    # Android Auto entry point
+│   ├── ClippySession.kt          # Auto session lifecycle
+│   └── ClippyScreen.kt           # Auto UI (talk button + status)
+├── voice/
+│   ├── VoiceState.kt             # State enum
+│   ├── VoiceStateMachine.kt      # State transitions
+│   ├── SpeechManager.kt          # STT (SpeechRecognizer)
+│   └── TTSManager.kt             # TTS with queue + audio focus
+├── matrix/
+│   └── MatrixRestClient.kt       # Lightweight Matrix REST API client
+├── push/
+│   └── ClippyFCMService.kt       # FCM receiver + dedup
+├── connectivity/
+│   ├── NetworkMonitor.kt         # Online/Weak/Offline detection
+│   └── MessageQueue.kt           # Offline message queuing
+└── ui/
+    └── SetupActivity.kt          # Phone setup + session indicator
+```
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full spec.
+
+## Status
+
+🚧 **v1 MVP in progress**
+
+- [x] Project scaffold
+- [x] Android Auto CarAppService + Screen
+- [x] Voice state machine
+- [x] STT manager (SpeechRecognizer)
+- [x] TTS manager (queue + audio focus + interruption)
+- [x] Matrix REST client (login, send, sync)
+- [x] FCM push receiver + dedup
+- [x] Network monitor + message queue
+- [ ] Wire voice pipeline end-to-end
+- [ ] Phone setup UI (login flow)
+- [ ] n8n FCM bridge workflow
+- [ ] Confirmation chime + thinking tone audio assets
+- [ ] Session lifecycle signals
+- [ ] Voice command recognition (go quiet, wrap up, etc.)
+- [ ] Real-car testing
+
+## License
+
+Private — hobbs.farm internal use.