From 5368225f23112d915e27812bc19a49ba0db41bba Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Tue, 13 Oct 2026 13:58:00 +1100 Subject: [PATCH] Docs: prerequisites (Android toolchain gap), MQTT broker, cross-project deps --- AGENTS.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 59d8122..90894dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,24 @@ collects usage, and lets Sam override. in `kotlin_phone_app_admin`. - Chores, quests, or earning screen time. Removed by decision. Do not build it. +## 2a. Prerequisites (verify before Phase 1) + +Check these first. Two are missing and will stop you later if ignored. + +| Need | Status / note | +|---|---| +| **Go toolchain** | Check `go version` on `.13`. Install if missing. | +| **Docker + compose** | Present on `.13`. Run as user `sam` (in the `docker` group, no sudo). | +| **MQTT broker** | The **Mosquitto container on `.13:1883`** (running). Use per-device credentials + topic ACLs. Do **not** use Home Assistant's broker on `.30`. | +| **Android toolchain** | **MISSING on `.13`** — no `java`, `gradle`, `kotlinc`, `adb`, or `sdkmanager`. Needed from **Phase 5**. Decide: install on `.13`, or build the Android client on `.51`. | +| **Windows test machine** | Needed from **Phase 4** to prove process blocking. | +| **The phone** | `sams-pixel-8a` is on the tailnet (`100.101.49.17`). ADB wireless can reach it. | +| **Apprise** | Running on `.35:8210`. | +| **The Hub** | Live on `.13:8788`. `/ask` is read-only. Contract: `central_ai_llm_master/docs/ask-contract.md`. | +| **Admin app** | Separate project: `kotlin_phone_app_admin`. It **calls this service**. Do not build it here. | + +**Do not start Phase 5 until the Android toolchain question is answered.** + ## 3. Users and roles | User | Can do | @@ -59,7 +77,7 @@ collects usage, and lets Sam override. | FR-8 | Web dashboard: devices, schedules, blocklists, allowlists, and usage. | | FR-9 | Kids' app view: what is blocked now, until when, why, and an alert when a block starts. | | FR-10 | Override: a keycode on the device, and remote control from the admin app. | -| FR-11 | Admin app API: lock, unlock, grant time, and query state. | +| FR-11 | Admin app API: lock, unlock, grant time, and query state. **Another project consumes this** (`kotlin_phone_app_admin`) — keep the shape small and stable, and version it. | | FR-12 | Hub API: `GET /capabilities`, `POST /ask` (read-only), `POST /notify`. | | FR-13 | Alerts via Apprise when a limit is hit or a device goes offline too long. | | FR-14 | Fail safe: when a device cannot reach the broker, it keeps its last state. | @@ -137,7 +155,7 @@ The Hub interface is frozen in `central_ai_llm_master/docs/ask-contract.md`. | Backend | **Go** | | UI | **HTMX** + server-rendered HTML | | Database | **SQLite** | -| Transport | **MQTT** (existing Mosquitto) + HTTP for setup and queries | +| Transport | **MQTT** on the existing Mosquitto container at `.13:1883` (per-device creds + ACLs) + HTTP for setup and queries | | Design | Family Home Lab `tokens.css` | | Host | `.13`, Docker | | Container | **This project's own** image and compose file. |