Luma/AGENTS.md

2.9 KiB

Repository guidance

Follow Android and Android TV best practices. Keep Luma portable across current and future devices, responsive on limited hardware, and economical with memory, GPU work, background CPU, and network use.

Portability and configuration

  • Do not select rendering paths or application behavior by device model, manufacturer, product name, serial number, IP address, or a list of known devices.
  • Use documented platform APIs, API-level availability checks, measured capabilities, and resource limits when behavior needs to adapt. Provide a safe portable fallback. Make performance/quality tradeoffs explicit user settings when capability checks cannot reliably predict performance.
  • Use the same defaults across devices unless a documented capability requires otherwise. Verify optimizations on both available test devices; record comparable workloads and distinguish measurements from assumptions. Never assume that an optimization on one GPU improves another.
  • Keep deployment addresses, repository endpoints, and environment-specific values configurable or in deployment/test configuration. Do not embed a particular household's device addresses in production logic.
  • Preserve installed launchers unless the user explicitly authorizes their removal. Preserve user preferences and accessibility configuration during development and testing. Restore temporary test changes.

Keys and security

  • Never hardcode, commit, or log private keys, signing keystores, passwords, access tokens, or other secrets. Use ignored local configuration, environment variables, Android's secure storage, or a suitable secret manager.
  • Preserve the existing local APK signing identity so installed devices can accept updates. Never generate a replacement key merely to work around a build or update failure.
  • Keep TLS, SSH host identity checks, APK signature verification, and update integrity checks enabled. Resolve trust failures explicitly; do not bypass verification.
  • Public verification material and intentional public defaults may be included when required by the design; document their purpose and keep them separate from secrets and device-specific behavior.

Implementation and validation

  • Prefer maintained platform APIs and small, understandable changes. Bound image dimensions, caches, queues, downloads, and worker concurrency; cancel obsolete work and release resources when Home is hidden.
  • Preserve D-pad navigation, accessibility, focus visibility, smooth scrolling, and lifecycle recovery. Test meaningful failure and recovery cases for changes affecting rendering, persistence, updates, or background work.
  • Do not ship a claimed performance improvement based only on an isolated microbenchmark. Compare normal and rapid navigation on both available devices and disclose material tradeoffs or untested cases.
  • Review the final diff for hardcoded device assumptions and secrets before committing. Document relevant behavior, settings, and validation alongside the change.