# Kordant App Actions — Google Assistant Integration

## Overview

Kordant integrates with Google Assistant via **App Actions** (Built-in Intents),
allowing users to interact with the app using voice commands on Android devices
that have Google Play Services installed.

## Architecture

```
User says "Hey Google, check my threat score on Kordant"
                       │
                       ▼
            Google Assistant
          (Natural Language → BII match)
                       │
                       ▼
        actions.xml (actions.intent.OPEN_APP_FEATURE)
                       │
                       ▼
        Deep-link URI: kordant://dashboard?feature=THREAT_SCORE
                       │
                       ▼
        MainActivity.handleIntent() → parseDeepLink()
                       │
                       ▼
        DeepLink.Dashboard → ViewModel / NavGraph
                       │
                       ▼
        DashboardScreen (threat score displayed)
```

Fulfillment is entirely deep-link based — no custom broadcast receivers or
services are needed for App Actions. All BIIs map to `kordant://` URIs, which
are handled by `MainActivity.parseDeepLink()` and dispatched via the Jetpack
Navigation graph.

## Supported Voice Commands

| Voice Command | Action | Deep Link | Screen |
|---|---|---|---|
| "Hey Google, check my threat score on Kordant" | `OPEN_APP_FEATURE` | `kordant://dashboard` | Dashboard |
| "Hey Google, open Kordant" | `OPEN_APP_FEATURE` | `kordant://dashboard` | Dashboard |
| "Hey Google, show my dashboard on Kordant" | `OPEN_APP_FEATURE` | `kordant://dashboard` | Dashboard |
| "Hey Google, run a security scan on Kordant" | `OPEN_APP_FEATURE` | `kordant://scan` | New Scan |
| "Hey Google, start a scan on Kordant" | `OPEN_APP_FEATURE` | `kordant://scan` | New Scan |
| "Hey Google, scan my accounts on Kordant" | `OPEN_APP_FEATURE` | `kordant://scan` | New Scan |
| "Hey Google, do I have security alerts on Kordant" | `OPEN_APP_FEATURE` | `kordant://alerts` | Alerts |
| "Hey Google, check my alerts on Kordant" | `OPEN_APP_FEATURE` | `kordant://alerts` | Alerts |
| "Hey Google, show my notifications on Kordant" | `OPEN_APP_FEATURE` | `kordant://alerts` | Alerts |
| "Hey Google, open Kordant settings" | `OPEN_APP_FEATURE` | `kordant://settings` | Settings |
| "Hey Google, show my preferences on Kordant" | `OPEN_APP_FEATURE` | `kordant://settings` | Settings |

## Entity Vocabulary

The `actions.xml` defines entity sets that Google Assistant uses to match
natural-language phrases to deep-link targets:

| Entity Set | Entities | Target |
|---|---|---|
| `dashboardEntities` | `dashboard`, `threat score`, `home` | Dashboard |
| `scanEntities` | `scan`, `security scan`, `run scan`, `start scan` | New Scan |
| `alertEntities` | `alerts`, `notifications`, `security alerts`, `threats` | Alerts |
| `settingsEntities` | `settings`, `preferences`, `account` | Settings |

## Files

| File | Purpose |
|---|---|
| `res/xml/actions.xml` | App Actions BII definitions, fulfillment templates, entity sets |
| `AndroidManifest.xml` | `<meta-data>` reference to `actions.xml` + deep-link intent-filters |
| `MainActivity.kt` | `handleIntent()` / `parseDeepLink()` — deep-link dispatch |
| `AppNavigation.kt` | `DeepLink.Settings` navigation handling |
| `docs/app-actions.md` | This documentation |

## Testing

### Prerequisites
- Physical device with Google Play Services and Google Assistant
- Kordant installed on the device
- Same Google account on device and Play Console

### Using App Actions Test Tool
1. Open the **Google Assistant App Actions Test Tool** on the device
2. Select Kordant from the app list
3. Test each BII by entering a sample query or using voice
4. Verify the app opens to the correct screen

### Manual Testing (Physical Device)
1. Ensure Assistant is set up: long-press Home or say "Hey Google"
2. Say the voice command (e.g., "check my threat score on Kordant")
3. Verify Kordant opens to the expected screen
4. Verify the Assistant surfaces Kordant in suggestions

### Deep Link Testing (adb)
```bash
# Open Dashboard
adb shell am start -d "kordant://dashboard" -a android.intent.action.VIEW

# Check Alerts
adb shell am start -d "kordant://alerts" -a android.intent.action.VIEW

# Run Scan
adb shell am start -d "kordant://scan" -a android.intent.action.VIEW

# Open Settings
adb shell am start -d "kordant://settings" -a android.intent.action.VIEW

# Open Services
adb shell am start -d "kordant://services" -a android.intent.action.VIEW

# Alert Detail with ID
adb shell am start -d "kordant://alert?id=123" -a android.intent.action.VIEW

# Service Detail with ID
adb shell am start -d "kordant://service?id=456" -a android.intent.action.VIEW
```

## Notes

- **App Actions require Google Play Services** — they will not work on
  devices without Google Play (e.g., some Android emulators, Amazon Fire OS).
- **Built-in Intents (BIIs) only** — custom intents are not supported for
  third-party apps. Only `actions.intent.OPEN_APP_FEATURE` and other
  Google-defined BIIs are available.
- **Slices are optional and being deprecated** — we chose not to implement
  Slices because Google is deprecating them in favor of App Widgets, which
  Kordant already supports (Threat Score Widget).
- **No crash from malformed intents** — all `parseDeepLink()` paths return
  `null` for unrecognized URIs, and the navigation graph safely ignores null
  deep links.
- **Token refresh / auth state** — if the user is not authenticated when a
  deep link arrives, the deep link is held until the auth flow completes
  (handled by `AppNavigation` composable).