Balde de Conhecimento

O que ele faz

• Ciclo de vida explícito

  Toda skill vive rascunho → canônica → depreciada. Rascunhos podem existir aos montes; canônicas são as que a organização promete manter.

• Trava de promoção

  POST /api/publish devolve 409 até que os nove controles mínimos passem — documentação, fontes citadas, reprodutibilidade, dono nomeado. Ou é PINO ou não sobe.

• Ledger em git de verdade

  Cada criação, upload, edição ou promoção vira um commit assinado pelo autor real (nome e e-mail vindos do SSO). O git log por skill é um histórico auditável, não um campo de banco.

• Skill como repositório

  Uma aba Explorar abre cada skill em modo leitura como se fosse um repo: árvore de arquivos, SKILL.md renderizado, output_schema.json lado a lado com anexos, e histórico de commits daquela skill específica.

• Buddies

  Biblioteca de avatares que espelha o corpus de skills — cada buddy tem dez poses canônicas, versionadas em git separadamente, criáveis por um grupo dedicado do Authentik. O Marcolito, o assistente embutido do Balde, mora aí.

• API pra máquinas

  /api/v1 com autenticação Bearer devolve só as skills canônicas no formato Open Knowledge Format (OKF) — pronto pra virar contexto de qualquer agente ou pipeline downstream.

Como uma skill anda pela esteira

1. Novo rascunho

   Um modal guiado coleta título, descrição, tipo, tags, objetivo, e permite anexar output_schema.json ou arquivos de exemplo. Nasce como rascunho, versão 0.1.0, e um commit assinado por quem criou.

2. Rascunho

   O dono edita, adiciona fontes, ajusta o prompt, junta anexos. Cada salvamento é um commit. O painel mostra em vermelho os controles mínimos ainda pendentes.

3. Portão

   Quando o dono clica publicar, um validador determinístico (com fallback quando não há IA disponível) verifica os nove controles. Falhou algum, a resposta é 409 e a lista do que falta.

4. Canônica

   Aparece na /api/v1, entra em "Todas as skills", e pode ser puxada por qualquer consumidor autorizado. Rollback vira outro commit — o histórico nunca é reescrito.

Sob o capô

Servidor Node zero-dependência (~3 mil linhas em server.js, usando só http e fs nativos) + SPA em JavaScript vanilla. Corpus é uma pasta de arquivos com um repositório git dentro, montado como bind mount no container. Sem banco de dados. Autenticação por Authentik forward-auth (SSO + 2FA), papéis vindos de grupos (Colaborador, Curador, Buddy Author, Admin). Chat embutido (o Marcolito) usa protocolo de texto pra falar com o LLM — funciona com Claude Code, Codex ou API tradicional, sem SDK específico.

Companheiro natural do Vassoura: skills catalogadas no Balde consomem dados coletados pelo Vassoura via chave de API.