[mariolucasdev]

Closes #113.

O que muda

O README.md sai de 1.338 linhas / 46 KB para 308 linhas / 11 KB. Fica nele só o que serve a quem está decidindo se usa: o que é, a matriz de capacidades, requisitos, instalação, início rápido e o índice.

1.036 linhas foram para 16 arquivos mais um índice:

docs/
├── README.md                      índice
├── capacidades.md                 erros.md
├── retry-e-idempotencia.md        ambientes-e-credenciais.md
├── cliente.md                     valores-monetarios.md
├── webhooks.md
└── gateways/
    ├── asaas.md       woovi.md          efi.md
    ├── mercado-pago.md pagbank.md       pagarme.md
    └── abacatepay.md  cielo.md          rede.md

Os títulos subiram de nível: o que era ### Asaas virou # Asaas no arquivo dele, e os #### de dentro viraram ##.

Achei um bug no caminho, e ele é o motivo do primeiro commit

Ao mapear o arquivo para quebrar, a contagem de cercas de código deu 113 — número ímpar. O bloco PHP do exemplo de recorrência da Cielo nunca foi fechado, e cercas alternam: de lá em diante o documento inteiro ficava invertido. O ### Rede e a prosa embaixo dele renderizavam como código, os exemplos seguintes renderizavam como prosa, e isso seguia por AbacatePay, Woovi e Efí — a segunda metade do README de um pacote com 593 downloads/mês.

Efeito colateral que confirma o diagnóstico: com o título preso dentro do bloco, dez links do sumário apontavam para âncoras que não existiam (#rede, #abacatepay, #wooviopenpix, #efí, #exemplos-executáveis, #migrando-da-v1, #roadmap, #contribuindo, #segurança, #licença). O verificador aponta isso sozinho quando roda contra a versão antiga.

Pelo histórico (git log -L), a cerca ficou faltando no PR do gateway Cielo (PHPAY-83), que acrescentou três linhas ao fim daquele exemplo.

O risco da tarefa, e a mitigação

Link quebrado é pior que arquivo grande. Cinco links de âncora viraram caminho relativo, cada um resolvido conforme onde o arquivo de origem foi parar — do README para docs/gateways/efi.md, de docs/valores-monetarios.md para gateways/efi.md#api-pix, e assim por diante.

Para provar que nenhum quebrou, escrevi um verificador que extrai todo link relativo e toda âncora dos markdowns do repositório, confere que o arquivo existe e que algum título gera aquela âncora:

29 arquivos, 67 links relativos conferidos
nenhum link quebrado

Ele também achou um link quebrado que já existia: o .github/SUPPORT.md apontava para ./README.md, que de dentro de .github/ resolve para .github/README.md. Virou commit próprio.

Duas mudanças de texto, declaradas

1. A matriz ganhou a sexta coluna. A verificação de assinatura de webhook entrou na v2.3.0 e a tabela seguia mostrando cinco capacidades — o leitor era informado de que a biblioteca faz menos do que faz. Com a coluna vem a explicação de por que Efí, Cielo, Rede e Pagar.me não têm ✅ ali.
2. As duas introduções de seção foram substituídas pelo índice. Uma dizia "três coisas valem entender uma vez" quando já são sete páginas de conceito, e a outra apontava para #conceitos, âncora que deixou de existir.

Como testar

composer test segue verde (nada em src/ ou tests/). O verificador de links está no scratchpad da sessão, não no repositório: se quiser, eu porto para PHP e ligo no gate, para que a próxima página nova não entre com link errado.

Vale abrir a prévia do docs/gateways/rede.md e do docs/gateways/efi.md no GitHub — são os que estavam renderizando errado.

Checklist

• composer test passa (Pint, Pest e PHPStan nível 9)
• Cobri a mudança com testes, usando HTTP mockado (nenhum teste acessa a rede) — não se aplica: só documentação
• Atualizei README, CLAUDE.md ou UPGRADE.md, se a mudança afeta quem usa a biblioteca
• Nenhuma credencial, token ou dado pessoal real foi commitado
• Li e aceito o Contributor License Agreement

Sem mudança de código. Link externo para âncora do README antigo (de fora do repositório) deixa de funcionar — é o custo inevitável de quebrar um documento, e o índice do docs/ cobre todos os destinos.