# Knowledge Base

> Envie runbooks, notas de arquitetura e documentos de contexto para que as recomendações de IA reflitam como seus sistemas realmente funcionam.

Source: https://latchkey.dev/pt/documentation/knowledge-base

## Summary

- Envie runbooks, docs de arquitetura e convenções (`.md`, `.yaml`, `.yml`, `.txt`, `.json`, até 500KB) para embasar as recomendações de IA.
- Os repositórios monitorados se indexam sozinhos: READMEs, pastas de docs, arquivos de workflow e outras configs de CI.
- Uma biblioteca **System** curada de conhecimento de CI/CD vem incluída de fábrica; é somente leitura.
- Melhor embasamento significa recomendações que respeitam como seus sistemas realmente funcionam.

A página **Knowledge Base** permite dar à IA do Latchkey contexto que não é visível em seus arquivos de workflow: runbooks, docs de arquitetura, convenções de deploy, padrões de nomenclatura e qualquer outra coisa que um engenheiro gostaria de saber antes de propor uma mudança na sua CI.

## Como funciona

Os repositórios monitorados são indexados automaticamente quando você habilita o monitoramento, então a IA já conhece o layout dos seus workflows; a Knowledge Base é para tudo além disso.

## O que é indexado automaticamente

Quando você habilita o monitoramento de um repositório, o Latchkey indexa sua documentação por conta própria:

- `README.md`, `CONTRIBUTING.md` e docs de nível raiz como `SECURITY.md` e `CHANGELOG.md`.
- Markdown nas pastas `docs/`, `doc/` e `documentation/`.
- Arquivos de workflow do GitHub Actions.
- `CODEOWNERS` mais templates de issue e PR.
- Configs de CI de outros sistemas, incluindo CircleCI, Jenkins, Travis, GitLab CI, Bitbucket Pipelines e Azure Pipelines.

Arquivos inalterados são ignorados na reindexação, então o índice permanece atual sem trabalho repetido. A IA conhece seus workflows e docs reais sem que ninguém envie nada.

## A biblioteca System integrada

O Latchkey também traz uma biblioteca curada de conhecimento de CI/CD cobrindo linguagens, frameworks, ferramentas de CI/CD e padrões de runner. Esses documentos aparecem na tabela com um selo **System**; são somente leitura e não podem ser excluídos. O efeito prático: as recomendações são bem embasadas desde o primeiro dia, mesmo antes de você enviar qualquer coisa.

## Enviando documentos

Clique em **Upload Document** para adicionar os seus. Digite ou cole o conteúdo diretamente, ou carregue um arquivo por arrastar-e-soltar ou navegar. Cada documento precisa de um título (até 200 caracteres) e conteúdo, com uma contagem de caracteres ao vivo enquanto você digita. Os tipos de arquivo aceitos são `.md`, `.yaml`, `.yml`, `.txt` e `.json`, até 500KB por documento; a caixa de diálogo sinaliza tipos não suportados e arquivos grandes demais antes de qualquer coisa ser salva.

## Como o embasamento muda as recomendações

Pense nisso como a diferença entre o conselho de um empreiteiro habilidoso e o conselho do engenheiro que trabalhou na sua base de código por um ano. Ambos podem ler seus arquivos de workflow; só um sabe qual pipeline é crítico para deploy, qual falha é um problema conhecido, e por que seu caching está configurado do jeito que está.

O retorno aparece em todas as superfícies de IA do Latchkey, incluindo o [AI Insight](/documentation/optimization-insights): o que você envia aqui faz parte da verdade fundamental a partir da qual o Latchkey raciocina, então o que é proposto respeita como seus sistemas realmente funcionam.

## Envios de alto impacto

- **Runbooks de incidente** O manual do seu pipeline mais instável ensina à IA como é um "problema conhecido" para você.
- **Mapa do crítico para deploy** Um doc descrevendo quais workflows são críticos para deploy muda quão agressivas as recomendações se atrevem a ser.
- **Convenções** Padrões internos de caching, artefatos e nomenclatura mantêm as mudanças propostas idiomáticas à sua equipe.

