Documentação como base de conhecimento
O corpus do aplicativo deve acompanhar o código: regenerar e validar a documentação, construir Docusaurus, exportar Markdown, importar o vault e compilar o índice de palavras antes de publicar uma nova versão para o chat.
Exportação
O plugin local plugins/markdown-export/index.cjs executa no postBuild de Docusaurus. Ele exporta as páginas carregadas pelos plugins de documentação, incluindo os PRDs, e converte a referência estruturada de código para Markdown. Não exporta drafts nem páginas unlisted. Componentes MDX conservam o texto; imports e expressões executáveis não são avaliados nem enviados para o corpus.
O diretório build/markdown contém arquivos .md e manifest.json. Cada entrada informa caminho, título, origem, URL canônica, bytes e SHA-256. O manifesto contém o digest agregado, sem timestamp variável. Arquivos removidos não devem sobreviver no próximo snapshot.
O manifesto é o contrato para a importação: validar todas as entradas e hashes antes de criar um índice, e publicar o ponteiro de versão somente após gravar todos os artefatos. Uma atualização incompleta não pode tornar a base consultável.
Separação dos corpora
O vault regulatório existente usa BM25 sobre documentos publicados e habilitados para IA, com revalidação de hashes no PostgreSQL. Seu limite de 200 documentos não é suficiente para toda a referência do aplicativo. A integração da documentação requer um corpus próprio e índice compilado com trechos vinculados às fontes.
A migração só estará concluída com importação automática, indexação, publicação e respostas autenticadas verificadas sobre a documentação atual. A existência dos Markdown exportados, isoladamente, não comprova essa conclusão.
Referência arquitetural
How We Built Our Knowledge Base, Cerebras descreve ingestão contínua, proveniência e combinação de busca lexical com embeddings. O projeto SST-X adota atualização automatizada, evidências rastreáveis e contexto limitado; a escolha de não depender de embeddings para este corpus é uma decisão própria. Medir latência de recuperação separadamente da geração do modelo.
Importação e compilação local
npm run docs:compile-vault lê apps/docs/build/markdown/manifest.json, confere o digest, bytes e hash de cada Markdown e rejeita caminhos inseguros e symlinks. Somente após validar o corpus completo, importa os documentos para .tmp/documentation-vault/markdown e compila os trechos e as listas de palavras. Esse comando integra docs:check, depois do build Docusaurus.
O compilador divide seções por cabeçalhos fora de blocos de código, limita cada trecho a 4.000 caracteres e conserva título, seção e URL de origem. A tokenização mantém identificadores completos e seus componentes camelCase/snake_case, normalizando acentos para busca em português. Trechos idênticos na mesma fonte são deduplicados.
O índice contém 64 partes de listas invertidas e os trechos são agrupados pelo prefixo de seu hash. Isso permite carregar somente partes relacionadas à consulta e reduz a quantidade de gravações remotas. BM25 calcula relevância usando frequência e comprimento do trecho; no máximo dois trechos por fonte entram nos resultados.
publication.json registra os artefatos da compilação e seus hashes. Apenas os arquivos enumerados pertencem ao snapshot atual; sobras locais de builds anteriores não são fontes válidas. O publisher deve verificar esse inventário e publicar o ponteiro por último. O publisher automatiza essa operação no workflow de publicação.
Publicação e consumo no chat
O leitor da API exige intenção de consulta sobre o aplicativo (por exemplo senha, tela, SST-X ou um identificador de código) antes de consultar o corpus. Perguntas gerais de SST e saudações não desviam a recuperação regulatória. Nas consultas documentais autenticadas, verifica documentation/current.json a cada pergunta. O ponteiro identifica uma publicação imutável em documentation/vaults/<buildId>, cujo identificador é o SHA-256 de publication.json. O inventário, o índice, as partes de postings e os trechos recuperados são conferidos antes do uso. Remover o ponteiro desabilita o corpus mesmo quando o índice anterior estava em cache. O índice wire schema 2 compartilha metadados de cada fonte entre trechos. Consultas concorrentes compartilham uma única carga por versão; a versão imutável permanece em cache até mudar o ponteiro.
npm run docs:evaluate-vault verifica todos os artefatos e trechos, depois exige resultados relevantes para perguntas de recuperação de senha, identificadores de código e atualização de documentação. npm run docs:publish-vault repete a avaliação, envia os arquivos declarados, confere a leitura remota e só então escreve o ponteiro. Falha antes dessa ativação mantém a versão anterior. Credenciais CLOUDFLARE_ACCOUNT_ID e CLOUDFLARE_API_TOKEN são necessárias; nunca fazem parte do corpus.
O workflow de documentação serializa execuções de produção e publica o vault após o portal. Pull requests apenas validam e preservam artefatos. Os links de documentação aparecem no Chat-IA; o modelo recebe os trechos como contexto não confiável, separado das instruções. Recuperação lexical não chama embeddings. O corpus regulatório continua disponível para perguntas normativas.
O comando npm run canary:chat-ia-documentation verifica uma pergunta real sobre recuperação de senha com identidade sintética, exige a fonte documental, a rota /forgot-password e uma citação na resposta, depois remove os dados sintéticos. Somente o resultado observado desse canário pode comprovar publicação e resposta em produção.
Compatibilidade de persistência e geração
A migração 0167_documentation_knowledge_version.sql amplia ai_messages.knowledge_base_version para 64 caracteres, preservando o SHA-256 completo da publicação. Deve ser aplicada antes de ativar o primeiro vault documental; a coluna antiga de 50 caracteres rejeita a gravação da pergunta.
A recuperação BM25 e a geração são etapas distintas. O Chat-IA solicita Kimi K2.6 via 9Router com chat_template_kwargs.thinking: false, controle documentado por Cloudflare, para reservar o limite interativo de 1.024 tokens à resposta final. Sem esse controle, uma resposta pode consumir todo o limite apenas em raciocínio e chegar vazia. Outros modelos não recebem esse parâmetro específico. Para dúvidas operacionais simples, o contexto do chat orienta até seis passos curtos e uma citação, preferindo até 180 palavras; o formato técnico extenso fica reservado às perguntas que o solicitam. Diagnósticos de falha registram somente comprimentos, motivo de término e contagem de tokens, nunca o texto de raciocínio ou credenciais.