Documentação: README, roadmap e docs/ (suporte, terminal, arquitetura)

README reescrito refletindo o estado real pós-1.0.0 (ext4, APFS, HFS+,
Btrfs, XFS, BitLocker, LUKS, FileVault 2, RAID, LVM, E01/Ex01, AFF4, JPEG
fragmentado, MP4 sem moov), com links para a documentação nova.

ROADMAP.md: histórico de versões e dez áreas com estado (feito, parcial,
planejado, ideia de longo prazo), incluindo cadeia de custódia, análise
forense, interpretação de artefatos e extração de dispositivos móveis.

docs/suporte.md, docs/cli.md e docs/arquitetura.md: matriz de suporte,
referência de comandos e mapa dos módulos do núcleo. Removido docs/ do
.gitignore, já que passa a ser documentação pública do projeto.

CONTRIBUTING.md: seções para adicionar sistema de arquivos, baixar dados
de referência e manter a documentação atualizada.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/arquitetura.md

@@ -0,0 +1,95 @@
+# Arquitetura
+
+O Guará é um workspace Rust com três partes: um núcleo (`guara-core`), um binário de terminal (`guara-cli`) e uma interface (`apps/gui`) que é a mesma página web servida de duas formas.
+
+```
+crates/guara-core   biblioteca: tudo que lê, interpreta e recupera
+crates/guara-cli    binário `guara`: comandos e servidor local da interface
+apps/gui/ui         HTML, CSS e JS da interface
+apps/gui/src-tauri  casca desktop (Tauri) que carrega a mesma interface
+```
+
+## Fluxo de uma varredura
+
+```
+origem (dispositivo ou imagem)
+   │  source / device         leitura somente leitura, setores ruins tolerados
+   ▼
+disco virtual                 (opcional)
+   │  assemble                junta imagem E01/AFF4, RAID, LVM e volumes cifrados
+   ▼
+partições e volumes
+   │  partition, volume       MBR, GPT, volumes perdidos por assinatura
+   ▼
+duas buscas em paralelo
+   ├─ fs/*                    metadados: NTFS, FAT, exFAT, ext, HFS+, Btrfs, XFS, APFS
+   └─ carve + signatures      estrutura dos arquivos no espaço livre e fora de partições
+        + formats, jpegscan, defrag, mp4rebuild
+   ▼
+scan                          funde sem duplicatas e atribui a confiança
+   ▼
+sessão salva                  retomar, exportar, relatar
+   ▼
+recover                       copia com MD5, SHA-1 e SHA-256 e grava o manifesto
+```
+
+## Módulos do núcleo
+
+### Acesso e montagem
+| Módulo | Função |
+|---|---|
+| `source`, `device` | Abrir dispositivos e imagens somente para leitura; listar discos |
+| `image` | Imagem bruta tolerante a setores ruins, com mapa de erros |
+| `ewf`, `aff4` | Ler e gravar E01/Ex01 e AFF4 |
+| `assemble` | Monta o disco virtual: imagem, RAID, LVM e volume cifrado |
+| `raid`, `raid_detect`, `lvm` | Remontagem de RAID (com descoberta automática de parâmetros) e LVM2 |
+| `crypt/` | BitLocker, LUKS e FileVault 2 |
+| `reconnect` | Reconhecer o mesmo disco que voltou com outro nome |
+
+### Interpretação
+| Módulo | Função |
+|---|---|
+| `partition`, `volume` | Tabelas de partição e detecção de volumes |
+| `fs/` | Um leitor por sistema de arquivos |
+| `signatures`, `formats` | Detectores de formato pela estrutura |
+| `carve`, `scan` | Varredura por assinatura e fusão com os metadados |
+| `jpegscan`, `defrag`, `mp4rebuild` | JPEG fragmentado e MP4 sem `moov` |
+| `meta`, `sqlite`, `thumb` | Metadados, leitor de SQLite, miniaturas |
+
+### Resultado e perícia
+| Módulo | Função |
+|---|---|
+| `recover` | Copia os arquivos, confere os hashes, grava o manifesto, retoma recuperação |
+| `hashing`, `search` | Hashes e busca de texto no disco inteiro |
+| `report`, `explorer` | Relatório HTML, CSV, filtros e agrupamentos do explorador |
+| `health`, `external` | SMART e ferramentas externas (`smartctl`) |
+
+### Serviço
+`service`, `http`, `settings`, `notify`, `owner`: a camada que a interface usa (API local, configurações, notificações, e gravação com o dono certo quando roda como administrador).
+
+## Interface
+
+A interface é uma página só (`apps/gui/ui`). Há duas formas de rodá-la:
+
+- **App desktop (Tauri):** a janela carrega a página e fala com o núcleo diretamente.
+- **`guara ui`:** o binário sobe um servidor em `127.0.0.1` protegido por token e abre o navegador.
+
+Como o front-end é o mesmo, tudo que existe em um existe no outro.
+
+## Decisões de projeto
+
+- **Somente leitura na origem, por construção.** Todo acesso a dispositivo passa por `source::open_path`. Revisão de código recusa qualquer escrita na origem.
+- **Recusa de destino no mesmo disco** da origem (Linux e macOS), para não sobrescrever o que se quer recuperar.
+- **Confiança por arquivo.** Cada detector declara o quanto conseguiu conferir; a fusão fica com a melhor evidência.
+- **Leitores próprios.** Sistemas de arquivos, cifras, SQLite e contêineres de imagem são implementados no núcleo, para tolerar estruturas corrompidas, que é exatamente o caso de uso.
+- **Segredos fora da sessão.** Senhas nunca são gravadas; no máximo a chave do volume, e só com `--remember-keys`.
+- **Privilégios.** Ler disco bruto exige administrador, mas tudo que o Guará grava (sessões, relatórios, recuperados) fica com o dono e as permissões do usuário que o abriu.
+
+## Testes
+
+Cerca de cem testes, em `crates/guara-core/tests/` (um arquivo por área: `ext4`, `xfs`, `apfs`, `bitlocker`, `raid`, `ewf`, `jpegscan`, `mp4rebuild`, `sqlite` e outros).
+
+- **Imagens geradas na hora** com `mtools`, `ntfs-3g`, `e2fsprogs` e afins (`scripts/make-fixtures.sh`).
+- **Imagens de referência** de projetos externos (cryptsetup, dfvfs, AFF4) baixadas por `scripts/fetch-testdata.sh` para `target/testdata`. Sem elas, os testes correspondentes são pulados.
+- Os testes de BitLocker levam cerca de 75 s por causa da derivação de chave.
+- No CI os testes com imagens reais rodam só no Linux.

