# Base de Conhecimento para Agentes de IA

Esta base foi projetada para leitura eficiente por agentes e humanos.

## Arquitetura recomendada
- `index.json`: catalogo central para busca semantica rapida por agente.
- `records/`: um registro por arquivo Markdown, com metadados em front matter YAML.
- `schemas/`: contrato JSON Schema para validar metadados e manter consistencia.

## Por que esse formato e eficiente
- **JSON para roteamento**: agentes localizam o registro certo sem ler toda a base.
- **Markdown para contexto**: explica causa, impacto e procedimento com baixa ambiguidade.
- **Metadados padronizados**: permite filtro por `tags`, `severity`, `domain` e `status`.
- **Versionamento simples**: cada incidente vira um arquivo independente e auditavel no Git.

## Convencao de registros
- ID: `KB-<DOMINIO>-NNN` (ex.: `KB-INFRA-001`)
- Nome de arquivo: `<ID>-<slug>.md`
- Campos obrigatorios de metadados:
  - `id`
  - `title`
  - `domain`
  - `tags`
  - `status`
  - `severity`
  - `created_at`
  - `updated_at`
  - `applies_to`

## Fluxo de atualizacao
1. Criar novo registro em `records/<dominio>/`.
2. Atualizar `index.json` com resumo e caminho.
3. Validar aderencia ao schema em `schemas/`.
4. Referenciar o registro em documentacao operacional quando necessario.

## Validacao automatica
Use:

```bash
make kb-check
make kb-fix
```

A verificacao valida:
- metadados obrigatorios conforme schema;
- padrao de ID de registro;
- sincronizacao entre `index.json` e arquivos em `records/`.

`make kb-fix` faz ajustes automaticos no `index.json`:
- inclui registros faltantes;
- remove entradas orfas;
- sincroniza campos principais;
- atualiza `last_updated`.