CL-2026-04-08-BK-239 - Unificacao documental de docs com AGENTS como entrada principal

Contexto

A camada /docs estava carregando onboarding duplicado e parcialmente desatualizado entre:

• docs/AGENTS.md
• docs/README.md
• docs/00_SITEMAP_DOCUMENTACAO.md

O rename anterior de docs/AGENT.md para docs/AGENTS.md, somado a limpeza recente de arquivos legados, deixou a trilha documental com necessidade de reconciliacao para evitar:

• links quebrados;
• descricao incorreta da estrutura de docs/;
• sobreposicao de funcao entre README, AGENTS e SITEMAP.

O que mudou

1. docs/AGENTS.md

Passou a ser a entrada operacional principal de /docs.

O arquivo agora concentra:

• leitura obrigatoria ao entrar na camada documental;
• fontes de verdade da governanca documental;
• mapa rapido de governanca, docs tecnicas, apoio e historico;
• regras para nao usar arquivos historicos ou links ausentes como referencia automatica;
• gatilhos de manutencao da propria camada /docs.

2. docs/README.md

Foi reduzido a stub minimo.

Em vez de repetir onboarding e listas de documentos, agora ele apenas aponta para:

• docs/AGENTS.md
• docs/00_SITEMAP_DOCUMENTACAO.md

Isso reduz friccao e evita que o onboarding fique divergente em dois arquivos diferentes.

3. docs/00_SITEMAP_DOCUMENTACAO.md

Foi reescrito para refletir o estado real atual de docs/.

O novo sitemap:

• descreve a estrutura atual das pastas e arquivos principais;
• diferencia material ativo de acervo historico;
• registra explicitamente referencias removidas da trilha principal;
• deixa claro que docs/AGENTS.md e a entrada principal e docs/README.md e apenas stub.

Referencias stale removidas do fluxo principal

O fluxo principal de onboarding deixou de tratar como referencia atual:

• .claude/CLAUDE.md
• PROCESSO_DEPLOY.md
• DEBUG.md
• README_FOTOS.md na raiz do projeto
• GUIA_RAPIDO_FOTOS.md na raiz do projeto
• documentos historicos removidos ou ja arquivados em docs/arquivo_v2026/

Validacao

Validacoes executadas nesta rodada:

• leitura integral de docs/AGENTS.md, docs/README.md e docs/00_SITEMAP_DOCUMENTACAO.md;
• checagem local dos links principais mantidos no novo AGENTS e no novo SITEMAP;
• comparacao com segunda opiniao externa trazida via OpenCode pelo usuario, aproveitando a direcao correta e descartando falsos positivos do checklist bruto.

Resultado

Ao final do BK-239:

• docs/AGENTS.md virou a fonte principal de entrada de /docs;
• docs/README.md deixou de competir com AGENTS;
• docs/00_SITEMAP_DOCUMENTACAO.md passou a servir como mapa factual e nao como inventario idealizado;
• a camada documental ficou mais simples de manter e menos sujeita a drift.