docs: Add DEBUG_FEATURES.md documenting debug shortcuts

Author: FiftyEightSoftware

DEBUG_FEATURES.md

@@ -0,0 +1,103 @@
+# Debug Features - AI Mate
+
+Features that are **only available in DEBUG builds** for testing and development.
+
+---
+
+## 🔧 Data Seeding Shortcut
+
+### Magic VAT Number: `12345`
+
+During onboarding in the mobile app (or web app running in DEBUG mode), entering `12345` as the VAT Registration Number will automatically trigger data seeding.
+
+**How it works:**
+1. User enters `12345` in the VAT Registration Number field
+2. User clicks "Save & Continue"
+3. App calls `/api/dev/reseed` endpoint on the backend
+4. Test data is seeded (sample invoices, jobs, etc.)
+5. User sees feedback: "🔧 Debug mode: Triggering data seeding..."
+6. After seeding, shows: "✅ Debug data seeded successfully! Redirecting..."
+
+**Use Case:**
+- Testing the mobile app with realistic data
+- Demonstrating features without manual data entry
+- E2E testing on devices where backend access is limited
+
+**Security:**
+- ✅ Only works in DEBUG builds (`#if DEBUG`)
+- ✅ Automatically excluded from release/production builds
+- ✅ Backend endpoint only available in Development environment
+- ✅ No security risk in production
+
+---
+
+## 📱 Mobile App Debug Builds
+
+### Building Debug APK with Data Seeding:
+
+```bash
+# Build debug Android APK
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+BUILD_TYPE=debug BUILD_FORMAT=apk ./scripts/build_mobile_android.sh
+
+# Output: build/android/ai-mate-debug.apk
+```
+
+### Testing on Device:
+
+1. Install debug APK:
+   ```bash
+   adb install build/android/ai-mate-debug.apk
+   ```
+
+2. Launch app and complete onboarding
+
+3. Enter `12345` as VAT number
+
+4. Click "Save & Continue"
+
+5. Watch for debug message confirming data seeding
+
+---
+
+## 🚀 Production Builds
+
+Release builds automatically exclude all debug features:
+
+```bash
+# Release builds have NO debug features
+BUILD_TYPE=release BUILD_FORMAT=aab ./scripts/build_mobile_android.sh
+```
+
+**What's removed in release:**
+- ❌ Magic VAT number detection
+- ❌ Data seeding shortcuts
+- ❌ Debug messages
+- ❌ `/api/dev/*` endpoints disabled
+
+---
+
+## 🎯 Backend Debug Endpoints
+
+Available only in Development environment:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/dev/reseed` | POST | Seed test data (invoices, jobs) |
+| `/api/dev/default-company` | GET | Get default company ID |
+| `/api/dev/backfill-company` | POST | Backfill company IDs (requires ENABLE_DEV_RESEED=true) |
+| `/api/dev/migrate-per-company` | POST | Migrate to per-company DBs (requires ENABLE_DEV_RESEED=true) |
+
+---
+
+## 📝 Notes
+
+- Debug features use `#if DEBUG` preprocessor directives
+- Release builds compile with optimizations and exclude debug code
+- Backend must be running in Development mode for endpoints to work
+- No performance impact in production builds
+- Safe for App Store / Play Store submission
+
+---
+
+**Last Updated:** October 26, 2025