# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this is

`mygram-droid`: a native Android TV client for browsing a self-hosted
Foldergram instance (an Instagram-style gallery served from local folders).
The app talks to the instance over its HTTP API and presents folders,
photos and videos in a remote-friendly, D-pad driven TV interface.

## Scope

- Read-only browsing: list folders, open a folder feed, view media
  fullscreen, step through items with the remote.
- Server address entered once on first launch and stored on the device.
- Out of scope unless asked: uploading, editing, deleting, accounts beyond
  what the instance itself requires, phone/tablet layouts.

## Target device

- Chromecast with Google TV HD: Google TV 14 (API 34), 32-bit ARM
  (`armeabi-v7a`), about 1.4 GB RAM. Keep memory use low, downscale images
  to screen size before decoding.
- Same device as the sibling `../tv-debloat` project. Its launcher shows a
  working setup to reuse: Java, minSdk 34, built in Docker (JDK 17, SDK 34),
  installed over adb.
- Reached over wireless adb from the Linux host. Wireless debugging turns off
  on every reboot, so re-enable it on the TV after one.
- Verify every UI change on the TV: `adb shell input keyevent` to drive it,
  `adb exec-out screencap -p` to see it. Send `KEYCODE_WAKEUP` first or the
  screenshot comes back black.
- Do not touch device state beyond installing and launching this app. Package
  disables, Home and launcher changes belong to `tv-debloat`, where they once
  cost a factory reset.

## Instance

- The instance is on the LAN over plain HTTP with a non-standard port, so the
  app must allow cleartext traffic (network security config).
- The real instance address is personal, keep it out of the repo. It is in
  agent memory, or ask the user.

## Open decisions

Not yet settled, ask before assuming:
- Language and UI toolkit (e.g. Kotlin with Compose for TV vs Leanback).
- Minimum Android TV API level.
- Which Foldergram API endpoints to use; read the instance's actual API,
  do not guess routes.

## Conventions

- Placeholders only in code, docs, tests and commits. Use
  `https://foldergram.example.org` for any instance URL, never a real host.
- Every source file carries the GPLv2 header:
  `Copyright (C) <year> Danilo M. <danix@danix.xyz>`.
- Minimal dependencies: platform and AndroidX first, third-party libraries
  only with a clear reason.
- Every screen must be fully usable with a D-pad remote (visible focus,
  no touch-only controls).

## Testing

No test suite yet.

## Repo facts

- License: GPLv2 only (`LICENSE`).
- Work directly on master.