# AGENTS.md: Epifah

Contexto do projeto para qualquer LLM/agente (Claude, ChatGPT, Cursor, etc.) ou pessoa nova.
Lê isto primeiro. Plano completo em `docs/PROJECT.md`.

## Resumo em 3 linhas

**Epifah** é o nome do projeto (slug `epifah`, package id `pt.ruifpb.epifah`, domínio `ruifpb.pt`).

Projeto de reverse engineering de interoperabilidade: perceber como a app **Aha Radio**
(Harman, serviço cloud morto) comunica com o **MediaNav Evolution** de um **Renault Clio IV**
e escrever uma app Android moderna que fale o mesmo protocolo, para mostrar e controlar
conteúdo atual (rádios web, podcasts, biblioteca local, etc.) no ecrã do carro.

## Ambiente do dono (preencher/atualizar)

- Carro: Renault Clio IV, MediaNav Evolution, sem Android Auto/CarPlay na unidade
- Versão hardware/software do MediaNav: `TODO`
- Telemóvel / versão Android: `TODO`
- Versão do APK Aha Radio (instalado à força): `TODO`
- Ligação testada: Bluetooth. USB: nunca testado
- Sistema de trabalho (SO, ferramentas instaladas): `TODO`
- Gitea self-hosted: `TODO url` (domínio do dono: `ruifpb.pt`)

## Estado atual

Fase 0 (ver `docs/PROJECT.md`). Atualizar esta secção no fim de cada sessão de trabalho.

- Descobertas confirmadas: nenhuma ainda
- Em curso: `TODO`
- Próximo passo: análise do manifest e strings do APK (UUIDs RFCOMM, classes de comunicação)

## Hipóteses de trabalho (NÃO são factos)

1. Controlo via Bluetooth RFCOMM/SPP com UUID próprio; áudio via A2DP separado.
   (Baseado em manuais Kenwood e Kia da plataforma Aha, não no MediaNav em si.)
2. O carro mostra um template fixo (estações, now playing, presets).
3. Protocolo binário com framing; autenticação desconhecida.

## Regras para o agente

1. **Não inventes detalhes de protocolo.** Se não há evidência (captura, hook, código lido),
   diz "não sei" e propõe como descobrir. Distingue sempre *confirmado*, *hipótese* e *desconhecido*.
2. **Toda a afirmação sobre o protocolo** deve apontar para evidência: ficheiro de captura + offset/frame,
   ou classe/método do APK. Sem evidência, entra como hipótese.
3. **Legal:** nunca pedir nem produzir cópias do APK/código da Harman nem texto descompilado extenso.
   Escrever implementação de raiz e documentação nas nossas palavras. Não ajudar a contornar
   DRM de conteúdo nem a aceder a serviços de terceiros sem autorização.
4. **Privacidade:** capturas e logs têm de ser sanitizados (MAC, tokens, credenciais, localização) antes de commit.
5. **Âmbito:** só equipamento do próprio dono, só interoperabilidade. Sem alterar firmware/ECUs do carro.
6. Prefere o caminho mais simples que dê resultado (ex.: confirmar se AVRCP browsing resolve parte do problema
   antes de investir em reimplementar o protocolo).
7. Não dar passos destrutivos sem avisar (flash, `adb` com root, alterações ao carro).
8. Se uma informação for sobre versões, preços ou estado atual de serviços/SDKs, verificar online
   em vez de confiar na memória.

## Marca e nomes

- Nome: Epifah. Descrição oficial: "Reimplementação independente do protocolo da app legada Aha Radio.
  Não afiliada à Harman nem à Renault."
- Nunca usar Aha, Harman, Renault, Clio, MediaNav, R-Link em nomes de pacotes, classes
  públicas, app, ícone ou repo. Só em documentação, de forma descritiva.
- Sem logótipos nem cores que lembrem essas marcas.

## Convenções

- Idioma: **português de Portugal** em docs, issues e commits. Código e identificadores em inglês.
- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`).
- Descobertas: uma nota por tema em `docs/findings/` (modelo em `docs/PROJECT.md`, secção 9).
- Decisões importantes: ADR curto em `docs/decisions/`.
- Android: Kotlin, `minSdk` a definir com base no telemóvel do dono.
- Protótipos de protocolo em Python (`prototype/`), com testes sobre capturas reais.

## Estrutura do repo

```
docs/PROJECT.md      plano, riscos, fases
docs/findings/       notas de descobertas
docs/protocol/       especificação do protocolo (SPEC.md, handshake.md)
docs/captures/       capturas SANITIZADAS + README de cenários
docs/decisions/      ADRs
tools/               scripts Frida e helpers de análise
prototype/           PoC Python
app/                 app Android
```

Nunca commitar: `*.apk`, `jadx-out/`, `apktool-out/`, capturas não sanitizadas.

## Contexto técnico útil

- Ferramentas previstas: jadx, apktool, Wireshark (RFCOMM/SDP), Frida (hook de `BluetoothSocket`
  input/output streams), mitmproxy (dependências de rede), adb.
- Captura BT em Android: ativar *Bluetooth HCI snoop log* nas opções de programador e extrair `btsnoop_hci.log`.
- Fonte de conteúdo gratuita para testes: radio-browser.info (rádios web).
- Projetos relacionados (inspiração, não resolvem este problema): `ddt4all`, projetos Hackaday sobre o
  protocolo CAN do display Renault. Não existe, até à data da pesquisa, nenhum projeto público que
  documente o protocolo Aha.

## Perguntas em aberto

- O carro inicia a ligação RFCOMM ou é o telemóvel?
- Há autenticação/assinatura no handshake?
- Há código nativo (`.so`) no caminho do protocolo?
- O MediaNav suporta AVRCP 1.4 com browsing?
- Existe atualização de firmware oficial que ative Android Auto nesta unidade?
- A app Aha precisa da cloud para o carro funcionar (login, listas de estações)?

## Como retomar uma sessão

Ao começar uma nova conversa: lê este ficheiro e `docs/PROJECT.md`, resume o estado em 5 linhas,
confirma o próximo passo comigo e pede-me só o que falta (ficheiros, outputs de comandos, capturas).