Manutenção e Publicação de Documentação

Regra: documento sem link na sidebar = documento inexistente.
Toda documentação nova DEVE ser visível na navegação lateral do VitePress.

1. Checklist Obrigatório para Novo Documento

Cada novo arquivo .md em docs/ exige todas as etapas abaixo na mesma entrega:

[ ] Arquivo .md criado em docs/<seção>/ com nome UPPER_SNAKE_CASE.md
[ ] Entry adicionada em docs/.vitepress/config.ts na seção correta da sidebar
[ ] Entry adicionada em docs/README.md na tabela-índice da seção correspondente
[ ] Se é regra obrigatória → cláusula adicionada ao Knowledge (project-knowledge)
[ ] Se é padrão recorrente → memory criada para contexto automático

Nenhuma dessas etapas é opcional. Se qualquer uma for esquecida, o documento fica invisível para a navegação, para o AI, ou para ambos.

2. Mapa de Seções

Cada tipo de documento tem um diretório específico. Colocar no lugar certo garante que será encontrado:

Diretório	Conteúdo	Exemplos
`architecture/`	ADRs, schemas, diagramas de sistema, decisões de infra	`ADR_SERVICE_ROLE_USAGE.md`, `DATABASE_SCHEMA.md`
`security/`	RLS, auth, rate limits, auditorias de segurança, hashing	`RLS_DESIGN_GUIDE.md`, `AUTHENTICATION.md`
`development/`	Padrões de código, templates, checklists, guias de dev	`CODING_STANDARDS.md`, `NEW_EDGE_FUNCTION.md`
`operations/`	Deploy, cron, troubleshooting, monitoramento	`DEPLOYMENT.md`, `CRON_JOBS.md`
`staging/`	Setup e referência do ambiente staging	`STAGING_SETUP.md`, `STAGING_REFERENCE.md`
`mural/`	Portal aluno/responsável (Mural Olímpico)	`MURAL_OVERVIEW.md`, `MURAL_LIBERACOES.md`
`business/`	Planos, faturamento, assinaturas	`SUBSCRIPTION_BILLING.md`
`plans/`	Designs futuros não implementados	`ANOMALY_DETECTION.md`
`audits/`	Relatórios de auditoria pontuais (com data)	`AUDIT_CALENDARIO_TRIAL_CADASTRO_2026-03-30.md`

3. Convenções de Nomes

Regra	Exemplo
Nome em `UPPER_SNAKE_CASE.md`	`RLS_DESIGN_GUIDE.md`
Prefixo `ADR_` para decisões arquiteturais	`ADR_SERVICE_ROLE_USAGE.md`
Prefixo `AUDIT_` para relatórios de auditoria	`AUDIT_CALENDARIO_TRIAL_CADASTRO_2026-03-30.md`
Data no nome para documentos pontuais	`SECURITY_AUDIT_2026-02-28.md`
Sem espaços, sem acentos, sem caracteres especiais	—

4. Como Adicionar na Sidebar (`config.ts`)

O arquivo docs/.vitepress/config.ts contém o array sidebar com seções. Cada seção é um objeto:

typescript

{
  text: 'Nome da Seção',  // título visível
  collapsed: false,        // false = expandida por padrão
  items: [
    { text: 'Título do Doc', link: '/secao/NOME_DO_ARQUIVO' },
    //                        ↑ sem .md, com / inicial
  ],
}

Regras:

O link usa o path relativo à raiz de docs/, sem a extensão .md
Seções principais (Arquitetura, Segurança, Desenvolvimento) ficam collapsed: false
Seções secundárias (Testes, Staging, Operações, etc.) ficam collapsed: true
Novos itens vão ao final da lista items da seção, exceto se há ordem lógica clara

5. Como Adicionar no Índice (`README.md`)

O docs/README.md contém tabelas Markdown organizadas por seção. Cada entrada segue o formato:

markdown

| [NOME_DO_ARQUIVO.md](./secao/NOME_DO_ARQUIVO.md) | Descrição curta do conteúdo |

Adicionar na tabela da seção correspondente, mantendo a ordem existente.

6. Como o AI Recebe Contexto (3 Camadas)

O Lovable opera com três camadas de contexto. Apenas uma é controlável pelo usuário.

6.1 Camadas de Contexto

