Tornar instalação pública reproduzível e configurar instâncias com clareza

.env.example

@@ -1,12 +1,73 @@
-# Identidade padrão do SHOGUN
+# SHOGUN — configuração privada da instância
+#
+# Os instaladores copiam este arquivo para .env.local quando ele não existe.
+# O núcleo do bot não exige chave de API para iniciar. Preencha somente as
+# integrações que você realmente utilizar. Nunca versione .env.local.
+
+# Identidade visual padrão do produto. O dono principal é configurado por
+# `npm run setup` e fica em dados/src/config.json, não neste arquivo.
 BOT_NAME=𝖘𝖍𝖔𝖌𝖚𝖓
 DEFAULT_PERSONA=shogun
 
 # Recomendado para Termux e aparelhos com pouca memória.
 SHOGUN_LOW_MEMORY=false
 
-# Controles seguros do módulo de downloads.
+# ---------------------------------------------------------------------------
+# BunnyFy — opcional
+# ---------------------------------------------------------------------------
+# false = o bot usa caminhos locais/legados quando disponíveis.
+# true  = habilita as capacidades BunnyFy configuradas abaixo.
+BUNNYFY_ENABLED=false
+BUNNYFY_BASE_URL=
+BUNNYFY_API_TOKEN=
+BUNNYFY_ALLOW_INSECURE_HTTP=false
+BUNNYFY_ACCOUNT_URL=
+BUNNYFY_CAPABILITY_TIMEOUT_MS=120000
+
+# Modos: off | primary | exclusive
+# off       = não usa BunnyFy nessa capacidade
+# primary   = tenta BunnyFy e usa fallback quando o contrato permitir
+# exclusive = usa BunnyFy sem fallback legado
+BUNNYFY_AI_MODE=off
+BUNNYFY_AI_TIMEOUT_MS=120000
 BUNNYFY_YOUTUBE_MODE=off
 BUNNYFY_YOUTUBE_TIMEOUT_MS=190000
 BUNNYFY_YOUTUBE_MAX_BYTES=52428800
 BUNNYFY_YOUTUBE_MAX_CONCURRENCY=4
+BUNNYFY_TRANSCRIPTION_MODE=off
+BUNNYFY_FACEBOOK_MODE=off
+BUNNYFY_PINTEREST_MODE=off
+BUNNYFY_TIKTOK_MODE=off
+BUNNYFY_KWAI_MODE=off
+BUNNYFY_IMAGES_MODE=off
+BUNNYFY_STICKERS_MODE=off
+BUNNYFY_CANVAS_MODE=off
+BUNNYFY_LOGOS_MODE=off
+BUNNYFY_GAMES_MODE=off
+BUNNYFY_IMAGE_GEN_MODE=off
+BUNNYFY_TAVERN_RENDER_MODE=off
+BUNNYFY_NEXO_RENDER_MODE=off
+
+# ---------------------------------------------------------------------------
+# IA direta NVIDIA — opcional
+# ---------------------------------------------------------------------------
+# Necessária somente quando a assistente usar NVIDIA diretamente:
+# - BUNNYFY_AI_MODE=off; ou
+# - BUNNYFY_AI_MODE=primary e você quiser fallback direto.
+# Em BUNNYFY_AI_MODE=exclusive, a credencial do provider pertence à BunnyFy.
+NVIDIA_API_KEY=
+
+# ---------------------------------------------------------------------------
+# Transcrição VEX legada — opcional
+# ---------------------------------------------------------------------------
+# Preencha apenas se sua instalação usar o fallback legado de transcrição.
+VEX_API_KEY=
+VEX_SITE=
+
+# ---------------------------------------------------------------------------
+# Upload GitHub legado — opcional
+# ---------------------------------------------------------------------------
+# Não é requisito geral do SHOGUN. Use apenas nos fluxos que ainda dependam
+# desse mecanismo e crie um token dedicado com o menor escopo possível.
+UPLOAD_GITHUB_TOKEN=
+UPLOAD_GITHUB_REPO=

.github/workflows/shogun-validate.yml

@@ -33,6 +33,8 @@ jobs:
         run: npm ci --no-audit --no-fund
       - name: Inspecionar plataforma
         run: npm run preflight
+      - name: Validar contrato de configuração pública
+        run: node scripts/validate-instance-config-contract.mjs
       - name: Validar arquitetura modular
         run: |
           npm run typecheck:vnext
@@ -59,7 +61,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         node: ['20.19.0', '22', '24']
     steps:
       - name: Baixar o repositório
@@ -75,12 +77,55 @@ jobs:
         shell: bash
         run: |
           node --check scripts/preflight-platform.mjs
+          node --check scripts/validate-instance-config-contract.mjs
           node --check dados/src/.scripts/config.js
           node --check dados/src/.scripts/start.js
           node --check dados/src/.scripts/start-v9-fixed.js
           node --check dados/src/connect.js
           node --check dados/src/index.js
+          bash -n scripts/install-linux.sh
+          bash -n scripts/install-macos.sh
+          bash -n scripts/install-termux.sh
       - name: Conferir configuração neutra
         run: node -e "const c=require('./dados/src/config.example.json'); if(c.nomebot!=='SHOGUN'||c.numerodono!=='55DDDNUMERO') process.exit(1)"
       - name: Construir arquitetura modular
         run: npm run build:vnext
+
+  contrato-termux:
+    name: Contrato Termux/Android
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Baixar o repositório
+        uses: actions/checkout@v4
+      - name: Preparar Node.js mínimo suportado
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.19.0'
+          cache: npm
+      - name: Preparar FFmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+      - name: Instalar dependências como clone limpo
+        run: npm ci --no-audit --no-fund
+      - name: Validar script Android
+        run: |
+          bash -n scripts/install-termux.sh
+          grep -q 'nodejs-lts' scripts/install-termux.sh
+          grep -q 'ffmpeg' scripts/install-termux.sh
+          grep -q 'termux-tools' scripts/install-termux.sh
+          grep -q '.env.local' scripts/install-termux.sh
+      - name: Exercitar ramificação Termux do preflight
+        env:
+          TERMUX_VERSION: ci
+          PREFIX: /tmp/shogun-termux-prefix
+        run: |
+          mkdir -p "$PREFIX/bin"
+          touch "$PREFIX/bin/termux-wake-lock"
+          node scripts/preflight-platform.mjs
+      - name: Validar entradas do runtime
+        run: |
+          node --check dados/src/.scripts/start-v9-fixed.js
+          node --check dados/src/connect.js
+          node --check dados/src/index.js