# Crkl Cursor Agent Rules

## Context Initialization
- **ALWAYS** start each session by reading `.notes/project_overview.md` for project context
- Reference `.notes/directory_structure.md` for file locations and module relationships
- Check `.notes/meeting_notes.md` for recent decisions and current status
- Review `PROJECT_STATUS.md` for current phase and capabilities

## Code Standards - Kotlin & Android
- **Language:** Always use Kotlin for Android source code (version 1.9.20+)
- **UI Framework:** Use Jetpack Compose for all overlay/UI components (Material3)
- **Async:** Use Kotlin Coroutines for all async operations (no callbacks)
- **Null Safety:** Leverage Kotlin's null safety, avoid !! operator
- **Code Style:** Follow official Kotlin coding conventions
- **Imports:** Remove unused imports, organize alphabetically

## Architecture & Design Patterns
- **Module Structure:** Follow the established package structure in `app/src/main/kotlin/com/example/crkl/`
  - `accessibility/` - Overlay services
  - `gesture/` - Touch and gesture processing
  - `model/` - ML inference wrappers
  - `vision/` - Content detection
  - `agent/` - Dialogue state management
  - `ui/` - Compose components
  - `privacy/` - Data controls
- **Dependency Injection:** Use constructor injection, avoid static dependencies
- **Composition over Inheritance:** Prefer interfaces and composition
- **Single Responsibility:** Each class should have one clear purpose

## Privacy & Security Rules (CRITICAL)
- **NEVER** introduce network or cloud service calls for AI features
- **NEVER** add internet permissions to AndroidManifest.xml
- **NEVER** include analytics, tracking, or telemetry libraries
- **ALWAYS** keep all ML inference local and on-device
- **ALWAYS** ensure user data stays on device
- Verify no data leaves the device before suggesting any new dependency

## Accessibility Service Rules
- **ALWAYS** respect and preserve existing accessibility overlay logic
- **NEVER** block or interfere with underlying app functionality
- Pass through touch events when not actively capturing gestures
- Test overlay behavior doesn't break other apps
- Handle permission denied gracefully

## ML & AI Integration
- Prioritize asynchronous, local-only inference for all ML modules
- Use GGUF, TFLite, or ONNX formats for models
- Load models lazily to reduce memory footprint
- Handle model loading failures gracefully
- Log model performance metrics for optimization

## Documentation Requirements
- Document any architectural changes in `ARCHITECTURE.md`
- Update `.notes/directory_structure.md` when adding new modules
- Add KDoc comments for all public APIs
- Include usage examples in doc comments for complex functions
- Update `PROJECT_STATUS.md` after completing major features

## Testing Standards
- Add unit tests for business logic in `app/src/test/`
- Add integration tests for module interactions
- Test on multiple Android versions (min API 27, target API 34)
- Log errors and edge cases for debugging
- Use descriptive test names: `test_shouldDoSomething_whenCondition()`

## Error Handling
- Use `Result<T>` or sealed classes for operation results
- Log errors with appropriate severity (Log.e, Log.w, Log.d)
- Provide user-friendly error messages
- Never crash silently - always log exceptions
- Handle all accessibility service lifecycle events

## File Editing Conventions
- Preserve existing code structure and formatting
- Don't rewrite working code unless explicitly asked
- Add TODO comments with context for future work
- Reference GitHub issue/ticket numbers in TODOs
- Keep changes focused and minimal

## Build & Deployment
- Ensure code compiles before committing
- Run linter and fix issues: `./gradlew lint`
- Keep APK size reasonable (< 50MB for POC)
- Use ProGuard rules to protect privacy-sensitive code
- Test on physical devices when possible

## Session Workflow
1. Read `.notes/project_overview.md` for context
2. Check `.notes/meeting_notes.md` for latest status
3. Review relevant module code
4. Make focused, incremental changes
5. Test and verify functionality
6. Update documentation if needed
7. Log session progress in `.notes/meeting_notes.md`

## AI-Specific Guidelines
- When implementing ML features, always verify model is local-only
- Check model license compatibility (prefer Apache 2.0, MIT)
- Document model size, performance, and device requirements
- Provide fallback behavior if model fails to load
- Test inference latency on lower-end devices

## Prohibited Actions
- ❌ Adding network calls for core AI features
- ❌ Introducing cloud service dependencies
- ❌ Modifying core privacy guarantees
- ❌ Breaking existing accessibility overlay functionality
- ❌ Adding heavy dependencies without justification
- ❌ Hardcoding API keys or secrets
- ❌ Using deprecated Android APIs without migration plan