Documentation Agent e Knowledge Center

Os três agentes desta página se apresentam como "da Radhr AI" (sem "da Witbiz") desde 12/10/2026 — só a frase de identidade mudou; gatilhos, entradas e validações seguem iguais.

A documentação da Radhr AI não é escrita depois: ela é gerada e conferida a partir do código a cada versão e servida dentro do próprio Radar, em /radar/conhecimento. A decisão está no ADR-0010 e o desenho completo em docs/radar/living-documentation.md.

Como a base nasce

1. npm run docs:gerar (em _source/novo) roda scripts/conhecimento.mjs.
2. O extrator lê o código: rotas Hono (com o prefixo das montagens, parâmetros, query, campos do formulário, respostas e códigos de erro lidos do handler), o SQL (db/schema.sql + migrações em ordem: colunas, tipos, obrigatoriedade, padrão, FK, valores do check, comentários de fim de linha, índices, restrições, RLS), os agentes de IA (todo chamarClaude/registrarChamadaIA com rótulo e os objetos Analise<…>: arquivo, modelo, versão do prompt, max_tokens e um hash dos literais longos, que é onde moram os prompts), eventos (registrarEvento), crons (wrangler.jsonc × scheduled), cadeias da fila, ferramentas do Copiloto, segredos do Env e o comentário de topo de cada módulo.
3. Lê os documentos: docs/conhecimento/** (com front matter e cobre), ADRs, CONTEXT.md (glossário), docs/radar/* (roadmap/arquitetura), docs/produto/* e docs/operacao/*.
4. Calcula a assinatura estrutural de cada item e compara com docs/conhecimento/_gerado/assinaturas.json: o que é novo, alterado ou removido entra no changelog (_gerado/mudancas.json) com categoria e impacto heurístico, e a data da mudança fica registrada por item.
5. Escreve src/conhecimento/base.gerada.ts, que vai no bundle do Worker. A documentação publicada é sempre a da versão publicada do código.

Portão no CI

O teste test/conhecimento.test.ts roda o extrator em modo de verificação: se o código mudou e a base não foi regenerada, o CI fica vermelho com a mensagem "rode npm run docs:gerar". O mesmo teste exige que as nove áreas funcionais tenham documento com as sete seções, que todo agente e toda tabela tenham documento escrito e que nenhum cobre aponte para item que não existe mais.

Desde a fase 4, test/conhecimento-fase4.test.ts também reprova o CI quando o Living Documentation Score fica abaixo da meta de 90 (META_SCORE em src/conhecimento/saude.ts) ou quando algum documento está desatualizado. Mudou o comportamento de algo que um documento cobre? O mesmo PR revisa o documento e atualiza o revisado_em.

Documento desatualizado

Um documento escrito fica desatualizado quando qualquer item do seu cobre mudou depois do revisado_em. O painel e a página do documento mostram quais itens mudaram e quando. Resolver = revisar o texto, atualizar revisado_em, npm run docs:gerar, commit.

Living Documentation Score

Média ponderada de cinco coberturas — funcional 25% (áreas com as sete seções), IA 25% (agentes, cadeias, ferramentas), técnica 20% (telas, módulos, jobs, eventos, segredos), banco 15% e APIs 15%. Item com documento escrito vale 1; item que só tem comentário no código vale ½. Do resultado saem 3 pontos por documento desatualizado (até 20) e 2 por referência órfã (até 10). Risco baixo com score ≥ 85 e nenhum desatualizado; médio ≥ 65; alto abaixo. Código em src/conhecimento/indice.ts.

Assistente de documentação

docs_assistente (src/conhecimento/agente.ts, função perguntar).

• Objetivo: responder perguntas sobre a Radhr AI citando a documentação oficial.
• Gatilho: botão "Perguntar à IA com estas fontes" na busca (POST /radar/conhecimento/perguntar).
• Entradas: até 8 trechos da busca (máx. 12 mil caracteres), numerados com título e link.
• Saídas: markdown com citações [n] que viram links para a fonte.
• Modelo e versão do prompt: MODELO (Sonnet) sem raciocínio, 900 tokens, VERSAO_PROMPT_DOCS = docs-v1.
• Validação em código: sem trecho encontrado, o modelo não é chamado e a resposta é "a documentação ainda não cobre isso". Resposta sem citação [n], ou citando número que não está entre as fontes entregues, não é mostrada nem guardada no cache: a tela exibe só os trechos oficiais (citacoesValidas). Fontes são dados, nunca instruções.
• Fallback: falha do modelo devolve os trechos encontrados, sem texto gerado.
• Cache: KV (RADAR_KV) por hash da pergunta + versão da base (hash de cada documento e data de cada item do inventário: qualquer edição invalida), 7 dias.

Smart Changelog

docs_changelog (resumirMudancas).

• Objetivo: transformar a lista de itens mudados num dia em changelog para humanos: o que mudou, impacto, risco, funcionalidades e usuários afetados, necessidade de treinamento e orientação.
• Gatilho: botão na entrada do changelog (POST /radar/conhecimento/mudancas), só Witbiz.
• Validação em código: JSON com impacto do vocabulário fechado (baixo|medio|alto); fora disso, cai na regra (resumoPorRegra: impacto = o maior detectado; treinamento quando muda tela ou agente).
• Versão: calculada pelo código, não pela IA — removido de impacto alto sobe a major, item novo a minor, alteração o patch.

Rascunho de documentação

docs_rascunho (rascunhar).

• Objetivo: a documentação inicial de um item sem documento, no formato desta pasta.
• Gatilho: "Rascunhar documentação com IA" na página do item (admin da Witbiz).
• Entradas: só os fatos que o extrator leu (JSON do item). O que falta vira "A CONFIRMAR".
• Handoff humano: o rascunho nunca é publicado sozinho — a pessoa revisa, salva em docs/conhecimento, regenera a base e faz commit.

Documentação como contexto dos agentes

A ferramenta consultar_documentacao do Copiloto usa a mesma busca, com as mesmas fontes autorizadas de quem pergunta. O prompt do Copiloto manda consultá-la antes de explicar como a Radhr AI funciona e dizer "a documentação não cobre" em vez de supor.

**Fase 1 — contextoDocumental(area)** (src/conhecimento/contexto.ts): os agentes do funil recebem no system prompt a seção "Regras de negócio" do documento funcional da área (até 3.500 caracteres, cortada em parágrafos), com a versão do documento — Proposal Strategist (propostas), motor de risco e Expansion Opportunity Agent (clientes), Scope Builder, Scope Validator e Change Request Analyzer (escopos). A versão do documento entra no hash de entrada das análises idempotentes (risco, expansão, estratégia): documento revisado → análise refeita na próxima leitura. As regras que o código valida continuam no código e prevalecem; a documentação dá ao modelo o porquê. — src/conhecimento/contexto.ts, src/expansao.ts, src/risco.ts, src/estrategia.ts, src/escopo.ts, src/mudancas.ts

Agente no PR (fase 1)

scripts/docs-agente.mjs, rodado pelo workflow .github/workflows/docs-agente.yml a cada pull request que toca código, banco ou docs/conhecimento:

1. regenera a base e lê as mudanças do inventário do dia e os documentos afetados (documentosAfetados: cobrem um item mudado no PR ou um item que mudou depois do revisado_em);
2. lê o diff do PR contra a base (git diff origin/<base>...HEAD, até 60 mil caracteres), os fatos do inventário dos itens (fatosDosItens) e o documento;
3. pede ao modelo (DOCS_MODELO, padrão claude-sonnet-5; prompt docs-pr-v1) um patch por documento — até 8 edições {secao, trecho_atual, novo_texto, motivo}; interpretarEdicoes descarta trecho que não existe no documento;
4. publica um comentário no PR (marcado <!-- docs-agente -->, atualizado a cada push) com os itens mudados, cada documento afetado e as edições em formato diff, mais o revisado_em a colocar.

Nunca faz commit: um humano aplica, atualiza revisado_em e roda npm run docs:gerar. Sem o segredo ANTHROPIC_API_KEY no repositório, o comentário só lista o que revisar. O extrator ainda emite avisos de convenção no CI (::warning::): rota nova sem comentário de uma linha acima do handler e coluna nova sem -- o que é na migração.

OpenAPI e Postman

/radar/conhecimento/openapi.json (OpenAPI 3.1) e /radar/conhecimento/postman.json (coleção v2.1) são gerados do inventário de rotas em src/conhecimento/openapi.ts: parâmetros de caminho e query, corpo (JSON nas APIs e webhooks; formulário com _csrf nas ações com sessão), respostas por tipo e erros, esquemas de segurança (cookie da sessão, assinatura HMAC do provedor), a fonte no código e o documento escrito que cobre cada operação. Por padrão só o contrato público (/api, /pp, /c, /portal, /d, /p, /planos e as APIs da Radhr AI); ?internas=1 inclui telas e ações. Só a Witbiz (organização 1) baixa. Mudança em rota pública continua com impacto alto no changelog.

Edição na Radhr AI, versões e fila de revisão (fase 2)

Migração 0029 (doc_documentos, doc_versoes, doc_perguntas, doc_revisoes; RLS). O repositório continua sendo a fonte; a Radhr AI guarda versões por cima dele.

• Editar (admin da Witbiz): /radar/conhecimento/editar/<id> — markdown sem front matter; salvar cria uma nova versão (doc_versoes, hash sha256 do corpo, autor, origem humano|agente|git|rollback, motivo); o histórico nunca é reescrito. Salvar resolve as revisões abertas do documento.
• Sobreposição: a base em memória recebe a última versão publicada de cada documento da Radhr AI (cache de 1 min): busca, assistente, Copiloto e o contexto dos agentes passam a ler o texto novo na hora; a versão do documento (hash) muda, então as análises idempotentes são refeitas. Sem a migração, tudo segue com o bundle.
• Versões, diff e rollback: /radar/conhecimento/versoes/<id> lista as versões, compara qualquer uma com a atual (diff de linhas) e restaura (nova versão com o corpo antigo, origem rollback).
• Volta ao Git: a página do documento mostra "editado na Radhr AI · ainda não está no repositório" até o corpo do bundle ter o mesmo hash; /radar/conhecimento/baixar/<id> entrega o .md com o front matter reconstruído para o commit.
• Perguntas e feedback: cada resposta do assistente fica em doc_perguntas com 👍/👎; 👎 abre uma revisão (feedback) apontando o documento da primeira fonte; pergunta sem fonte (assistente ou Copiloto) abre pergunta_sem_fonte sem documento.
• Fila de revisão: /radar/conhecimento/revisoes — pendências abertas (assumir, resolver, dispensar, editar o documento), documentos com item mudado depois da revisão e as perguntas recentes. A Home do Knowledge Center mostra o total aberto.

Fica para a fase 2b: busca híbrida com embeddings (doc_trechos, Voyage) — depende da chave — e a edição de documentos pela própria organização (fase 3).

Registro dos agentes na página de IA

/radar/conhecimento/ia mostra, ao lado do inventário de cada agente, o registro dos últimos 30 dias na organização (src/agentes-registro.ts): chamadas, custo, análises gravadas e quantas caíram na regra. O admin da Witbiz vê outra organização com ?org=<id>.

Documentação da organização e "O que é isto?" (fase 3)

• Documentos da organização: em /radar/conhecimento/organizacao ("Como fazemos aqui"), o admin da organização escreve playbooks, regras comerciais, processos e guias de tela em Markdown.
• Ficam em doc_documentos com organizacao_id dela, seção organizacao e o tipo em area.
• Cada salvamento é uma versão (doc_versoes), com a mesma tela de versões e restauração da fase 2.
• Arquivar tira o documento da busca e do Copiloto; reativar devolve.
• Permissões: no modelo antigo, só o admin escreve; no RBAC v2, a permissão é organizacao.perfil, decidida pela mesma engine das escritas (papel do vínculo e overrides) também nas telas de edição. Os demais papéis só leem.
• Arquivado aparece na lista de gestão sem link para a página (só versões e reativar).
• Base por organização: sincronizarOrganizacao (src/conhecimento/edicao.ts) monta a base da plataforma mais os documentos publicados da organização. BASE_CONHECIMENTO() devolve a base da organização do contexto, então a busca, o assistente, o Copiloto (consultar_documentacao) e o contexto dos agentes leem os dois.
• Agentes do funil: contextoOrganizacional (src/perfil/contexto.ts) sincroniza a base da organização antes do prompt, e promptDocumental acrescenta as regras comerciais que ela escreveu (tipo regras), delimitadas como dados, depois das regras fixas e do documento da plataforma (o código segue prevalecendo). A versão delas entra em versaoDocumental — regra revisada → risco, expansão e estratégia refeitos na próxima leitura.
• Nenhuma organização vê documento de outra; a Witbiz também não vê os das organizações clientes.
• Os documentos da organização ficam fora do score, da cobertura e do changelog da plataforma (não são curado; BASE_PLATAFORMA() é a base sem eles).
• Na busca, o processo da própria organização pesa mais que a regra genérica. O Copiloto é orientado a dizer as duas quando divergirem.
• "O que é isto?": o botão ⓘ no topo de toda tela da Radhr AI abre /radar/conhecimento/ajuda?caminho=<tela> (src/conhecimento/ajuda.ts, sem IA). A página mostra:
• a tela é achada pela rota do inventário, inclusive as com parâmetro de padrão do Hono (:id{.+});
• os guias da organização que declaram aquela tela (cobre com tela:/radar/lead/*, coluna da migração 0038);
• o trecho da seção Telas e o Fluxo do documento funcional que cobre a rota do inventário;
• um atalho para o admin escrever o guia da tela.

Sem a 0038, os documentos da organização funcionam; só os guias não entram na ajuda das telas.

A documentação que se sustenta sozinha (fase 4)

• Meta de engenharia: score ≥ 90 e nenhum documento desatualizado, verificados no CI (seção "Portão no CI"). O score aparece na Home do Knowledge Center, na tela de uso e no relatório semanal.
• Relatório semanal: o e-mail de segunda (e a prévia em /radar/relatorio) ganhou a seção "Documentação viva" (htmlDocumentacao em src/relatorio.ts, dados de saudeDaDocumentacao):
• para a Witbiz, o score com a meta, o delta contra a semana anterior, o risco e os documentos desatualizados;
• para todas as organizações, as perguntas da semana, quantas ficaram sem fonte, a taxa de respostas úteis e até 3 perguntas sem resposta;
• a fila de revisão e as áreas que pedem treinamento.

O score da semana é gravado no evento docs_saude_semanal só no envio de segunda; a prévia não grava.

• Uso: /radar/conhecimento/uso (7, 28, 56 ou 90 dias) mostra, para a organização da sessão:
• as perguntas por canal (busca e Copiloto) e quantas pessoas perguntaram;
• a taxa sem fonte e a taxa de respostas úteis;
• a tendência por semana;
• as perguntas sem resposta, agrupadas;
• os documentos mais citados.

Os números saem de doc_perguntas (metricasDeUso, função pura): toda pergunta do assistente e toda consulta do Copiloto (com ou sem fonte) é registrada lá. Nenhuma organização vê perguntas de outra.

• Treinamento gerado do changelog: /radar/conhecimento/treinamento (7, 30 ou 90 dias) monta um módulo por documento funcional (treinamentoDoChangelog). Entra no módulo:
• toda mudança do changelog em tela, ação, agente de IA, ferramenta do Copiloto ou cadeia da fila que o documento cobre;
• todo documento funcional revisado no período, porque a regra pode ter mudado sem item estrutural.

Roteiro de treinamento

docs_treinamento (roteiroDeTreinamento em src/conhecimento/saude.ts).

• Objetivo: um roteiro curto para a equipe reaprender uma área que mudou.
• Gatilho: "Gerar roteiro de treinamento" em /radar/conhecimento/treinamento. Vale para todos os papéis, como uma pergunta à documentação (permissão docs.ler no RBAC v2; escritaDeConsulta no modelo antigo). O custo entra no limite de IA da organização.
• Entradas: as mudanças da área em linguagem de quem usa (descreverItem: "tela /contrato/:id/pdf", "agente de IA contrato"), a data da revisão e as seções Fluxo e Telas do documento funcional.
• Saídas: Markdown com as quatro seções Objetivo, O que mudou, Passo a passo e Perguntas de checagem.
• Modelo e versão do prompt: MODELO (Sonnet) sem raciocínio, 900 tokens, VERSAO_PROMPT_TREINAMENTO = docs-treinamento-v1.
• Validação em código: roteiroValido exige as quatro seções. O modelo só pode usar o trecho do documento e a lista de mudanças.
• Fallback: roteiroPorRegra monta as mesmas quatro seções com o texto do documento. É usado quando a IA não responde, recusa ou devolve formato inválido.
• Cache: KV por hash da entrada, 30 dias.
• Handoff humano: o roteiro é material de apoio; quem treina revisa antes de usar.

Quem vê o quê

Organização 1 (Witbiz) vê tudo. Outras organizações veem o funcional, o glossário e os próprios documentos (seção organizacao, fase 3), na busca, no assistente e no Copiloto; banco, APIs, IA, técnica, decisões e roadmap respondem 403. Documento de uma organização nunca aparece para outra, nem para a Witbiz.