Camada	Visibilidade	Limite	Quem edita	Confiável?
Knowledge	Sempre injetado em toda mensagem, sem exceção	10.000 chars (Project) + 10.000 chars (Workspace)	Usuário manualmente	SIM — fonte de verdade
Memories	Selecionadas por relevância; podem ou não aparecer	Sem limite conhecido	Lovable (automático)	NÃO — auxiliar apenas
docs/	Consultados sob demanda — AI precisa ler explicitamente	Sem limite	Usuário ou AI via entrega	SIM — se referenciado

6.2 Memories (camada automática)

O Lovable gera automaticamente Memories a partir de padrões que emergem das conversas. Elas são metadados internos, não documentação do projeto.

Como funcionam:

Geradas automaticamente pelo Lovable a partir de padrões recorrentes nas conversas
Injetadas no bloco <useful-context> com prefixo <memory/...> antes de cada mensagem
Selecionadas por relevância estimada — NÃO garantidas em toda mensagem
Sem interface para o usuário visualizar, editar ou deletar
O usuário não controla quais Memories existem nem quando aparecem

Por que NÃO são confiáveis:

Podem estar desatualizadas (refletindo decisões antigas já revertidas)
Podem estar ausentes (o algoritmo de relevância não as selecionou)
Podem contradizer o Knowledge ou a documentação atual
Se uma regra depende exclusivamente de uma Memory, ela pode falhar silenciosamente

Regra: toda regra que "o AI aprendeu" via conversa DEVE ser formalizada no Knowledge ou em docs/. Memory nunca substitui documentação explícita.

6.3 Quando Colocar no Knowledge vs. docs/

Situação	Onde	Por quê
Regra que se aplica a toda interação (ex: "nunca usar `FOR ALL`")	Knowledge	Precisa estar visível sempre, sem depender de leitura
Ponteiro para documento detalhado	Knowledge (1 linha com `→ Ref: docs/...`)	Garante que o AI sabe que o doc existe e quando lê-lo
Guia detalhado, template, inventário, relatório	docs/ apenas	Muito grande para Knowledge; consultado quando necessário
Regra crítica + detalhes extensos	Knowledge (regra curta) + docs/ (detalhes)	Regra sempre visível, detalhes acessíveis
Regra que "o AI já aprendeu" via conversa	Knowledge (não Memory)	Memories podem desaparecer; Knowledge é garantido

6.4 Boas Práticas para o Knowledge

Compacto: cada regra em 1-2 linhas. Detalhes vão nos docs.
Estruturado: usar tabelas e seções com headers claros.
Ponteiros: toda regra que tem doc detalhado deve ter → Ref: docs/...
Tabela de leitura obrigatória: mapear tipo de tarefa → documentos que DEVEM ser lidos antes.
Sem redundância: não repetir no Knowledge o que já está nos docs — apenas apontar.
Prioridade: se Knowledge e docs conflitam, Knowledge prevalece. Se Project e Workspace Knowledge conflitam, Project prevalece.

6.5 Limitações Importantes

O AI não lembra entre sessões. Cada mensagem começa do zero com: Knowledge + Memories (se selecionadas) + código visível + histórico da sessão atual.
Memories são voláteis e opacas. Nunca assumir que uma Memory será injetada. Toda regra crítica DEVE estar no Knowledge.
docs/ não são lidos automaticamente. Se uma regra está APENAS em docs/, o AI pode não consultá-la a menos que o Knowledge instrua explicitamente.
Knowledge tem limite de 10k chars. Regras devem ser concisas. Se o Knowledge está cheio, mover detalhes para docs e deixar apenas ponteiros.

Regra prática: se em dúvida, crie o doc primeiro e adicione uma cláusula curta no Knowledge apontando para ele.

7. Validação

Após adicionar documentação, verificar:

Sidebar: o documento aparece na navegação lateral?
Índice: o documento está listado na tabela do README.md?
Links: os links internos (referências cruzadas) funcionam?
Build: npm run docs:build passa sem erros de dead links?

bash

# Verificar dead links no build
cd docs && npx vitepress build

Resumo

Novo documento = .md + config.ts + README.md + Knowledge (se regra)

Sem exceções.

Manutenção e Publicação de Documentação ​

1. Checklist Obrigatório para Novo Documento ​

2. Mapa de Seções ​

3. Convenções de Nomes ​

4. Como Adicionar na Sidebar (config.ts) ​

5. Como Adicionar no Índice (README.md) ​

6. Como o AI Recebe Contexto (3 Camadas) ​

6.1 Camadas de Contexto ​

6.2 Memories (camada automática) ​

6.3 Quando Colocar no Knowledge vs. docs/ ​

6.4 Boas Práticas para o Knowledge ​

6.5 Limitações Importantes ​

7. Validação ​

Resumo ​