kotlin_phone_app_admin/AGENTS.md

# Kotlin Phone App + Admin

> Build spec for Paperclip. Follow the phases in section 11 in order. Do not skip a
> phase's Definition of Done. When something is unclear, ask Sam — do not guess.

---

## 1. Purpose and outcome

Sam's Android app. It is the **Hub's way in from the phone**, and the **trusted
admin surface** for approvals and parental controls.

**Outcome (the single success statement):**
> Sam talks to the Hub from his phone, hears the answer, and can approve or change
> anything from the same app.

## 2. Scope

**In scope**
- Capture voice and send it to the Hub.
- Show the Hub's reply: text, spoken audio, and notifications.
- Show approval prompts ("Did you ask for this?") and answer them.
- Admin controls: parental controls, by calling the internet control service.
- Native phone actions the Hub requests (call, open a link, open an app by deep link).

**Out of scope**
- The **kids' phone client.** That stays under `internet_use_control`.
- **Artemis** (screen control). Separate project.
- The **Hub** service itself.
- Understanding speech. The Hub does that.

**Decision to confirm:** this is **one app with two areas** — Hub (voice) and Admin.
Not two apps.

## 3. Users and roles

- **Sam only.** This app is not for Jo, Harry, or Finn.
- The kids' client is a different app, built under `internet_use_control`.

## 4. Functional requirements

| ID | Requirement |
|---|---|
| FR-1 | Capture voice. Start with **hold-to-talk**; add a wake word later. |
| FR-2 | Send the transcript to the Hub (`POST /ask`) and show the reply as text. |
| FR-3 | Play the Hub's reply as **TTS on the phone**, when the reply asks for it. |
| FR-4 | Show **approval prompts** and return approve or deny to the Hub. |
| FR-5 | Admin: list the kids' devices and their state, and lock, unlock, or grant time. |
| FR-6 | Admin calls the **internet use control** API directly. The app holds no control logic. |
| FR-7 | Gate admin actions behind a **keycode or biometric**. |
| FR-8 | Perform native actions the Hub requests: place a call, open a deep link. |
| FR-9 | Show Hub `/notify` messages as Android notifications. |
| FR-10 | Settings: Hub URL and token. Test the connection. |
| FR-11 | Offline: fail cleanly, and never claim a command succeeded. |

## 5. Screens and UX flow

**Screens**
1. **Home (Hub)** — a large talk button, the last reply, and recent history.
2. **Approvals** — pending "Did you ask for this?" items with Approve / Deny.
3. **Admin** — the kids' devices, each with its state and quick actions.
4. **Settings** — Hub URL, token, keycode, test connection.

**Main flow**
```
Sam holds the button and speaks → the Hub replies → the phone speaks it
If the Hub needs approval → a card appears → Sam taps Approve
If Sam opens Admin → he locks a phone → the internet control service applies it
```

## 6. Look and feel

Reuse the Family Home Lab design system, adapted to Android.

- Source: `/home/sam/Docker/Containers/family-home-lab/DESIGN.md`
- Tokens: `/home/sam/Docker/Containers/family-home-lab/portal/static/tokens.css`

Map the tokens to the app theme: canvas `#f6f5f4`, one action blue `#0075de`, Inter,
8px spacing, 4px inputs, pill buttons, hairline dividers, dark mode. The login/consent
moment is the one dark indigo band.

## 7. Data model

On the device only. No server database.

| Store | Holds |
|---|---|
| Settings | Hub URL, Hub token (encrypted), keycode hash |
| Cache | recent replies, pending approvals |
| Log | last actions, for debugging |

## 8. Integrations

| System | Use |
|---|---|
| **Hub** | `POST /ask`, approval callbacks, `/notify`. Frozen in `central_ai_llm_master/docs/hub-api.md`. |
| **Internet use control** | Admin lock, unlock, grant. Direct API call. See `internet_use_control/SYSTEM_MAP.md`. |
| **Android telephony** | Native calls and contacts. |
| **Deep links** | Opening a specific song or place. |
| **Artemis** | Not called from here. The Hub calls it. Native actions stay in this app. |

