docs/installation-contract.pt-BR.md
Rama main · réplica de lectura del repositorio original.
# Contrato de instalação
Status: **decisão normativa do projeto**.
Este documento delimita os procedimentos temporários de desenvolvimento/validação e a experiência de instalação oferecida ao usuário. A implementação, os testes, os READMEs, os tutoriais e a revisão de release precisam respeitar este contrato.
Versão em inglês: [Installation contract](installation-contract.md).
## Experiência de instalação suportada
A instalação é:
- iniciada e acompanhada pelo terminal;
- baseada em Docker Compose;
- executada por comandos e scripts transparentes, passíveis de inspeção;
- reproduzível na VPS do próprio operador;
- utilizável sem assistência dos desenvolvedores do projeto;
- *native-first*: usa mecanismos oficiais, Docker, MCP e OAuth/OIDC padronizados antes de adaptações próprias.
O operador instala e administra o pacote diretamente na VPS. O ChatGPT só é conectado depois que a instalação local e a autenticação pública estão prontas.
## Segredos e acesso remoto
Os tutoriais **nunca** exigem a entrega dos seguintes dados à IA ou à equipe do projeto:
- senha da VPS;
- chave SSH privada;
- acesso SSH ou administrativo remoto irrestrito;
- credenciais de root;
- credenciais administrativas do provedor da nuvem;
- saídas de terminal que contenham segredos;
- qualquer outro segredo que não seja estritamente necessário ao serviço.
Os segredos indispensáveis à operação são informados **localmente na VPS** ou na interface/API nativa do serviço correspondente. Exemplo: a senha da identidade OAuth dedicada é digitada no configurador local e utilizada posteriormente na tela de login do provedor de identidade, sem passar por mensagens do chat.
Durante o desenvolvimento, um agente sem acesso à máquina pode excepcionalmente pedir que o operador execute diagnósticos e compartilhe resultados previamente sanitizados. Isso é uma limitação da sessão de desenvolvimento, **não é requisito do produto** e não deve entrar no tutorial de instalação.
## Responsabilidade da automação
Quando uma etapa determinística pode ser automatizada com segurança, o pacote deve executá-la. Conforme aplicável, isso inclui:
- detecção de dependências e mensagens com correções práticas;
- análise das portas disponíveis e do proxy de borda;
- validação do Docker Compose;
- inicialização e checagem de saúde dos contêineres;
- configuração e validação de HTTPS;
- inicialização e descoberta OAuth/OIDC;
- checagem do endpoint MCP;
- testes de autenticação que falham de maneira segura (*fail closed*);
- diagnósticos com remoção de dados sensíveis;
- orientação de recuperação quando o software não pode escolher pelo operador.
Comandos investigativos usados uma única vez durante desenvolvimento não viram etapas obrigatórias de instalação.
## Ações manuais deliberadas
Uma ação manual é aceitável somente quando a plataforma exige decisão do operador ou interação com navegador/interface. Para cada ação, a documentação explica:
1. exatamente o que fazer;
2. por que a automação não pode tomar essa decisão com segurança;
3. como confirmar o resultado.
Exemplos: escolher o teto físico do filesystem, apontar DNS quando o instalador não controla o provedor, informar localmente a senha da conta OAuth dedicada e cadastrar o servidor MCP no ChatGPT Web.
## Critério de conclusão
Contêineres iniciados e verificação local são etapas intermediárias, **não** a conclusão.
~~~text
VPS configurada
-> MCP público com HTTPS válido
-> autenticação OAuth/OIDC funcionando
-> conexão no ChatGPT Web configurada
-> chamada MCP real feita pelo ChatGPT
-> sujeito/política/auditoria confirmados
-> INSTALLATION COMPLETE
~~~
O script `scripts/connect-chatgpt.sh` integra a jornada oficial. O processo só se encerra como concluído quando o Broker registra a chamada autenticada esperada e a cadeia de auditoria permanece válida.
Uma conexão somente de leitura pode servir para diagnóstico, mas não comprova uma instalação com ferramentas de escrita quando esse for o objetivo.
## Procedimentos exclusivos de desenvolvimento
Estes procedimentos pertencem à engenharia e ao aceite, salvo promoção explícita para uma funcionalidade pública segura:
- pedir ao proprietário que execute comandos investigativos e cole diagnósticos;
- probes temporários do GitHub Actions;
- runners autogerenciados específicos do projeto;
- máquinas efêmeras de CI;
- hostnames e IPs de VPS de desenvolvimento, caminhos de checkout e nomes de branch;
- ramificações temporárias de implementação;
- comandos avulsos curl/openssl usados apenas para depurar falhas;
- acesso SSH por desenvolvedores ou manutenção remota improvisada.
Essas informações pertencem aos registros de issues/PRs e às notas técnicas de desenvolvimento, não aos READMEs, tutoriais, site público ou fluxo suportado de conexão ao ChatGPT.
## Revisão final antes de release
Antes de declarar um candidato pronto:
1. revisar `README.md` e `README.pt-BR.md`;
2. revisar `docs/installer-flow.md` / `docs/installer-flow.pt-BR.md` e os guias de integração do ChatGPT;
3. conferir as páginas públicas EN/PT-BR;
4. retirar hostnames, IPs, nomes de branches e diagnósticos temporários da experiência de instalação;
5. verificar que não há instruções de compartilhamento de senhas VPS ou chaves privadas;
6. explicar motivo e validação de cada ação manual indispensável;
7. executar `python3 scripts/check-installation-contract.py` na CI;
8. realizar a instalação integral em uma VPS limpa e suportada;
9. finalizar com chamada MCP real no ChatGPT Web, sujeito autorizado e prova na auditoria do Broker.
## Regra de engenharia
**NATIVE FIRST.** Priorizar APIs oficiais, configuração suportada, Docker/Compose, MCP, OAuth/OIDC e mecanismos nativos. Código próprio só quando não houver caminho nativo suficiente, mantendo-o mínimo, centralizado, documentado e reversível.
## Estado de aprovação de clientes
O uso de MCP Apps/elicitation depende de recursos anunciados e efetivamente testados pelo cliente. Nunca presumir que uma janela integrada autentica o proprietário. A autoridade pertence ao Broker. Integrações HTTPS/CLI/SSH são alternativas operacionais quando realmente presentes e configuradas no runtime utilizado. Não anunciar instalação estável nem validação móvel antes do aceite específico.
**Versão em inglês:** [Installation contract](installation-contract.md).