docs/cli.md

@@ -0,0 +1,124 @@
+# Referência do terminal
+
+Ler disco bruto exige privilégios: administrador no Windows, `sudo` no Linux e no macOS. Use `guara <comando> --help` para a lista completa de opções.
+
+## Comandos
+
+| Comando | Para que serve |
+|---|---|
+| `devices` | Lista discos e pendrives, avisa TRIM e volumes montados |
+| `inspect <origem>` | Partições, espaço não particionado, cifragem |
+| `health <origem>` | Saúde do disco (SMART); requer `smartmontools` |
+| `scan <origem>` | Varredura de arquivos apagados e perdidos |
+| `resume <sessão>` | Continua uma varredura pausada |
+| `recover <sessão> <destino>` | Recupera os arquivos de uma sessão |
+| `image <origem> <destino>` | Imagem forense (bruta, E01 ou AFF4) |
+| `verify <imagem>` | Confere uma imagem E01 ou Ex01 contra o hash gravado |
+| `hash <origem>` | MD5, SHA-1 e SHA-256 do dispositivo |
+| `search <origem> <termos...>` | Texto no disco inteiro, UTF-8 e UTF-16 |
+| `export <sessão> <csv>` | Planilha dos achados |
+| `report <sessão> <html>` | Relatório HTML imprimível |
+| `sessions` | Sessões salvas automaticamente |
+| `ui` | Interface no navegador (127.0.0.1, com token) |
+
+`--json` existe em `devices`, `inspect`, `health` e `scan`.
+
+## Varredura
+
+```bash
+sudo guara scan /dev/sdb --session s.json --list     # profunda, com lista
+sudo guara scan /dev/sdb --quick                     # só metadados, em segundos
+guara scan disco.img --category image,document --min-confidence medium
+guara scan disco.img --recover /mnt/outro-disco/Recuperados
+```
+
+Filtros (valem em `scan`, `recover`, `export` e `report`):
+
+| Opção | Efeito |
+|---|---|
+| `--category` | `image`, `document`, `video`, `audio`, `archive`, `database`, `other` (separe por vírgula) |
+| `--min-confidence` | `low`, `medium` ou `high` |
+| `--name` | só nomes e caminhos que contenham o texto |
+| `--organize` | como gravar: `folders` (pastas originais), `type`, `date` ou `flat` |
+
+## Recuperação
+
+```bash
+guara recover s.json /mnt/outro-disco/Recuperados --category image
+guara resume s.json
+```
+
+O destino precisa estar em **outro disco**. Cada recuperação grava `guara-manifesto.json` com MD5, SHA-1 e SHA-256 de todos os arquivos. Se a recuperação for interrompida, repetir o comando pula o que já foi copiado e conferido.
+
+## Volumes cifrados
+
+```bash
+sudo guara scan /dev/sdb1 --ask-password
+sudo guara scan /dev/sdb1 --recovery-key 111111-222222-333333-444444-555555-666666-777777-888888
+sudo guara scan /dev/sdb1 --key-file chave.BEK
+sudo guara scan /dev/sdb1 --volume-key 4f2a...
+```
+
+| Opção | Uso |
+|---|---|
+| `--ask-password` | Pergunta no terminal, sem mostrar. **Preferida** |
+| `GUARA_PASSWORD` | Variável de ambiente com a senha |
+| `--password` | Senha na linha de comando (fica no histórico do shell) |
+| `--recovery-key` | Chave numérica do BitLocker |
+| `--key-file` | `.BEK` do BitLocker ou keyfile do LUKS |
+| `--volume-key` | Chave do volume em hexadecimal (a que o Guará mostra ao abrir um volume) |
+| `--remember-keys` | Guarda na sessão as chaves dos volumes abertos (nunca a senha) |
+
+## RAID e LVM
+
+Passe o disco principal e os outros membros com `--member`, repetido. Use `-` para um disco ausente.
+
+```bash
+# Com metadados do mdadm ou do LVM: o Guará lê tudo sozinho
+guara inspect disco1.img --member disco2.img --member disco3.img
+
+# Sem metadados: descobre nível, faixa, layout e ordem
+guara scan disco1.img --member disco2.img --member disco3.img --raid
+
+# Fixando o que você já sabe
+guara scan disco1.img --member disco2.img --member - --raid \
+  --raid-level 5 --raid-chunk-kb 64 --raid-layout left-symmetric --raid-order 0,1,2
+```
+
+## Imagem forense
+
+```bash
+sudo guara image /dev/sdb /mnt/outro-disco/sdb.img                      # bruta, com mapa de erros
+sudo guara image /dev/sdb /mnt/outro-disco/sdb --format e01 \
+  --case 2026-001 --examiner "Nome" --evidence E1 --description "HD do notebook"
+sudo guara image /dev/sdb /mnt/outro-disco/sdb --format aff4
+guara verify /mnt/outro-disco/sdb.E01
+```
+
+Para E01: `--segment-mib` (tamanho de cada segmento, padrão 1500, 0 para um arquivo só) e `--compression` (0 a 9, padrão 1).
+
+## Vídeo sem índice (MP4 sem moov)
+
+Passe um vídeo **íntegro da mesma câmera ou drone** para o Guará refazer o índice:
+
+```bash
+guara scan cartao.img --reference VIDEO_BOM.MP4 --category video
+```
+
+`--reference` pode ser repetido. O áudio não é reconstruído.
+
+## Busca de texto
+
+```bash
+sudo guara search /dev/sdb "contrato" "cpf" --case-sensitive --max 500
+```
+
+Procura em UTF-8 e UTF-16 (`--no-utf16` desliga), inclusive no espaço livre e fora de partições. Mostra posição, partição e contexto. `--max` limita os resultados (padrão 200).
+
+## Relatório
+
+```bash
+guara report s.json relatorio.html --case 2026-001 --examiner "Nome" --hash-source
+```
+
+Traz identificação do caso, origem, partições, resumo, hashes e a lista dos arquivos. `--hash-source` inclui o hash da origem inteira.

