Update project configuration files and enhance documentation

- Updated `.gitignore` and `.cursorignore` to exclude additional build artifacts and temporary files. - Enhanced `.cursorrules` with comprehensive AI guidelines and best practices. - Improved `.notes/directory_structure.md` to reflect the current project structure and module organization. - Updated `ARCHITECTURE.md` to include new insights on the system's modular design and privacy-first approach. - Refined `README.md` for clarity on project setup and usage instructions. - Added new entries in `.notes/meeting_notes.md` to document recent progress and decisions. - Ensured all changes align with the project's privacy and security standards.
2025-10-18 14:32:33 -04:00
commit c351858749
48 changed files with 2305 additions and 0 deletions
@@ -0,0 +1,143 @@
+# Physical Phone Setup Guide
+
+## Prerequisites
+
+1. **Android phone** (Android 8.1 or higher)
+2. **USB cable**
+3. **Android SDK installed** on your Linux machine
+
+---
+
+## Step 1: Enable Developer Options on Phone
+
+1. Open **Settings** on your phone
+2. Go to **About Phone**
+3. Tap **Build Number** 7 times
+4. You'll see "You are now a developer!"
+
+---
+
+## Step 2: Enable USB Debugging
+
+1. Go back to **Settings**
+2. Open **Developer Options** (or **System → Developer Options**)
+3. Enable **USB Debugging**
+4. (Optional) Enable **Stay Awake** - keeps screen on while charging
+
+---
+
+## Step 3: Connect Phone to Computer
+
+1. Plug phone into computer via USB
+2. On your phone, a popup will appear: **"Allow USB debugging?"**
+3. Tap **Allow** (check "Always allow from this computer")
+
+---
+
+## Step 4: Verify Connection
+
+```bash
+cd /home/user/Documents/code/crkl
+export ANDROID_HOME=~/android-sdk
+export PATH=$ANDROID_HOME/platform-tools:$PATH
+
+# Check if phone is detected
+adb devices
+```
+
+You should see:
+```
+List of devices attached
+ABC123XYZ    device
+```
+
+---
+
+## Step 5: Build and Install Crkl
+
+```bash
+# Build the app
+make build
+
+# Install to your phone
+make install
+```
+
+---
+
+## Step 6: Enable Accessibility Service
+
+### On Your Phone:
+
+1. **Open the Crkl app** (will show welcome screen)
+2. **Tap "Open Accessibility Settings"** button
+3. In Settings, find **"Crkl Overlay Service"**
+4. **Toggle it ON**
+5. Accept the permission dialog
+6. **Press back button** to return to home screen
+
+---
+
+## Step 7: Test It
+
+The overlay is now active system-wide!
+
+**Watch logs:**
+```bash
+make logs
+```
+
+**Touch your phone screen** anywhere - you should see:
+```
+OverlayView: Touch down at (X, Y)
+OverlayView: Touch up at (X, Y)
+```
+
+**Visual feedback:**
+- Cyan circles appear where you touch
+- Crosshair shows exact touch point
+
+---
+
+## Quick Commands
+
+```bash
+make build      # Build APK
+make install    # Install to phone
+make run        # Launch app
+make logs       # Watch logs
+make stop       # Stop app
+make clean      # Clean build
+make uninstall  # Remove app
+```
+
+---
+
+## Troubleshooting
+
+### "adb: command not found"
+```bash
+export ANDROID_HOME=~/android-sdk
+export PATH=$ANDROID_HOME/platform-tools:$PATH
+```
+
+### "no devices/emulators found"
+- Check USB cable is connected
+- Check "USB Debugging" is enabled
+- Run `adb devices` and accept prompt on phone
+
+### "unauthorized"
+- Revoke USB debugging authorizations in Developer Options
+- Disconnect and reconnect USB
+- Accept the new prompt
+
+### Can't see overlay
+- Make sure you enabled "Crkl Overlay Service" in Accessibility Settings
+- Restart the app: `make stop && make run`
+
+---
+
+## Done!
+
+You're ready to develop. The app will now detect touches system-wide on your phone.
+