# AGENTS.md: Ionic + Capacitor

## Commands
- Web dev: `ionic serve` (or `npm run dev`) · Build: `npm run build` · Native sync: `npx cap sync` · Open: `npx cap open ios|android`
- Live reload on device: `ionic cap run android -l --external` (ask before running on a device).
- Check `package.json` for Ionic and Capacitor majors; plugins must match the Capacitor major.

## Rules
- UI with Ionic components (`ion-page`, `ion-header`, `ion-content`, `ion-list`, `ion-item`) so platform styling, safe areas, and gestures work. Don't hand-roll headers or scroll containers.
- Navigation with the framework's Ionic router integration (`IonRouterOutlet`, `ion-tabs`); keep page lifecycle hooks (`ionViewWillEnter`) for refreshes that must run on back navigation.
- Native features through official `@capacitor/*` plugins (Camera, Filesystem, Preferences, Haptics, Push Notifications). Check `Capacitor.isNativePlatform()` and provide web fallbacks.
- Request permissions just in time (`Camera.requestPermissions()`), and add the usage descriptions to `Info.plist` / `AndroidManifest.xml`.
- Secrets/tokens in secure storage (a Keychain/Keystore plugin), not `Preferences` or `localStorage`.
- Run `npx cap sync` after adding plugins or changing web build output; commit native project changes deliberately.
- Performance: virtual scrolling for long lists, lazy-loaded routes, compressed images.
- Handle the hardware back button and keyboard (`@capacitor/keyboard`) on Android.

## Don't
Don't edit generated native files under `ios/App/App/public` or `android/app/src/main/assets/public`.

## Done
Web build, unit tests, and lint pass; `npx cap sync` runs cleanly.