diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1f157ff
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,20 @@
+# Vacation (Paradise Planner)
+
+Firebase + Flutter monorepo for an AI vacation-planning lead-capture product (Firebase project `vacation-app-21706`).
+
+- `flutter_app/` — Flutter client. Two entry points: `lib/main_customer.dart` (Paradise Planner customer chat) and `lib/main_admin.dart` (CRM/admin). Talks to live Firebase: anonymous Auth, Gemini via Firebase AI Logic, and Cloud Functions.
+- `functions/` — Cloud Functions (TypeScript, Node 20): `submitLead`, `submitPartialLead`, `sendLeadSms`, `onLeadStatusChange`, `retryLeadSms`.
+- `public/` — prebuilt Flutter web served by Firebase Hosting. `docs/deploy.md` covers deploy.
+
+## Cursor Cloud specific instructions
+
+- Flutter SDK is installed at `/home/ubuntu/flutter` (not in repo). `flutter`/`dart` are on PATH via `~/.bashrc`; if a non-login shell can't find them, use the full path `/home/ubuntu/flutter/bin/flutter` or run `export PATH="$PATH:/home/ubuntu/flutter/bin"`.
+- Dependencies are refreshed automatically by the update script (`npm install --prefix functions` and `flutter pub get -C flutter_app`). No manual install needed at session start.
+- Run the customer app in dev mode from `flutter_app/`:
+  `flutter run -d web-server --web-hostname=0.0.0.0 --web-port=5001 -t lib/main_customer.dart`
+  Then open `http://localhost:5001/`. First load compiles for ~15-20s. Admin app: same command with `-t lib/main_admin.dart`.
+- The customer app uses the committed Firebase config and hits the **live** backend: anonymous Auth, live Gemini (`gemini-2.5-flash-lite`) via Firebase AI Logic, and the **deployed** Cloud Functions URLs hardcoded in `lib/chat/vacation_agent_service.dart` (`https://us-central1-vacation-app-21706.cloudfunctions.net/...`). There is no local Gemini emulator. To exercise functions locally you must either deploy them or repoint those URLs to the Firestore/Functions emulators (`npm run serve` in `functions/`).
+- Lead-capture hello-world: chat trip details (destination, dates, budget, activities) then a valid US phone; a green "You're all set!" banner confirms the lead was submitted to `submitLead`.
+- Lint: `flutter analyze` (in `flutter_app/`) reports a few pre-existing info/warning issues and exits non-zero — that is expected, not a setup failure. Functions "lint"/typecheck is `npm run build` (tsc) in `functions/`.
+- Tests: `flutter test` in `flutter_app/` (12 unit tests). `functions/` has no test suite (build-only).
+- Twilio SMS is optional; `sendLeadSms` degrades gracefully (`smsStatus: failed`) when `TWILIO_*` secrets are unset, so the lead flow still completes. Deploys need `FIREBASE_TOKEN` (already provided as a secret).