epifah/AGENTS.md

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