# Physical Phone Setup Guide — Circle

## Prerequisites

1. **Android phone** (API 27+ / Android 8.1+)
2. **USB cable**
3. **Android SDK** on your Mac/Linux machine

---

## Step 1: Enable Developer Options

1. Settings → **About Phone**
2. Tap **Build Number** 7 times

---

## Step 2: Enable USB Debugging

1. Settings → **Developer Options**
2. Enable **USB Debugging**
3. (Optional) **Stay Awake** while charging

---

## Step 3: Connect Phone

1. Plug in USB
2. Allow USB debugging on the phone

---

## Step 4: Verify Connection

```bash
adb devices
```

You should see `device` (not `unauthorized`).

---

## Step 5: Build and Install Circle

```bash
cd ~/Documents/code/crkl
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.crkl/.MainActivity
# or: make build && make install && make run
```

---

## Step 6: Enable Circle Overlay

1. Open the **Circle** app
2. Tap **Enable Accessibility**
3. Turn on **Circle Overlay**
4. Accept the permission dialog

Re-enable after every reinstall.

---

## Step 7: Test It

Tap the floating **C** (or QS **Circle**), draw a closed loop around text, use the chips.

```bash
make logs
# or: adb logcat -s CrklAccessibilityService:D OverlayView:D AssistEngine:D
```

VIP path: **Test fixtures** → [docs/DEMO.md](docs/DEMO.md).

---

## Quick Commands

```bash
make build / install / run / logs / stop / clean / uninstall
```

---

## Troubleshooting

### adb not found
```bash
export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools   # example
export PATH=$ANDROID_HOME/platform-tools:$PATH
```

### no devices
- USB debugging on; accept the prompt
- Emulator flaky? Headless tips in [docs/RELEASE.md](docs/RELEASE.md)

### unauthorized
- Revoke USB debugging authorizations; reconnect

### Can't see overlay
- Enable **Circle Overlay** in Accessibility
- `make stop && make run`

---

## Shortcuts

See [docs/shortcuts.md](docs/shortcuts.md).

1. Enable **Circle Overlay**
2. Circle app → **Add Quick Settings tile**
3. Swipe down → **Circle** → closed loop

Optional: Accessibility shortcut → **Circle Overlay** (hold both volume keys).

---

## Done

Enable Accessibility, then use the floating C or the Circle QS tile.