docs/suporte.md

@@ -0,0 +1,102 @@
+# O que o Guará suporta
+
+Matriz do que existe hoje (versão 1.0.0). Para o que vem a seguir, veja o [ROADMAP](../ROADMAP.md).
+
+## Tabelas de partição
+
+MBR e GPT. Quando a tabela falha, o Guará procura volumes por assinatura (NTFS, FAT, exFAT, ext, APFS, HFS+, BitLocker, LUKS) e também examina o **espaço não particionado**.
+
+## Sistemas de arquivos
+
+"Metadados" significa que o Guará lê a estrutura do sistema de arquivos e devolve **nome, pasta e datas**. Sem isso, a recuperação depende só do carving, que devolve o conteúdo sem nome.
+
+| Sistema | Metadados | O que é aproveitado | Limites |
+|---|---|---|---|
+| NTFS | ✅ | MFT, registros apagados, datas de criação, modificação e acesso | Comprimidos e EFS são ignorados ou marcados como incompletos; lista de atributos tratada de forma parcial |
+| FAT12/16/32 | ✅ | Entradas apagadas, nomes longos, datas | |
+| exFAT | ✅ | Entradas apagadas, datas | Coberto por imagem sintética; falta validar em mais mídias reais |
+| ext2/3/4 | ✅ | Inodes apagados, cópias antigas no diário (ext4), mapa de blocos livres | |
+| HFS+ | ✅ | Sobras de nós da árvore de catálogo, diário | |
+| Btrfs | ✅ | Versões antigas das árvores; extensões zlib, zstd e lzo | |
+| XFS | ✅ | Inodes liberados, nomes de entradas liberadas, espaço livre por grupo | Exclusão testada só em simulação |
+| APFS | 🟡 | Contêiner, mapa de objetos, árvore de arquivos, instantâneos, nós antigos | Sem mapa de espaço livre; exclusão testada só em simulação |
+| ReFS | ❌ | Apenas detectado | Recuperação por carving |
+| Storage Spaces | ❌ | Não suportado | |
+
+Em todos os casos o carving continua rodando no espaço livre e o resultado é fundido sem duplicatas.
+
+## Volumes cifrados
+
+O Guará abre o volume com a **senha ou a chave que você fornece**, monta um disco virtual e varre por dentro. Ele não quebra senhas.
+
+| Formato | Credenciais aceitas |
+|---|---|
+| BitLocker | Senha, chave de recuperação (8 grupos de 6 dígitos), arquivo `.BEK`, chave limpa |
+| LUKS1 e LUKS2 | Senha, arquivo de chave, chave do volume |
+| FileVault 2 (Core Storage) | Senha, chave de recuperação, chave do volume |
+
+As senhas **nunca** vão para o arquivo de sessão. Com `--remember-keys` a sessão guarda a chave do volume já derivada, não a senha. No terminal, prefira `--ask-password` ou a variável `GUARA_PASSWORD` a `--password`, que fica no histórico do shell.
+
+## RAID e LVM
+
+| Item | Suporte |
+|---|---|
+| RAID 0, 1, 4, 5, 6, 10 e linear a partir de superblocos do mdadm | ✅ inclusive degradado (use `-` em `--member` para um disco ausente) |
+| RAID sem metadados | ✅ `--raid` descobre nível, faixa, layout e ordem; `--raid-level`, `--raid-chunk-kb`, `--raid-layout` e `--raid-order` fixam o que você já sabe |
+| LVM2 | ✅ linear, em faixas, espelhado e RAID |
+| Storage Spaces | ❌ |
+
+## Imagens forenses
+
+| Formato | Ler | Gravar |
+|---|---|---|
+| Bruta (dd, `.img`) | ✅ | ✅ com mapa de erros de setores ruins |
+| E01 e Ex01 (Expert Witness) | ✅ | ✅ com metadados do caso e segmentação |
+| AFF4 | ✅ | ✅ |
+
+`guara verify` recalcula o MD5 de uma imagem E01 ou Ex01 e compara com o gravado nela.
+
+## Carving: formatos reconhecidos pela estrutura
+
+Os detectores leem cabeçalhos, blocos e tamanhos internos para devolver o **tamanho exato** e uma **confiança**, em vez de cortar em um número fixo de bytes.
+
+| Família | Formatos |
+|---|---|
+| Imagem | JPEG, PNG, GIF, BMP, TIFF, ICO, HEIC, WebP |
+| Documento | PDF, DOC/XLS/PPT (OLE), DOCX/XLSX/PPTX/ODF/EPUB (ZIP), RTF |
+| Vídeo e áudio | MP4/MOV, AVI, WAV, MP3, Matroska/WebM, Ogg, MPEG-TS, FLV, ASF/WMV, MIDI |
+| Compactado | ZIP, 7z, RAR, gzip, zstd, ar |
+| Banco e sistema | SQLite, registro do Windows (regf), EVTX, PST, pcap/pcapng, EXE/DLL (PE), ELF, SWF |
+
+### Arquivos fragmentados
+
+- **JPEG:** remontado a partir de até três fragmentos (`jpegscan.rs`, `defrag.rs`).
+- **MP4/MOV sem índice (`moov`):** o índice é refeito a partir de um vídeo íntegro da **mesma câmera ou drone**, passado com `--reference`. Funciona com H.264 e HEVC. O áudio não é reconstruído.
+- Os demais formatos só saem inteiros se estiverem contíguos; do contrário saem truncados com confiança baixa.
+
+## Metadados e pré-visualização
+
+| Tipo | O que é lido |
+|---|---|
+| Fotos | EXIF: câmera, lente, número de série, data, GPS |
+| PDF | Autor, programa, datas |
+| Office e OpenDocument | Autor, última modificação por, empresa |
+| MP4/MOV | Data de gravação, duração, resolução |
+| SQLite | Esquema, tabelas, blobs, datas, linhas apagadas do espaço livre das páginas |
+
+A pré-visualização é lida direto do disco, sem gravar nada: imagem, vídeo, áudio, PDF, texto, Office, ZIP e hexadecimal.
+
+## Plataformas
+
+| | CLI | Interface | Testes com imagens reais |
+|---|---|---|---|
+| Linux | ✅ | ✅ AppImage e deb | ✅ |
+| Windows | ✅ | ✅ msi e exe | só compilação e testes sintéticos |
+| macOS | ✅ | ✅ dmg | só compilação e testes sintéticos |
+
+## O que o Guará não faz
+
+- Recuperar dados **sobrescritos**. Em SSD com TRIM o próprio disco pode zerar blocos apagados.
+- Desbloquear celulares ou contornar senhas e travas de segurança.
+- Substituir uma ferramenta de extração de dispositivos móveis.
+- Produzir laudo com validade pericial por si só: ainda não passou por validação externa (NIST CFTT). Veja o [ROADMAP](../ROADMAP.md).