# Contribuindo com o Acauã

[English](CONTRIBUTING.md) · **Português**

Obrigado por ajudar. O projeto é um esqueleto pré-alfa, então as contribuições
mais úteis agora são testes, fixtures, documentação e correções de projeto
pequenas e bem delimitadas.

1. **Só monitoramento autorizado.** O Acauã é software defensivo para redes
   próprias ou com autorização explícita. Não adicione caminhos de coleta que
   escondam escopo, retenção ou evidência.
2. **Evidência faz parte do recurso.** Uma mudança de detecção precisa declarar
   entradas, reduções em ordem fixa e valores intermediários. Pontuação sem
   registro reproduzível de evidência não é aceita.
3. **Seja honesto sobre o que funciona.** Se um recurso é stub, só roda no Linux
   ou cobre apenas um log Zeek, diga isso no README, no `--help` e no teste.
4. **Código 100% em inglês.** Código-fonte, comentários, scripts, workflows e
   mensagens de commit são em inglês. A GUI e a CLI continuam bilíngues (PT-BR e
   EN via `i18n-en.js`).

## Fluxo

```bash
scripts/install-hooks.sh
scripts/check.sh
scripts/check.sh --full
```

O `check.sh` roda formatação, clippy com warnings como erro, cobertura de
tradução da UI, sintaxe de shell, YAML dos workflows, consistência de SemVer e a
checagem do desktop. O `--full` inclui testes do workspace e `cargo audit`.

A feature opcional DuckDB não entra na checagem padrão:

```bash
cargo check -p acaua-core --features duckdb
```

## Pesquisa

`research/` é um espaço Python isolado para validação científica. Ele pode usar
astropy, scipy, networkx, pandas e notebooks. Ele nunca deve ser importado pelo
runtime Rust, copiado para um release ou exigido para compilar o produto.

## Regras de detecção

- Mantenha reduções em ordem fixa quando resultados de ponto flutuante entram em
  um alerta.
- Use um valor sentinela documentado em vez de `NaN` ou panic para entradas
  degeneradas.
- Use Jensen-Shannon, não KL puro, quando uma distribuição pode ter probabilidade
  zero.
- Não use JA4S/JA4H/JA4X/JA4SSH/JA4L por padrão: essas variantes têm licença
  não-OSI. O JA4 de impressão digital de cliente TLS é o único padrão.
- Conexões longas precisam de detector próprio; elas não produzem os intervalos
  curtos que uma pontuação de beaconing espera.

## Interface e tradução

O texto-fonte da interface é em português. O inglês vem de
`apps/gui/ui/i18n-en.js`, aplicado em tempo de execução por `i18n.js`. Ao
adicionar texto visível, rode `node scripts/check-ui-i18n.mjs` e inclua o par em
inglês.

## Documentação

Mantenha o par: todo arquivo `*.md` e `docs/*` tem versão em inglês e em
português (`*.pt-BR.md`, `docs/pt-BR/`). Nomes de arquivo só são traduzidos
quando a palavra muda de verdade, como `architecture.md` → `arquitetura.md`.

## Commits e releases

Os commits seguem Conventional Commits 1.0.0 em inglês (`feat:`, `fix:`,
`chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `perf:`, `build:`). As versões
seguem SemVer 2.0.0 e ficam sincronizadas entre o workspace, o manifesto do
desktop e a configuração do Tauri.

Enviar uma tag `v*` cria uma Release no Gitea a partir da seção correspondente do
`CHANGELOG.md` e anexa os pacotes Linux da CLI e os bundles do desktop.

## Licença

Ao contribuir, você concorda em licenciar sob [MIT](LICENSE-MIT) **ou**
[Apache-2.0](LICENSE-APACHE), como o resto do projeto.