### Como é um bom envio

Você não precisa de documentação polida; você precisa de documentos que carreguem decisões. Alguns formatos concretos que funcionam bem (são sugestões, não requisitos):

- **Um runbook de pipeline instável** que nomeie o workflow como ele aparece na CI, descreva as assinaturas de falha que sua equipe considera "conhecidas", e declare a solução alternativa aceita.
- **Um mapa de deploy** que liste quais workflows controlam a produção e quais nunca devem ser modificados sem revisão humana.
- **Um doc de convenções** que explicite como você nomeia caches e artefatos, e, crucialmente, por que essas regras existem.
- **Notas de arquitetura** que expliquem as relações que um forasteiro não conseguiria inferir: quais serviços constroem juntos, o que depende de quê, onde vivem as esquisitices estruturais.

O fio comum: anote o **porquê**, não apenas o quê. A IA já consegue ver o que seus workflows fazem; o que ela não consegue ver é o raciocínio e as restrições por trás deles.

**Uma rápida autoverificação antes de enviar**
- [ ] Está atualizado: um doc obsoleto embasa a IA em como as coisas costumavam funcionar
- [ ] Nomeia workflows e repositórios do jeito que aparecem na CI
- [ ] Explica por que cada regra existe, não apenas qual é a regra
- [ ] Diz o que não deve mudar, não apenas o que poderia ser melhorado

## Veja o que a IA sabe

Todo documento indexado aparece em uma tabela ordenável com seu título, selo de origem, caminho e horário de indexação. Uma linha de resumo mostra a contagem de documentos, o número de repositórios representados e quando ocorreu a indexação mais recente. A tabela é paginada a 10 documentos por página, inclui uma visualização em tela cheia, e um filtro de origem restringe a lista a uma fatia: All Sources, README, Workflow, Docs, Manual ou System.

| Selo de origem | O que ele marca |
| --- | --- |
| README | Arquivos README de repositório |
| Workflow | Arquivos de workflow do GitHub Actions |
| Docs | Markdown das pastas de documentação do repositório |
| Manual | Documentos que sua equipe enviou |
| System | A biblioteca de CI/CD curada do Latchkey (somente leitura) |

Você pode excluir qualquer documento que não seja System a partir de sua linha. O Latchkey pede confirmação primeiro, e a exclusão não pode ser desfeita.

> **A autocorreção também lê, com segurança**
> Quando um runner de [autocorreção](/documentation/self-healing) descobre uma correção, ele consulta o conhecimento curado do Latchkey por um canal de consulta restrito, com limite de taxa e auditado. Uma correção nunca trava esperando por uma consulta de conhecimento, e sua base de conhecimento nunca é exposta ao ambiente de build.

### Que tipos de arquivo posso enviar para a Base de Conhecimento?

Markdown, YAML, texto puro e JSON (`.md`, `.yaml`, `.yml`, `.txt`, `.json`), até 500KB cada. Runbooks, notas de arquitetura e convenções do time são os envios de maior impacto, porque registram decisões que o próprio repositório não contém.

### Preciso enviar algo para isso funcionar?

Não. Os repositórios monitorados se indexam sozinhos, cobrindo READMEs, pastas de documentação, arquivos de workflow e outras configurações de CI, e uma biblioteca System curada e somente leitura já vem incluída. Os envios acrescentam o seu contexto sobre essa base.

### O que o grounding muda na prática?

Muda se uma recomendação respeita como seus sistemas realmente funcionam. Sem seus runbooks, o modelo raciocina a partir de práticas gerais de CI; com eles, consegue considerar a restrição que levou você a fazer algo incomum, e essa é a diferença entre uma sugestão que você aplica e uma que descarta.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt