# Circle

Android assist app: circle on-screen text, then Translate, Copy, Explain, Share,
or Vikunja. On-device processing.

Repo / Gradle module: **crkl** · Application id: `com.example.crkl` · Display name: **Circle**

## Ship docs

- [docs/DEMO.md](docs/DEMO.md) — 45s recording script  
- [docs/dogfood.md](docs/dogfood.md) — daily checklist  
- [docs/non-goals.md](docs/non-goals.md) — freeze list  
- [docs/marketing.md](docs/marketing.md) — blurb + posts  
- [docs/shortcuts.md](docs/shortcuts.md) — QS tile / a11y button / volume keys  
- [docs/RELEASE.md](docs/RELEASE.md) — install & tag  
- [docs/brand/](docs/brand/) — logo (shipped: **lasso #2**)  
- [CHANGELOG.md](CHANGELOG.md)

## Features

- Circle gesture captures on-screen text (accessibility service + on-device OCR)
- Action chips: Translate, Copy, Explain, Share, Vikunja
- Vikunja HTTPS integration for add-to-todo
- Optional mailto / lab gog bridge (Advanced in Integrations)
- Device calendar read (Advanced)
- Circle style settings (color, neon, stroke)
- First-run onboarding; optional debug metadata in panel
- Shortcuts: Quick Settings Circle tile, Accessibility button, volume-key shortcut
- Local LLM when a `.task` model is present; otherwise stub Explain / summary

## Quick start

```bash
./setup.sh          # one-time SDK (if needed)
make check-device
./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` when Make targets are available.

See [PHONE_SETUP.md](PHONE_SETUP.md) for USB debugging.

### Enable Circle Overlay

1. Open **Circle**
2. Tap **Enable Accessibility** (or Accessibility settings)
3. Turn on **Circle Overlay**
4. Accept the permission dialog  
   Re-enable after every reinstall.

### Try it

Tap the floating **C**, or Quick Settings → **Circle**, then draw a closed loop around text.  
VIP path is on **Test fixtures** (see [docs/DEMO.md](docs/DEMO.md)).

### Shortcuts

[docs/shortcuts.md](docs/shortcuts.md) — QS tile, Accessibility button, hold both volume keys.  
Double-press power is **not** available to third-party apps.

## Emulator note

If the GUI emulator never appears in `adb devices`, use headless (see [docs/RELEASE.md](docs/RELEASE.md)):

```bash
$ANDROID_HOME/emulator/emulator -avd CrklEmulator -no-window \
  -gpu swiftshader_indirect -no-snapshot-load -grpc 8554 &
adb wait-for-device
```

## Project structure

```
crkl/
├── app/src/main/kotlin/com/example/crkl/
│   ├── MainActivity.kt
│   ├── accessibility/          # Overlay, QS tile, bridge
│   ├── agent/                  # VoiceIntent, ActionExecutor, AssistEngine
│   ├── vision/                 # OCR + content capture
│   ├── integrations/           # Vikunja, translate, calendar
│   ├── fixtures/               # Test fixtures + demoScript()
│   └── ui/                     # Result panel, theme, CrklUi tokens
├── docs/                       # Ship + brand docs
└── Makefile
```

## Model (optional)

Inference is MediaPipe on-device (`make push-model`). Without a model, Circle uses a local stub — still no cloud for summaries. OCR is ML Kit on-device.

## License

MIT — see [LICENSE](LICENSE).