# 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

- Browsing: folder rows, folder grids, reels, fullscreen viewer driven by
  the remote. The only write is toggling a like.
- Instance found by LAN scan on first launch (manual URL as fallback),
  logged in with the viewer password, both stored on the device.
- Out of scope unless asked: uploading, editing, deleting, admin features,
  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.

## Design

The approved design is
`docs/superpowers/specs/2026-10-22-mygram-droid-design.md`: Java, minSdk
34, Glide and Media3 ExoPlayer as the only dependencies, viewer-password
login, subnet-scan instance discovery. Follow it; change it only with the
user. For Foldergram endpoints read upstream `docs/api.md` and probe the
live instance, do not guess routes or fields.

## 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.