## 9. Technology (locked)

| Item | Value |
|---|---|
| Language | **Kotlin** (Android) |
| Voice | `SpeechRecognizer` first; a wake-word engine later |
| Transport | HTTP to the Hub. **LAN, or Tailscale when away** — decide in Phase 1. |
| Push | FCM, or polling for approvals — decide in Phase 4 |
| Min SDK | Decide in Phase 1. Suggest API 29 (Android 10). |
| Repo | `sam/kotlin_phone_app_admin` |

## 10. Rules and constraints

1. **Admin actions need the keycode or biometric.** Never a spoken keycode alone.
2. The app **never** holds control logic. It calls the service.
3. The Hub token lives in encrypted storage. Never in logs.
4. The app never claims success on a failed call.
5. Models go through **OmniRoute** — but this app talks to the Hub, not to models.
6. Own folder, own repo.

## 10a. Prerequisites (verify before Phase 1)

| Need | Status / note |
|---|---|
| **Android toolchain** | **MISSING on `.13`** — no `java`/`javac`, `gradle`, `kotlinc`, `adb`, `sdkmanager`. Phase 1 cannot start without a JDK + Android SDK + Gradle. Decide: install on `.13`, or build on `.51`. |
| **A device to test on** | `sams-pixel-8a` is on the tailnet (`100.101.49.17`). |
| **The Hub** | Live on `.13:8788`. Frozen API: `central_ai_llm_master/docs/hub-api.md`. |
| **Internet use control API** | **Not built yet.** Required from **Phase 5** (admin lock/unlock). Until then, stop at Phase 4. |

**Build order note:** this project depends on `internet_use_control` for its admin
half. That project is being built first. Phases 1–4 (voice + approvals) do not
need it; Phase 5 does.

**Task 1 should be: stand up the Android build environment and prove it** — JDK,
SDK, Gradle, then a hello-world app that calls the Hub's `/health` and shows the
result. No UI, no features. This turns "build an Android app" from an unknown
into a known.

## 11. Build order

**Phase 1 — Skeleton and settings**
Empty app, settings screen, Hub URL + token, test connection.
*DoD:* the app reaches the Hub and shows its health.

**Phase 2 — Voice in**
Hold-to-talk, send to the Hub, show the text reply.
*DoD:* a spoken question returns a Hub answer on screen.

**Phase 3 — Voice out**
Play the reply as TTS on the phone.
*DoD:* the phone speaks the Hub's reply.

**Phase 4 — Approvals**
Fetch pending approvals, show the card, approve or deny.
*DoD:* a real "did you ask for this?" from the Hub is answered from the phone.

**Phase 5 — Admin**
List kids' devices via the internet control API. Lock, unlock, grant.
*DoD:* a real device locks in under one second from the app.

**Phase 6 — Security gate**
Keycode or biometric before admin actions.
*DoD:* admin actions are blocked without the gate.

**Phase 7 — Notifications and deep links**
Hub `/notify` as notifications. Native actions and deep links.
*DoD:* a Hub notification arrives, and a deep link opens the right song.

**Phase 8 — Wake word (optional)**
Replace hold-to-talk with a wake word.
*DoD:* the wake word starts listening without touching the phone.

**Phase 9 — Documentation**
*DoD:* project-docs run; docs updated.

## 12. Acceptance criteria

- Sam asks a question by voice and hears the answer on the phone.
- An approval prompt can be answered from the phone.
- A kids' device can be locked from the app in under one second.
- Admin actions require the keycode or biometric.
- A Hub notification arrives on the phone.
- The app never reports success after a failure.

## 13. Decisions and remaining questions

Resolved:
1. **One app for Sam** (Hub + Admin). The kids' client is under `internet_use_control`.
2. **Kotlin**, Android.
3. Admin calls the internet control API directly. No Hub in that path.

Remaining:
1. **Hold-to-talk first, wake word later** — agree?
2. How does the app reach the Hub: LAN only, or Tailscale when away?
3. Approvals by FCM push, or polling?
4. Locked-screen behaviour: can approvals be answered from the lock screen?
5. Min SDK version.