Manutenção da wiki

A fonte pública fica em docs e usa VitePress. O build gera docs/.vitepress/dist; altere somente os arquivos fonte.

Criar ou atualizar uma página

1. Confirme o comportamento no código, nas rotas, validações e permissões atuais.
2. Edite ou crie um arquivo Markdown com nome curto em kebab-case.
3. Escreva em português do Brasil e inclua sinônimos pesquisáveis, como “flow”, “fluxo” e “automação”.
4. Adicione a página ao grupo correto em docs/.vitepress/config.ts.
5. Crie links cruzados para os pré-requisitos e próximos passos.
6. Execute npm run build.
7. Revise a página e teste uma busca pelo nome da tela e pelo sintoma.

Modelo de tutorial

Use somente as seções necessárias, nesta ordem:

1. objetivo e público;
2. quem pode acessar;
3. pré-requisitos;
4. passo a passo;
5. exemplo fictício;
6. como validar;
7. erros comuns e diagnóstico;
8. segurança;
9. próximos passos.

Páginas de referência podem usar tabelas e checklists. Não repita conteúdo canônico: resuma e vincule à página principal.

Pesquisa e navegação

A pesquisa local é gerada pelo próprio VitePress, sem serviço externo. Para facilitar descoberta:

• use o nome exato da tela no título ou texto;
• inclua termos que usuários relatam, como “não envia”, “fila pendente” e “acesso negado”;
• mantenha um único título # por página;
• prefira links relativos entre páginas Markdown;
• mantenha a jornada de implantação visível na barra superior.

Segurança editorial

Use somente domínios, pessoas, telefones e IDs fictícios. Segredos devem aparecer como nomes de variáveis ou placeholders entre <...>.

Nunca publique:

• .env, senha, token, cookie ou chave;
• token real de portal/webhook;
• payload com dados pessoais;
• domínio interno, IP privado ou detalhe de infraestrutura do cliente;
• captura de tela com credencial ou informação identificável.

Antes do commit, pesquise padrões suspeitos e analise cada resultado:

rg -n "(secret|token|password)[=:][[:space:]]*[^<{[:space:]]" docs

Validação

Build rápido da wiki:

npm run build

Preview local separado:

npm run preview

O build deve terminar sem dead links. No preview, revise menu lateral, busca, tabelas, blocos de código, versão mobile e links para páginas-chave.

Quando a documentação é obrigatória

Atualize a wiki no mesmo trabalho que alterar:

• rota, menu, perfil ou permissão;
• campo, validação, limite ou estado visível;
• configuração, variável de ambiente ou processo de deploy;
• evento, job, fila, scheduler ou retenção;
• trigger, node, credencial, contexto ou política de flow;
• conexão, webhook ou operação do WhatsApp;
• contrato do portal ou comportamento financeiro/RH.

Mudanças de payload do frontend também devem manter docs/frontend-spec.md conforme o guia do repositório.

Revisão de conteúdo

Em cada release relevante:

1. percorra a implantação;
2. compare a navegação com as rotas atuais;
3. confira inventário de ambiente e catálogo de flows;
4. execute build e busca;
5. remova instruções obsoletas;
6. confirme que nenhum segredo foi introduzido.

O critério final é simples: uma pessoa nova deve conseguir configurar um cliente e coletar evidências de aceite sem depender de conhecimento oral.