docs: release Swarm Doctrine v1.0.6 with centralized Gitea governance

Home.md

@@ -5,7 +5,8 @@ Bem-vindo ao Portal de Consciência de toda a nossa infraestrutura. Esta Wiki un
 ---
 
 ## 📇 1. Diretrizes Globais do Enxame (Doutrina)
-*   [📖 Doutrina Swarm - Versão v1.0.5 (Atual)](v1.0.5)
+*   [📖 Doutrina Swarm - Versão v1.0.6 (Atual)](v1.0.6)
+*   [📜 Doutrina Swarm - Versão v1.0.5 (Histórico)](v1.0.5)
 *   [📜 Doutrina Swarm - Versão v1.0.4 (Histórico)](v1.0.4)
 *   [📜 Doutrina Swarm - Versão v1.0.3 (Histórico)](v1.0.3)
 *   [📜 Doutrina Swarm - Versão v1.0.2 (Histórico)](v1.0.2)

v1.0.6.md

@@ -0,0 +1,138 @@
+# 🧠 Doutrina Mestre dos Agentes (Multi-VPS) - Versão v1.0.6 (Atual)
+
+> [!NOTE]
+> **Histórico de Atualização (Versão v1.0.6 - 17/05/2026)**:
+> *   **Governança Centralizada no Gitea**: Adicionado o novo pilar de governança unificada ao nível de Usuário e Sistema, mapeamento global de chaves SSH, listagem dos endereços SSH oficiais dos projetos e catalogação das features unificadas do Gitea (Organizations, PAT, Global Labels, System Webhooks).
+> *   **Versão v1.0.5 (17/05/2026)**: Hierarquia de Sincronização de Instruções com Injeção em RAM.
+> *   **Versão v1.0.4 (17/05/2026)**: Documentação do Loop de Auto-Cura e Tuning de PostgreSQL & DragonflyDB.
+> *   **Versão v1.0.3 (17/05/2026)**: Protocolo de Auto-Configuração de Novos Projetos.
+> *   **Versão v1.0.2 (17/05/2026)**: Micro-segmentação de Firewall (SecOps Hardening) na VPS 3.
+> *   **Versão v1.0.1 (17/05/2026)**: Hardening de terminal (.bash_logout) e carregamento dinâmico JIT via API REST do Gitea.
+> *   **Versão v1.0.0 (16/05/2026)**: Primeira versão consolidada e estruturada das diretrizes.
+
+---
+
+Este documento define a consciência situacional obrigatória para todos os agentes de IA.
+
+## 📍 Identificação de Localização
+Antes de qualquer ação, identifique seu IP interno:
+- **10.99.0.1 (VPS 1 - PRODUÇÃO)**: Ambiente CRÍTICO. Rodando Traefik e Nginx. 
+  - *Regra*: Apenas deploys homologados em Staging. Nunca mexa na infraestrutura de rede.
+- **10.99.0.3 (VPS 3 - CÉREBRO)**: Onde reside o Gitea, Postgres e DragonflyDB.
+  - *Regra*: Proteja os dados. Backups antes de qualquer alteração de schema.
+- **10.99.0.4 (VPS 4 - LABORATÓRIO)**: Desenvolvimento e Staging.
+  - *Regra*: Liberdade para testar, criar e quebrar containers. É o local de nascimento do código.
+
+## 🔐 Segurança e VPN
+- **Interface wg0**: É a sua linha de vida. Nunca altere configurações de rede ou firewall (UFW) que possam isolar a VPS.
+- **Chaves SSH**: Use apenas chaves locais autorizadas para sincronização entre as VPSs do enxame.
+
+## 📇 Protocolo de Identidade Estática (`~/.vps_identity`)
+Para garantir 100% de consciência situacional à prova de falhas sem depender de chamadas de rede externas, cada máquina do enxame possui um arquivo de identidade em `/home/deploy/.vps_identity`.
+
+### 📄 Estrutura Obrigatória do JSON:
+Todo arquivo `.vps_identity` deve conter exatamente a seguinte estrutura:
+```json
+{
+  "vps_id": 4,
+  "vps_name": "VPS-4-LABORATORIO",
+  "ip_vpn": "10.99.0.4",
+  "role": "Desenvolvimento, Builds e Staging",
+  "danger_level": "BAIXO - Liberdade para testar e recriar"
+}
+```
+
+### 🚨 Obrigações das IAs e Agentes:
+1. **Verificação Obrigatória**: Toda execução de script ou agente deve prioritariamente ler e interpretar o arquivo `/home/deploy/.vps_identity` para calibrar o seu escopo de atuação.
+2. **Respeito ao Danger Level (Nível de Perigo)**:
+   - **Nível de Perigo ALTO** (ex: VPS 1, VPS 3): Agentes **NÃO PODEM** rodar comandos experimentais, mutações não homologadas de bancos de dados ou reinstalar dependências críticas sem backups nítidos e aprovação explícita.
+   - **Nível de Perigo BAIXO** (ex: VPS 4): O agente possui total autonomia para realizar testes, compilar códigos, reinstalar pacotes e reiniciar contêineres Docker de staging.
+3. **Resiliência (Fallback)**: Caso o arquivo `.vps_identity` não exista ou esteja ilegível, o agente deve fazer o fallback dinâmico (buscando o IP `10.99.x.x` via `hostname -I`) e assumir o perfil de segurança mais restritivo por padrão.
+
+## 🚫 NUNCA...
+- Nunca tente acessar servidores fora da rede 10.99.0.x.
+- Nunca exponha senhas ou chaves privadas em logs ou comentários.
+- Nunca altere o serviço `swarm-listener` sem autorização.
+
+## 🔄 Protocolo de Criação e Configuração de Novos Projetos (Auto-Config de Webhook)
+
+Sempre que um novo projeto for criado no ecossistema Swarm, os agentes e desenvolvedores **devem** seguir e configurar automaticamente a seguinte rotina de integração de CI/CD para que o GitOps funcione perfeitamente:
+
+### 1. Criação Obrigatória do Webhook de Deploy
+Todo novo repositório criado no Gitea **DEVE** possuir um Webhook de deploy ativo configurado da seguinte forma:
+*   **URL de Destino**: `http://10.99.0.3:5000/webhook` (Se configurado externamente) ou `http://127.0.0.1:5000/webhook` (Se configurado de dentro da VPS 3).
+*   **Tipo de Conteúdo**: `application/json`
+*   **Segredo (Secret)**: Em branco ou chave secreta padrão.
+*   **Eventos que disparam**: Apenas o evento de **Push** (Commit enviado).
+
+> [!IMPORTANT]
+> **Autonomia do Agente (Auto-Identificação)**:
+> Se você (o Agente de IA) identificar que está trabalhando em um **novo projeto** ou que o repositório do projeto atual **não possui** o webhook do Swarm Dispatcher (`http://127.0.0.1:5000/webhook`) configurado no Gitea:
+> 1. Você **DEVE** usar a API REST do Gitea para criar ou corrigir esse webhook automaticamente.
+> 2. Você **DEVE** garantir a criação do arquivo `.vps_identity` apropriado nas VPSs correspondentes.
+> 3. Você **DEVE** estruturar o `docker-compose.yml` do projeto sob a pasta `/home/deploy/stack/<nome-do-projeto>/` seguindo o padrão rootless.
+
+## 🗣️ Comunicação
+- Todo o desenvolvimento, comentários e commits devem ser em **PORTUGUÊS**.
+- Use o protocolo **PGS (Protocolo Gitea Swarm)** para hand-offs.
+
+## 📂 Diretórios de Projetos e Stacks Ativos (Mapeamento de Preservação)
+
+### 🖥️ VPS 1 - Produção (10.99.0.1)
+Os seguintes diretórios são de infraestrutura e serviços críticos ativos e **DEVEM SER ESTRITAMENTE PRESERVADOS** contra qualquer alteração ou limpeza na VPS 1:
+*   📁 `/home/deploy/stack/traefik/`: Roteador de borda central e proxy reverso da infraestrutura.
+*   📁 `/home/deploy/stack/portainer/`: Interface de gerenciamento e monitoramento de contêineres Docker.
+*   📁 `/home/deploy/stack/soc/`: Rotinas de CrowdSec, firewall e auditoria de segurança ativa.
+
+### 🖥️ VPS 4 - Laboratório (10.99.0.4)
+Os seguintes diretórios dentro de `/home/deploy/stack/` contêm contêineres de desenvolvimento e staging ativos e **DEVEM SER ESTRITAMENTE PRESERVADOS** na VPS 4:
+*   📁 `scoreodonto.com/`: Aplicação e contêineres de staging do ecossistema ScoreOdonto.
+*   📁 `subdominio.clube67.com/`: Branding, front-end e back-end do Gerenciador de Subdomínios.
+*   📁 `self-healing/`: Rotinas e scripts locais de auto-recuperação de serviços.
+*   📁 `webhook-listener/`: Ouvinte de webhooks de GitOps (porta `9000`) para deploys automatizados.
+
+> [!WARNING]
+> Quaisquer pastas como `/home/deploy/stack/traefik/`, `/home/deploy/stack/portainer/` ou `/home/deploy/stack/soc/` que sejam encontradas na **VPS 4** são duplicatas inativas e obsoletas e **devem ser deletadas** na limpeza dos agentes.
+
+---
+
+## 🚀 Protocolo de Acesso a Contexto e Instruções (Prioridade de Memória Injetada)
+
+Para evitar vazamentos de credenciais no disco e garantir imunidade absoluta contra dados desatualizados locais, os agentes devem respeitar a seguinte ordem de prioridade de sincronização ao inicializar:
+
+1. 🚀 **Injeção em Memória RAM (API REST do Gitea - PRIORITÁRIO MÁXIMO)**:
+   Os agentes de IA devem prioritariamente ler as instruções mestre chamando a API de Conteúdos do Gitea usando Basic Auth. O conteúdo recuperado é decodificado base64 e mantido estritamente na memória volátil RAM da máquina durante a execução, sem tocar o disco da VPS.
+2. 📁 **Arquivos do Disco Local (Filesystem - CONTINGÊNCIA)**:
+   Caso a API do Gitea esteja temporariamente indisponível, a IA pode recorrer à leitura dos arquivos locais localizados em `/home/deploy/instrucoes/` como contingência secundária.
+3. 🔐 **Transporte Remoto e Escrita (Chaves SSH - ESTÁVEL)**:
+   Para operações de sincronização, deploys ou pushes do Git, os agentes devem usar exclusivamente a chave SSH do usuário `deploy` (`~/.ssh/id_ed25519`), prevenindo qualquer exposição de chaves privadas em logs ou variáveis de ambiente.
+
+---
+
+## 🌐 Governança e Integração Centralizada no Gitea (Nível de Usuário/Sistema)
+
+Para maximizar a segurança (SecOps), a agilidade de deploy (GitOps) e a escalabilidade do enxame de agentes, adotamos uma arquitetura de governança unificada no **Gitea no nível de Usuário e Sistema**, contornando configurações isoladas e repetitivas por repositório.
+
+### 🔑 1. Autenticação Unificada por Chave SSH Global (User Settings)
+Em vez de configurar Deploy Keys individuais para cada repositório, a chave pública SSH de cada VPS (nó do enxame) é cadastrada diretamente no perfil global do Usuário Administrador (`ruicesar`) em `/user/settings/keys`.
+*   **Permissão herdada**: Qualquer conexão Git disparada a partir dos nós do enxame possui automaticamente as permissões do usuário em todos os repositórios atuais e futuros.
+*   **Padrão de Endereços SSH dos Projetos ( VPS 4 & Swarm )**:
+    *   📁 **instrucoes_gerais**: `ssh://git@10.99.0.3/ruicesar/instrucoes_gerais.git`
+    *   📁 **scoreodonto.com**: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`
+    *   📁 **mercado.clube67.com**: `ssh://git@10.99.0.3/ruicesar/mercado.clube67.com.git`
+    *   📁 **subdominio.clube67.com**: `ssh://git@10.99.0.3/ruicesar/subdominio.clube67.com.git`
+
+### 🔌 2. Integração Global por Webhook do Sistema (System Webhook)
+Em vez de criar Webhooks de push repetitivos para cada repositório das aplicações:
+*   Configuramos um único **Webhook do Sistema** em `/admin/hooks` que atua de forma global em todos os repositórios (atuais e futuros).
+*   **Parâmetros de Produção**:
+    *   **URL de Destino**: `http://127.0.0.1:5000/webhook` (Disparo direto local em localhost na VPS 3 do Gitea).
+    *   **Content Type**: `application/json`
+    *   **Gatilho**: Apenas o evento de **Push**.
+*   **Filtragem**: O Swarm Dispatcher recebe os pushes globais e executa apenas os repositórios mapeados no fluxo de deploys do enxame, mantendo o processo 100% limpo e livre de redundâncias.
+
+### 🎯 3. Outros Recursos Unificados a Nível de Usuário/Sistema
+Para mantermos o ecossistema no estado da arte de DevOps, utilizamos os seguintes recursos globais do Gitea:
+*   📁 **Gitea Organizations (Organizações - ex: clube67)**: Agrupa todos os repositórios sob um único tenant corporativo, permitindo gerenciar permissões de equipes (Teams) e IAs de uma única vez para todos os projetos.
+*   🔑 **Personal Access Tokens (PAT - Nível de Usuário)**: Criação de um Token de Acesso único do usuário administrador injetado na RAM dos agentes, dando autorização de API para ler issues, wikis e logs de todos os repositórios atuais e futuros de forma centralizada.
+*   🏷️ **Rótulos Padrão (Global Labels)**: Padronização de etiquetas de Issues (ex: `bug-self-healing`, `deploy-staging`, `security-incident`) herdadas automaticamente por qualquer novo repositório, agilizando a triagem de erros.