ADR 001 · Hospedagem da documentação

• Data: 22/08/26
• Status: aceito

Contexto

O projeto precisava de uma documentação detalhada — fluxos, gráficos de desempenho, explicação metodológica da prescrição e a parte técnica do app — com dois requisitos duros: existir em versão gratuita e suportar visibilidade pública e privada ao mesmo tempo. A documentação será revisitada e atualizada com frequência, boa parte disso com ajuda de IA (Claude Code).

Foram avaliados VitePress, Docusaurus, GitBook, Notion e Mintlify.

Decisão

VitePress dentro do próprio repositório, publicado como dois sites no Cloudflare Pages, com o site interno protegido por Cloudflare Access.

Por quê

O arquivo mora junto do código. Este é o critério que decide, não a aparência do site. Documentação que o Claude Code mantém precisa ser Markdown versionado no mesmo repositório: assim a atualização da doc entra no mesmo commit da mudança que a causou, aparece no diff e é revisável no PR. GitBook e Notion tiram os arquivos do repositório e transformam cada atualização numa chamada de API sem diff — é exatamente aí que a documentação começa a mentir sem ninguém perceber.

Os requisitos eliminam metade das opções sozinhos:

	Grátis	Privado no plano grátis
VitePress / Docusaurus / Starlight	sim (MIT)	depende do host
GitBook	sim	não — acesso autenticado só no Ultimate (US$249/site/mês)
Mintlify	Starter grátis	não — senha/SSO só no Pro (US$450/mês)
Notion	sim	sim, mas reprova na manutenção por IA

Entre os geradores estáticos, VitePress por três motivos: Markdown puro em vez de MDX (menos sintaxe para a IA quebrar), build rápido o bastante para rodar a cada alteração, e detecção de dead link no build — que dá ao agente um teste automático real depois de mexer em dezenas de arquivos. Docusaurus só se ganharia se houvesse necessidade de versionamento de documentação (v1/v2) e i18n, que não é o caso.

Cloudflare porque o GitHub Pages não resolve o requisito de privado: site com visibilidade privada só existe no GitHub Enterprise Cloud. Além disso o /holy-squat-app/ do Pages já está ocupado pelo Flutter Web e um segundo site ali criaria conflito de base-href. O Cloudflare Zero Trust cobre até 50 usuários no plano gratuito, com login por e-mail e PIN — mais que suficiente para "eu e poucos convidados".

Dois builds, não um site com rota protegida

Decisão deliberada e não óbvia: existem dois roots VitePress independentes (publico/ e interno/), que geram dois bundles e dois deploys.

A alternativa tentadora — um site só, com uma policy de Access no caminho /interno/* — não isola de verdade. O VitePress compila o conteúdo das páginas em chunks com hash sob /assets/, buscados pelo roteador client-side; uma regra por caminho protege a URL mas não esses arquivos, e o conteúdo ainda vaza pelo índice de busca local e pelo sitemap. Dois builds tornam o vazamento estruturalmente impossível: o conteúdo interno nunca é lido pelo build público.

Consequências

• Publicar algo é escolher em qual pasta o arquivo nasce. Mover um arquivo entre publico/ e interno/ é uma decisão editorial consciente, e é isso que se quer.
• Domínio próprio é opcional: o Access protege a própria URL pages.dev de produção, desde que o curinga seja removido do subdomínio da aplicação (corrigido em 22/08/26 — a versão inicial deste ADR afirmava que o domínio era necessário). Passo a passo em Publicar a documentação.
• npm run check roda os dois builds e verifica que nenhum termo interno apareceu no bundle público.
• Se um dia a doc pública crescer para explicar metodologia, ela cresce dentro do mesmo VitePress — sem migração.

Alternativa mantida em reserva

Se o domínio não valer a pena agora: publicar apenas o site público e manter o material interno como Markdown no repositório privado (o GitHub renderiza Mermaid nativamente). Perde-se gráfico interativo do lado interno; não se perde nada da estrutura, porque os arquivos já estariam no formato certo.