JolandaVerhoef · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026
@@ -0,0 +1,83 @@
+# Agent & Developer Guidelines: JetPacker
+
+This document outlines key technical constraints, coding standards, and testing procedures for AI agents and human developers working in the JetPacker repository.
+
+---
+
+## 1. Code Style & Syntax Invariants
+
+### 1.1 Avoid Fully Qualified Class Names (FQCN)
+When writing or modifying Kotlin, Java, or Compose files:
+- **Always Use Top-Level Imports**: Never write inline Fully Qualified Class Names (e.g., `com.example.jetpacker.core.flags.FeatureFlags`, `java.time.Instant`, `androidx.compose.ui.Modifier`) in function bodies, parameter lists, or property definitions.
+- **Explicit File-Level Imports**: Add explicit `import` statements at the top of the file for all referenced types, classes, and utilities.
+
+### 1.2 Jetpack Compose Conventions
+- **Modifier Placement**: Every composable function (except top-level screen containers) must accept `modifier: Modifier = Modifier` as the first optional parameter.
+- **Unidirectional Data Flow (UDF)**: ViewModels expose a single immutable `uiState: StateFlow<ScreenState>`. Composables accept states and emit lambda event callbacks (e.g., `onTripSelected: (String) -> Unit`).
+- **No Direct Context References in ViewModels**: ViewModels should remain agnostic of Android UI lifecycles. Never pass `Activity` or `Context` into ViewModel methods. If `Application` is required, inject `Application` directly via constructor.
+
+### 1.3 Hilt Dependency Injection Rules
+- **No `@ApplicationContext` on `Application`**: In Hilt, `Application` is provided directly by default. Annotating constructor parameter `application: Application` with `@ApplicationContext` will cause a Dagger compiler failure (`[Dagger/MissingBinding]`). Only use `@ApplicationContext` when the parameter type is `Context`.
+
+---
+
+## 2. Room Database & Persistence Rules
+
+- **Database Class**: `JetPackerDatabase` in `:data:db` (current version: 4).
+- **Entities & DAOs**:
+  - `Trip` & `TripDao` in `:data:trips`.
+  - `TimelineEvent`, `Expense`, `TravelDocument`, `DayTheme`, `VoiceNoteEntity`, `AssistantConversation` in `:data:itinerary`.
+- **Interface Parity**: When updating a DAO interface, immediately update corresponding test fakes (`FakeTripDao`, `TestTripDao`, `FakeEventDao`). Never add methods to test fakes that do not exist on the real DAO interface.
+- **Schema Updates**: Any entity modification requires bumping the `version` number in `JetPackerDatabase.kt` and providing an appropriate `Migration` or fallback policy.
+
+---
+
+## 3. AI & On-Device Agent Constraints
+
+### 3.1 ML Kit GenAI Agent Integration
+- JetPacker uses the public Android ML Kit GenAI Agent library (`com.google.mlkit:genai-agent:1.0.0-alpha1`).
+- Always use standard public Android AI dependencies.
+- Use `AgentRunner(context, agent, generativeModel = previewGenerativeModel)` with `agentBuilder.enableAppFunctions(true)`.
+
+### 3.2 Gemini Nano v4 Preview
+- Configured using `ModelReleaseStage.PREVIEW` and `ModelPreference.FAST`.
+- Always check on-device availability via `previewGenerativeModel.checkStatus()` and handle download / unsupported states before invoking inference.
+
+### 3.3 Token Pruning for On-Device Tools
+- On-device models have strict context window budgets. When defining tool descriptions or schemas in `TravelDaoTools.kt`, keep descriptions compact and concise to prevent exhausting token limits.
+
+---
+
+## 4. Build & Test Recipes
+
+### 4.1 Running Tests
+```bash
+# Run all unit tests across all modules
+cd jetpacker/android && ./gradlew testDebugUnitTest
+
+# Run tests for a specific module
+./gradlew :feature:assistant:testDebugUnitTest
+./gradlew :data:trips:testDebugUnitTest
+./gradlew :feature:trip:booking_assistant:testDebugUnitTest
+
+# Assemble Debug APK
+./gradlew :app:assembleDebug
+```
+
+### 4.2 Handling Incremental Build Quirks
+If KSP or Kotlin compiler fails with unexpected unresolved symbols after switching branches or modifying interfaces:
+```bash
+./gradlew clean <affected_module>:compileDebugKotlin
+```
+
+---
+
+## 5. Python Booking Assistant Server (`jetpacker/server`)
+
+The booking assistant backend coordinates agents for flights, hotels, and activities:
+```bash
+cd jetpacker/server
+pip install -r requirements.txt
+uvicorn main:app --host 0.0.0.0 --port 8000
+```
+- **Staging vs Production**: Configurable in `BookingAssistantViewModel.kt` (`PARALLEL_STAGING` connects to Cloud Run `/v2`, `LOCAL` connects to `localhost:8000`).
@@ -0,0 +1,126 @@
+---
+name: jetpacker
+description: >-
+  Comprehensive guide for developing, building, testing, architecting, and debugging
+  the JetPacker Android travel companion application and its Python booking backend.
+  Use when compiling or running unit tests with Gradle, inspecting or updating Room database
+  schemas, editing ViewModels and Compose screens, configuring on-device ML Kit / Gemini Nano,
+  working with Jetpack A2UI booking flows, or adding AppFunctions.
+---
+
+# JetPacker Development & Architecture Skill
+
+This skill provides step-by-step procedures, architectural overviews, and build/test recipes for working with JetPacker.
+
+---
+
+## 1. Quick Navigation & Module Layout
+
+JetPacker is organized into an Android multi-module project under `jetpacker/android/` and a Python backend under `jetpacker/server/`.
+
+- **Application Shell**:
+  - `jetpacker/android/app` (`:app`): Top-level navigation host, Hilt graph, theme.
+- **Feature Modules**:
+  - `jetpacker/android/feature/home` (`:feature:home`): Upcoming trips list, quick actions.
+  - `jetpacker/android/feature/create_trip` (`:feature:create_trip`): Create/edit trip destination and date picker.
+  - `jetpacker/android/feature/trip` (`:feature:trip`): Trip dashboard and bottom bar container.
+  - `jetpacker/android/feature/trip/itinerary` (`:feature:trip:itinerary`): Daily timeline events & summaries.
+  - `jetpacker/android/feature/trip/expenses` (`:feature:trip:expenses`): Budgeting, expense logging, receipt OCR.
+  - `jetpacker/android/feature/trip/voice_notes` (`:feature:trip:voice_notes`): On-device speech recognition audio recorder.
+  - `jetpacker/android/feature/trip/booking_assistant` (`:feature:trip:booking_assistant`): Jetpack A2UI dynamic card streaming UI.
+  - `jetpacker/android/feature/assistant` (`:feature:assistant`): On-device Gemini Nano v4 Travel Assistant, Document Vault, and Chat History.
+  - `jetpacker/android/feature/detail` (`:feature:detail`): Detail screens (Museum Assistant, AI Reviews, Hotel Support Chat).
+  - `jetpacker/android/feature/appfunctions` (`:feature:appfunctions`): Android system AppFunctions service.
+- **Data & Core Modules**:
+  - `jetpacker/android/data/db` (`:data:db`): Room database v4 (`JetPackerDatabase`), DAOs, Hilt module.
+  - `jetpacker/android/data/trips` (`:data:trips`): Trip repository, entities, and Flow streams.
+  - `jetpacker/android/data/itinerary` (`:data:itinerary`): Itinerary events, expenses, documents, and DAOs.
+  - `jetpacker/android/core/ui` (`:core:ui`): Design system, toolbar, FAB, tokens.
+  - `jetpacker/android/core/flags` (`:core:flags`): Feature toggles (`FeatureFlags`).
+
+---
+
+## 2. Build & Test Recipes
+
+Execute Gradle commands from the `jetpacker/android` directory:
+
+### Run All Unit Tests
+```bash
+cd jetpacker/android
+./gradlew testDebugUnitTest
+```
+
+### Run Targeted Module Tests
+```bash
+# Travel Assistant & Document Vault
+./gradlew :feature:assistant:testDebugUnitTest
+
+# Trips Repository & DAOs
+./gradlew :data:trips:testDebugUnitTest
+
+# Booking Assistant & A2UI
+./gradlew :feature:trip:booking_assistant:testDebugUnitTest
+
+# AppFunctions
+./gradlew :feature:appfunctions:testDebugUnitTest
+```
+
+### Build APK
+```bash
+./gradlew :app:assembleDebug
+```
+
+### Fix Stale Compiler / KSP Caches
+If encountering unresolved references after switching branches or updating interfaces:
+```bash
+./gradlew clean :feature:assistant:compileDebugKotlin
+```
+
+---
+
+## 3. Database Updates & Room Guidelines
+
+- **Database Class**: `JetPackerDatabase.kt` (`jetpacker/android/data/db/src/main/kotlin/com/example/jetpacker/data/db/JetPackerDatabase.kt`).
+- When modifying an entity:
+  1. Increment `version = N + 1` in `@Database(...)`.
+  2. If adding fields, provide appropriate default values or migration steps.
+  3. Ensure test fake DAOs (`FakeTripDao`, `TestTripDao`, `FakeEventDao`) match the interface in `data/trips` and `data/itinerary` exactly.
+
+---
+
+## 4. On-Device AI: Gemini Nano & Travel Assistant
+
+The on-device assistant lives in `TravelAssistantViewModel.kt` (`jetpacker/android/feature/assistant/src/main/kotlin/com/example/jetpacker/feature/assistant/TravelAssistantViewModel.kt`).
+
+- **Model Setup**:
+  Uses `previewGenerativeModel` configured with `ModelReleaseStage.PREVIEW` and `ModelPreference.FAST`.
+- **Dynamic Tool Registration**:
+  Tools in `TravelDaoTools.kt` (`jetpacker/android/feature/assistant/src/main/kotlin/com/example/jetpacker/feature/assistant/tools/TravelDaoTools.kt`) query the local Room database (`TripDao`).
+- **Token Pruning Invariant**: Keep tool descriptions and schema payloads concise to stay well within on-device context windows (~1,200 tokens saved per turn).
+- **Public API Rule**: Always use the public Android ML Kit GenAI Agent library (`com.google.mlkit:genai-agent:1.0.0-alpha1`).
+
+---
+
+## 5. Booking Assistant & Jetpack A2UI
+
+- **UI Renderer**: Uses `androidx.a2ui` Compose renderer to dynamically render flight, hotel, and activity cards streamed from the backend.
+- **Backend Service**:
+  ```bash
+  cd jetpacker/server
+  pip install -r requirements.txt
+  uvicorn main:app --host 0.0.0.0 --port 8000
+  ```
+- **Reverse Port for Local Emulation**:
+  ```bash
+  adb reverse tcp:8000 tcp:8000
+  ```
+- Switch between `BackendEndpoint.LOCAL`, `PARALLEL_STAGING`, and `PRODUCTION` in `BookingAssistantViewModel.kt` (`jetpacker/android/feature/trip/booking_assistant/src/main/kotlin/com/example/jetpacker/feature/booking_assistant/BookingAssistantViewModel.kt`).
+
+---
+
+## 6. AppFunctions Integration (`:feature:appfunctions`)
+
+Exposes travel data and actions to Android system intelligence:
+- Entry point: `JetPackerAppFunctionService.kt` (`jetpacker/android/feature/appfunctions/src/main/java/com/example/jetpacker/feature/appfunctions/JetPackerAppFunctionService.kt`).
+- Annotated with `@AppFunctionService`.
+- Functions must use `@AppFunctionSerializable` inputs/outputs.