Princípios operacionais — knowledge-base

As regras de como esta base é operada. Moram aqui no repo (versionadas, portáveis) — não na memória de nenhuma ferramenta. Se a IA ou a infra mudarem, os princípios continuam de pé.

1. Fonte única da verdade

O repo é a referência canônica dos sistemas da Bepex. Quando a realidade de um sistema mudar, o doc correspondente muda junto — nunca deixamos a doc divergir do que está no ar.

2. Vendor-neutral / portável

O ativo é o conhecimento (Markdown puro), não a ferramenta que o lê. Nada de nome ou conteúdo acoplado a uma IA específica. Arquivos como CLAUDE.md, .claude/ e as skills são a camada adaptadora atual — substituíveis; não são o núcleo. Trocar de IA um dia = trocar essa camada, o conhecimento fica intacto.

3. Remote-first

O GitHub é a fonte da verdade (repo privado bepex-sys/knowledge-base), não o disco local. - Toda sessão começa com git pull. - Todo trabalho termina com add + commit + push automático (hook Stop): o que foi feito na sessão sobe pro GitHub sozinho, sem depender de commit manual. O gitleaks no pre-commit barra segredo antes de subir. - Se a máquina local sumir, nada de conhecimento se perde.

4. Anti-rot (documentar ao fim)

Tudo que for feito num sistema é documentado no padrão ao fim da mesma sessão de trabalho — quem faz é quem documenta, com contexto fresco, então o doc não apodrece. - Atualizar, não duplicar: mudou algo já documentado? Edite o doc existente; não crie arquivo novo.

5. Segredos e binários nunca no Git

• Segredos: só placeholders ${...} no repo; valores reais num arquivo restrito no Drive. .claude/settings.json bloqueia leitura de .env/secrets, e o hook .githooks/pre-commit (gitleaks) barra segredo antes de commitar.
• Binários (PDF, planilha, imagem, dataset, proposta): ficam fora do Git. Motivo real: o Git guarda toda versão de todo arquivo pra sempre, e binário passa de 1GB rápido, inchando o repo e o clone pra todo mundo. O .gitignore barra; cada anexo é referenciado no ARQUIVOS.md do projeto.

Como o binário fica salvo (Forma A): ele nasce na pasta do projeto no repo (lugar natural de escrita), fica fora do Git, e uma cópia mão-única vai pra uma pasta local knowledge-base-anexos/ (BEPEX_DRIVE_ROOT), irmã do repo e fora da árvore do Git, que o Google Drive Desktop acompanha. O Drive sincroniza essa pasta sozinho e de lá sai o link de compartilhamento. A cópia é feita pelo .claude/sync-anexos.sh, disparado no fim da sessão pelo hook Stop logo após o push. O repo nunca é sincronizado com o Drive: só os binários são copiados, e nunca levam o .git junto, pra não arriscar corromper o histórico do Git. Backup fica assim: doc no GitHub, binário no Drive. A duplicação local (mesmo binário no repo e na pasta de anexos) é aceita e se limpa com o tempo; nunca há sync de volta Drive para repo.

6. Autoria hoje: solo

Enquanto o time for só o dono + a IA, commit direto na main com mensagens limpas no padrão tipo(escopo): descrição. O fluxo de branch + Pull Request do CONTRIBUTING.md entra em vigor quando o time crescer — não antes.

7. Organização é definitiva

A árvore por disciplina (ver CLAUDE.md) não se reorganiza. Projetos novos entram na disciplina que servem, seguindo a anatomia de projeto padrão.