@semacode/cli 1.5.18 → 1.5.19

package/docs/integracao-com-ia.md

@@ -1,103 +1,110 @@
-# Integracao com IA
-
-Sema foi feita para IA operar software vivo com menos adivinhacao. O consumidor principal nao e o humano lendo arquivo bonito; e o agente decidindo o que pode tocar, que efeito vai causar e como validar antes de mexer no codigo vivo.
-
-Humanos entram como autores, revisores e aprovadores do contrato. A ponte da Sema e da intencao operacional para um formato que IA consegue consumir sem transformar contexto em chute.
-
-## Ordem recomendada
-
-1. `sema inspecionar . --json`
-2. `sema resumo <arquivo-ou-pasta> --micro --para onboarding`
-3. `sema drift <arquivo-ou-pasta> --json`
-4. `sema contexto-ia <arquivo.sema> --saida <diretorio> --json`
-
-Nao comece cavando codigo bruto quando a ferramenta ja consegue te dar contrato, score, lacuna e superficie viva.
-
-## Por capacidade do modelo
-
-IA pequena:
-
-- `sema resumo --micro`
-- `briefing.min.json`
-- `prompt-curto.txt`
-
-IA media:
-
-- `sema resumo --curto`
-- `drift.json`
-- `briefing.min.json`
-
-IA grande:
-
-- `sema contexto-ia`
-- `briefing.json`
-- `ir.json`
-- `ast.json`
-
-## MCP
-
-Se o agente usa MCP:
-
-```bash
-npm install -g @semacode/cli @semacode/mcp
-```
-
-Depois configure:
-
-```json
-{
-  "mcpServers": {
-    "sema": {
-      "command": "npx",
-      "args": ["-y", "@semacode/mcp"]
-    }
-  }
-}
-```
-
-Ferramentas mais uteis no fluxo de mudanca:
-
-- `sema_drift` para medir coerencia viva
-- `sema_impacto` para dizer o que tocar
-- `sema_renomear_semantico` para guiar troca de nomes sem misturar payload antigo e novo
-- `sema_docs_impacto` para obrigar leitura das docs relacionadas antes de agir
-- `sema_finalizar_mudanca` para bloquear conclusao sem leitura documental comprovada
-
-## Portao documental
-
-Antes de editar ou executar operacao sensivel, declare a intencao:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Leia todos os itens em `leituraObrigatoria`. Se `docsAusentes` vier preenchido, crie ou complete os documentos antes da acao.
-
-Antes de concluir:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Se houver diagnostico de severidade 4+, a IA nao deve finalizar a mudanca.
-
-## Regras praticas
-
-- trate `.sema` e IR como fonte de verdade semantica
+# Integração com IA
+
+<!-- sema:i18n -->
+> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
+
+
+Sema foi feita para IA operar software vivo com menos adivinhação. O consumidor principal não é o humano lendo arquivo bonito; e o agente decidindo o que pode tocar, que efeito vai causar e como validar antes de mexer no código vivo.
+
+Humanos entram como autores, revisores e aprovadores do contrato. A ponte da Sema e da intenção operacional para um formato que IA consegue consumir sem transformar contexto em chute.
+
+## Ordem recomendada
+
+1. `sema resumo <arquivo-ou-pasta> --micro --para onboarding`
+2. Liste ou leia os contratos existentes e inspecione o `.sema` mais próximo.
+3. Crie, edite ou remova o contrato aplicavel antes de qualquer ação.
+4. `sema validar <arquivo.sema> --json`
+5. `sema drift <arquivo-ou-pasta> --json`
+6. `sema contexto-ia <arquivo.sema> --saida <diretorio> --json`
+
+Não comece cavando código bruto quando a ferramenta já consegue te dar contrato, score, lacuna e superficie viva. Contrato primeiro vale para Software, Author, Workflow, Ops, Game, Legal, Research e qualquer profile futuro.
+
+## Por capacidade do modelo
+
+IA pequena:
+
+- `sema resumo --micro`
+- `briefing.min.json`
+- `prompt-curto.txt`
+
+IA média:
+
+- `sema resumo --curto`
+- `drift.json`
+- `briefing.min.json`
+
+IA grande:
+
+- `sema contexto-ia`
+- `briefing.json`
+- `ir.json`
+- `ast.json`
+
+## MCP
+
+Se o agente usa MCP, configure o endpoint remoto privado fornecido pelo operador do serviço. O MCP não é mais distribuido como pacote npm público neste GitHub. A variavel `SEMA_MCP_AUTH_TOKEN` no cliente deve conter uma chave comercial `sema_mcp_*` do painel, nao um token fixo do servidor.
+
+Exemplo para clientes que aceitam MCP HTTP:
+
+```toml
+[mcp_servers.sema]
+url = "https://sema.exemplo.com/mcp"
+bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
+tool_timeout_sec = 90
+```
+
+Ferramentas mais úteis no fluxo de mudanca:
+
+- `sema_resumo` para descobrir o estado do projeto
+- `sema_listar_contratos` e `sema_ler_contrato` quando a versão privada expuser a leitura direta dos contratos
+- `sema_inspecionar` para entender o contrato mais próximo
+- `sema_validar` para bloquear contrato inválido antes da ação
+- `sema_drift` para medir coerência viva
+- `sema_impacto` para dizer o que tocar
+- `sema_renomear_semantico` para guiar troca de nomes sem misturar payload antigo e novo
+- `sema_profile_validar` ou os gates Author para validar o profile especifico
+- `sema_docs_impacto` para obrigar leitura das docs relacionadas antes de agir
+- `sema_finalizar_mudanca` para bloquear conclusóo sem leitura documental comprovada
+
+O MCP deve repetir a regra sem ambiguidade: se não ha contrato, crie; se a intenção mudou, edite; se a capacidade saiu do sistema, remova ou aposente. Ação sem ciclo de contrato não é fluxo Sema.
+
+## Portao documental
+
+Depois de resolver e validar o contrato, declare a intenção documental:
+
+```bash
+sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+```
+
+Leia todos os itens em `leituraObrigatoria`. Se `docsAusentes` vier preenchido, crie ou complete os documentos antes da ação.
+
+Antes de concluir:
+
+```bash
+sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
+```
+
+Se houver diagnóstico de severidade 4+, a IA não deve finalizar a mudanca.
+
+## Regras praticas
+
+- trate `.sema` e IR como fonte de verdade semântica
 - trate humanos como donos/aprovadores e agentes como consumidores primarios do contrato
-- trate `drift` como juiz da adocao incremental
+- trate `drift` como juiz da adoção incremental
 - use `briefing.min.json` antes de abrir dezenas de arquivos
-- nao invente sintaxe fora da gramatica oficial
-- em task sensivel, teste que valida apenas `sucesso` e fraco; inclua output, erro esperado ou garantia observavel
-- em persistencia, nao assuma que bancos diferentes tem o mesmo contrato operacional
-
-## Arquivos uteis no repo
-
-- `AGENTS.md`
-- `llms.txt`
-- `llms-full.txt`
-- `SEMA_BRIEF.md`
-- `SEMA_INDEX.json`
-- `docs/persistencia-vendor-first.md`
-- `docs/mcp.md`
-- `docs/documentacao.md`
+- não invente sintaxe fora da gramática oficial
+- em task sensível, teste que valida apenas `sucesso` e fraco; inclua output, erro esperado ou garantia observavel
+- em persistência, não assuma que bancos diferentes tem o mesmo contrato operacional
+
+## Arquivos úteis no repo
+
+- `AGENTS.md`
+- `llms.txt`
+- `llms-full.txt`
+- `SEMA_BRIEF.md`
+- `SEMA_INDEX.json`
+- `docs/persistencia-vendor-first.md`
+- `docs/mcp.md`
+- `docs/documentacao.md`

package/docs/mcp.md

@@ -1,51 +1,292 @@
-# MCP
-
-O MCP da Sema e a porta de entrada para agentes que precisam obedecer contrato, ler contexto certo e fechar mudanca com verificacao rastreavel.
-
-## Fluxo obrigatorio para agentes
-
-Antes de uma acao operacional, a IA deve declarar a intencao e chamar:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Via MCP, use `sema_docs_impacto` com a mesma intencao. A resposta contem `leituraObrigatoria` com caminhos, motivos e conteudo dos documentos existentes. Se algum documento obrigatorio estiver ausente, o resultado vem com bloqueio de severidade 4.
-
-Antes de concluir, a IA deve comprovar leitura:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Via MCP, use `sema_finalizar_mudanca`.
-
-## Ferramentas de documentacao
-
-- `sema_docs_impacto`: resolve docs obrigatorias por intencao, arquivos alvo e categoria inferida.
-- `sema_finalizar_mudanca`: bloqueia conclusao sem docs lidas ou docs ausentes.
-
-## Quando criar docs
-
-Se a intencao exige um runbook e ele nao existe, rode `sema_docs_impacto` com `criar_ausentes: true`. Exemplos:
-
-- deploy: cria `docs/deploy.md`, `docs/env.md` e `docs/rollback.md`.
-- rota/API: cria `docs/api.md`.
-- auth: cria `docs/auth.md` e `docs/seguranca.md`.
-- banco: cria `docs/database.md`.
-- MCP: cria `docs/mcp.md`.
-- extensao: cria `docs/extensao-vscode.md`.
-
-O documento criado e um ponto de partida. A IA ainda deve preencher detalhes reais do projeto antes de executar a acao.
-
-## Regra de conclusao
-
-Uma mudanca nao deve ser considerada concluida enquanto `sema_finalizar_mudanca` retornar diagnostico de severidade 4 ou maior. Isso inclui:
-
-- documento obrigatorio ausente
-- leitura obrigatoria nao comprovada
-- runbook criado mas ainda nao revisado para a operacao real
-
-## Relacao com contratos
-
-Essas ferramentas nao substituem `sema_resumo`, `sema_inspecionar`, `sema_drift` ou `sema_validar`. Elas adicionam o portao documental: a IA descobre o que ler e o que documentar antes de agir.
+# Private MCP
+
+## English
+
+The Sema MCP is a private/commercial remote surface for agents that must obey contracts, read the right context, and close changes with traceable verification. It is not shipped in the public npm package and must not be documented as an open server package.
+
+Use OAuth for browser-based clients such as ChatGPT and Lovable when available. Use bearer keys only for clients that need that fallback. Fixed server tokens must not be the primary path for web apps.
+
+## Português
+
+O MCP da Sema é uma superfície remota privada/comercial para agentes que precisam obedecer contrato, ler contexto certo e fechar mudança com verificação rastreável. Ele não acompanha a release pública, não é publicado como pacote npm aberto e não deve ser documentado como pacote aberto de servidor.
+
+Use OAuth para clientes baseados em navegador, como ChatGPT e Lovable, quando disponível. Use chaves bearer apenas para clientes que precisam desse fallback. Tokens fixos de servidor não devem ser o caminho principal em apps web.
+
+## Español
+
+El MCP de Sema es una superficie remota privada/comercial para agentes que deben obedecer contratos, leer el contexto correcto y cerrar cambios con verificación trazable. No se distribuye en el paquete público de npm y no debe documentarse como paquete abierto de servidor.
+
+Usa OAuth para clientes basados en navegador, como ChatGPT y Lovable, cuando esté disponible. Usa claves bearer solo para clientes que necesitan ese fallback. Los tokens fijos de servidor no deben ser el camino principal en apps web.
+
+## Referência Operacional
+
+O repositório público documenta apenas o contrato de uso do serviço. A implementacao fica no pacote privado mantido fora deste monorepo.
+
+## Modelo de distribuição
+
+- Público: CLI, núcleo, geradores, contratos, exemplos, docs e extensao VS Code.
+- Privado: servidor MCP, OAuth, bearer, roots permitidas, deploy remoto, healthcheck e ferramentas remotas.
+- Consumo externo: ChatGPT, Codex, n8n, backends e outros agentes acessam um endpoint HTTPS `/mcp` operado por quem controla o serviço.
+
+Não use mais `npm install -g @semacode/mcp` nem `npx -y @semacode/mcp` em documentação pública. Esses caminhos eram validos enquanto o MCP era distribuido como pacote aberto; agora a integração correta e via URL remota autorizada.
+
+## Endpoint remoto
+
+Para ChatGPT Apps ou conectores baseados em MCP, a URL deve apontar para:
+
+```text
+https://sema.exemplo.com/mcp
+```
+
+Para clientes legados que ainda pedem SSE:
+
+```text
+https://sema.exemplo.com/sse
+```
+
+Endpoints esperados do serviço remoto:
+
+- `GET /healthz`: healthcheck sem segredo para proxy e deploy.
+- `GET /logo.png`: logo pública do servidor MCP.
+- `POST /mcp`: MCP Streamable HTTP.
+- `GET /mcp` e `DELETE /mcp`: continuidade/fechamento de sessão quando o cliente usa `mcp-session-id`.
+- `GET /sse` e `POST /message`: SSE legado.
+- `GET /.well-known/oauth-protected-resource`: metadata OAuth para recursos protegidos.
+- `GET /.well-known/oauth-authorization-server`: metadata do authorization server.
+- `POST /oauth/register`: dynamic client registration.
+- `GET|POST /oauth/authorize`: autorizacao com passcode.
+- `POST /oauth/token`: emissao e refresh de tokens.
+
+## ChatGPT
+
+No ChatGPT normal, em **Settings -> Apps & Connectors -> Advanced settings -> Create**:
+
+- Icone: PNG quadrado, mínimo `128x128`, maximo `10 KB`.
+- Nome: `Sema`.
+- Descricao: `Contrato semantico IA-first para agentes validarem, inspecionarem e operarem software vivo com drift, impacto e garantias.`
+- URL do servidor MCP: `https://sema.exemplo.com/mcp`.
+- Autenticação: `OAuth`.
+
+O ChatGPT abre a página de autorizacao do Sema, o operador digita o passcode privado e o servidor emite tokens proprios para o app. Nunca coloque bearer, OAuth secret ou passcode em README, AGENTS, release notes, prints ou logs.
+
+## Regra Zero Do MCP
+
+O MCP deve deixar claro, em toda orientacao operacional, que contrato vem antes da ação. Antes de código, deploy, geracao, revisão, texto Author, workflow, ops, game, legal, research ou qualquer outro profile, a IA precisa criar, editar ou remover o contrato `.sema` aplicavel.
+
+Se não existe contrato, a próxima ação e criar contrato. Se a intenção muda comportamento, a próxima ação e editar contrato. Se a funcionalidade deixa de existir, a próxima ação e remover ou aposentar o contrato. Só depois disso entram drift, impacto, código vivo, artefatos, deploy ou texto gerado.
+
+Essa regra vale para Software, Author, Workflow, Ops, Game, Legal, Research e qualquer profile futuro. Um MCP que permite agir sem ciclo de contrato virou autocomplete com cracha, não Sema.
+
+## Codex É Outros Agentes
+
+Para ambientes que aceitam MCP HTTP, configure o endpoint remoto e armazene a chave comercial `sema_mcp_*` no mecanismo de segredo do cliente. Essa chave identifica o workspace/projeto e alimenta o billing; ela nao e um token fixo global do servidor.
+
+No Windows, a CLI pode gravar a chave como variavel do usuario sem colocar o segredo em argumento de processo:
+
+```powershell
+Get-Clipboard | sema mcp-instalar-chave --stdin --json
+```
+
+No VS Code oficial, use o comando `Sema: Instalar Chave MCP` e cole a chave gerada no painel. A extensao chama a CLI por stdin, grava `SEMA_MCP_AUTH_TOKEN` no usuario e orienta reabrir o cliente.
+
+Exemplo de `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sema]
+url = "https://sema.exemplo.com/mcp"
+bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
+tool_timeout_sec = 90
+```
+
+Para ambientes sem suporte a bearer do cliente, use OAuth quando disponivel. OAuth nao deve reutilizar uma chave fixa de servidor.
+
+## IDE Local Vs App Remoto
+
+O MCP só deve ler arquivos do ambiente onde ele roda.
+
+- Em IDE/plugin com workspace local, o fluxo preferencial e enviar um snapshot tipado para `sema_contratos_sincronizar`: `contratos`, `arquivos_codigo`, `documentacao` e `indice`. Quando a tarefa precisar verificar implementacao, envie código selecionado, nunca o projeto inteiro.
+- Em ChatGPT/app remoto, o MCP roda no servidor e só enxerga roots do servidor, como `/srv/sema/projetos/...`. Caminho local de IDE não deve cair silenciosamente para outro projeto.
+- Toda chamada operacional deve enviar `projeto` com um caminho existente no servidor ou com o caminho retornado pelo espelho de contratos. Em HTTP remoto, `projeto` vazio ou `.` deve falhar com `workspace_atual_nao_informado`; cair em `/srv/sema/projetos/Sema` seria validar o repositório errado.
+- Quando o workspace não vier no contexto, a IA deve pedir ou usar a sincronizacao de contratos remotos e código selecionado. MCP local/stdio e opcional e deve ser reservado para drift contra código vivo completo.
+- Quando o arquivo veio de upload, anexo ou sandbox do chat, use `conteudo` inline.
+- Para `sema_drift`, `escopo = arquivo` ou `escopo = modulo` exige alvo explícito. Envie `arquivo` ou `contrato_alvo` com o `.sema` alvo dentro do `projeto`; se enviar apenas o diretorio do projeto, o MCP remoto deve retornar `contrato_alvo_nao_informado`. Use `escopo = projeto` somente quando a auditoria global for intencional.
+
+Se uma IA pedir `C:\GitHub\Gestech` para um MCP remoto Linux, o servidor deve responder erro claro de caminho local inacessivel e orientar sincronizar contratos e código selecionado com `sema_contratos_sincronizar`. MCP local/stdio só entra quando a tarefa exige ler código local completo.
+
+Exemplo de drift remoto focado:
+
+```json
+{
+  "projeto": "/srv/sema/projetos/_contratos_remotos/github-gestech-0e2eb48843",
+  "arquivo": "contratos/promocoes.sema",
+  "escopo": "modulo",
+  "json": true
+}
+```
+
+## Ferramentas Expostas
+
+A lista concreta depende da versão privada implantada, mas o contrato atual espera:
+
+- `sema_mcp_doctor`
+- `sema_resumo`
+- `sema_contratos_sincronizar`
+- `sema_contrato_salvar`
+- `sema_contrato_remover`
+- `sema_listar_contratos`
+- `sema_ler_contrato`
+- `sema_validar`
+- `sema_drift`
+- `sema_impacto`
+- `sema_renomear_semantico`
+- `sema_inspecionar`
+- `sema_ir`
+- `sema_verificar`
+- `sema_contexto_ia`
+- `sema_prompt_ia`
+- `sema_author_iniciar`
+- `sema_author_validar`
+- `sema_author_briefing`
+- `sema_author_revisar_cliches`
+- `sema_profile_validar`
+- `sema_sync_ai_entrypoints`
+- `sema_instalar_exemplos`
+- `sema_docs_impacto`
+- `sema_finalizar_mudanca`
+
+O doctor operacional do MCP privado fica no backlog do serviço comercial. Quando existir, ele deve retornar versão do MCP, versão da CLI, transporte, `cwd` do processo, `cwd` efetivo, raiz detectada, roots permitidas, endpoints e marcadores do projeto sem expor tokens, secrets ou passcodes.
+
+## Arquivos Enviados No ChatGPT
+
+O MCP remoto roda no servidor e não le caminhos do sandbox do ChatGPT como `/mnt/data/pedido.sema`. Para esses casos, ferramentas de contrato devem aceitar `conteudo` inline:
+
+```json
+{
+  "conteudo": "module exemplo { ... }",
+  "nome_arquivo": "pedido.sema"
+}
+```
+
+Use `conteudo` em `sema_validar`, `sema_ir`, `sema_inspecionar`, `sema_contexto_ia`, `sema_author_validar`, `sema_author_briefing` e `sema_author_revisar_cliches` quando o contrato vier de upload, anexo ou texto colado.
+
+Use `arquivo` apenas quando o caminho existir dentro das roots permitidas no servidor. Se uma IA enviar `/mnt/data/...`, o servidor deve orientar repetir a chamada usando `conteudo`.
+
+## Espelho De Contratos Da IDE
+
+Para IDEs e plugins, o MCP remoto não precisa ler o projeto inteiro para
+governar a mudanca. O cliente deve enviar um snapshot tipado:
+
+```json
+{
+  "projeto_id": "C:\\GitHub\\Gestech",
+  "nome_projeto": "Gestech",
+  "contratos": [
+    {
+      "caminho": "contratos/produtos_catalogo.sema",
+      "conteudo": "module ... { ... }"
+    }
+  ],
+  "arquivos_codigo": [
+    {
+      "caminho": "routes/produtos.py",
+      "conteudo": "def listar_produtos(...): ..."
+    },
+    {
+      "caminho": "tests/test_produtos.py",
+      "conteudo": "def test_listar_produtos(...): ..."
+    }
+  ],
+  "documentacao": [
+    {
+      "caminho": "AGENTS.md",
+      "tipo": "operacional",
+      "conteudo": "# Regras do projeto..."
+    },
+    {
+      "caminho": "docs/VPS_DEPLOY.md",
+      "tipo": "deploy",
+      "conteudo": "# Deploy..."
+    }
+  ],
+  "indice": [
+    {
+      "caminho": "routes/produtos.py",
+      "tipo": "codigo",
+      "hash": "sha256:...",
+      "mtime": "2026-05-16T12:00:00Z",
+      "resumo": "Rotas de produtos"
+    }
+  ]
+}
+```
+
+O servidor grava em uma pasta Linux dedicada contendo contratos, metadados
+mínimos e apenas os arquivos de código enviados. A resposta traz `projeto`;
+esse caminho deve ser usado nas proximas chamadas. Se o Sema criar, editar ou
+remover um contrato, a IDE deve trazer a alteracao de volta para o workspace
+local antes de qualquer código.
+
+O código enviado deve ser selecionado por criterio: arquivos citados em `impl`,
+`vinculos`, routes, effects, services/repos proximos e testes relacionados. O
+MCP deve bloquear `.env`, tokens, chaves, `node_modules`, `.git`, build/cache,
+uploads, dependências instaladas e snapshots de repo inteiro. Quando nenhum
+código for enviado, o Sema deve declarar `contratos_apenas` e trocar lacunas de
+implementacao por `implementacao_nao_enviada` ou
+`codigo_nao_verificado_neste_modo`. Quando código parcial for enviado, deve
+declarar `codigo_selecionado` e limitar a conclusóo ao snapshot.
+
+Documentação enviada deve ser operacional ou de negócio: `AGENTS.md`,
+`README.md`, docs do módulo mexido, notas de deploy quando a tarefa envolve
+VPS, runbooks em incidentes e exemplos Sema quando a IA estiver criando
+contrato. O índice deve conter mapa de arquivos relevantes, hashes, timestamps
+é resumo curto sem conteúdo sensível.
+
+Toda conclusóo precisa declarar sua fonte: `contrato`, `codigo`,
+`documentacao` ou `indice`. Exemplos de leitura: bloqueado pelo contrato;
+divergente do código; regra documentada mas sem contrato; documentação
+contradiz implementacao; escopo inferido pelo índice.
+
+`sema_author_revisar_cliches` opera como validador bloqueante: violacao de politica Author deve retornar `aprovado: false`, `bloqueado: true` e `sucesso: false`. Um contrato narrativo que não bloqueia drift, voz genérica ou tema sensível sem autorizacao não deve ser tratado como contrato.
+
+## Segurança Operacional
+
+O servidor privado deve rodar com:
+
+- HTTPS no reverse proxy.
+- Chave comercial bearer por request ou OAuth obrigatorio.
+- Passcode OAuth configurado para ChatGPT.
+- Roots restritas a uma pasta dedicada, por exemplo `/srv/sema/projetos`.
+- Logs sem tokens, passcodes, secrets ou conteúdo sensível desnecessário.
+- Rotacao imediata da chave comercial ou segredo OAuth se qualquer valor aparecer em terminal compartilhado, print, chat ou log.
+
+Nunca publique `/mcp` ou `/sse` sem autenticação e raiz restrita.
+
+## Fluxo Obrigatorio Para Agentes
+
+Antes de uma ação operacional, a IA deve declarar a intenção e resolver o contrato:
+
+1. `sema_resumo` para descobrir o estado do projeto.
+2. `sema_listar_contratos` e `sema_ler_contrato` quando disponiveis, ou `sema_inspecionar` no `.sema` mais próximo.
+3. Criar, editar ou remover o contrato aplicavel antes de tocar código, docs operacionais, deploy, texto Author, workflow, jogo, juridico, pesquisa ou ops.
+4. `sema_validar` no contrato alterado.
+5. `sema_drift`, `sema_impacto` ou gate de profile/Author conforme o tipo.
+
+Depois do ciclo de contrato, a IA deve chamar:
+
+```bash
+sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+```
+
+Via MCP privado, use `sema_docs_impacto` com a mesma intenção. A resposta contem `leituraObrigatoria` com caminhos, motivos e conteúdo dos documentos existentes.
+
+Antes de concluir:
+
+```bash
+sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
+```
+
+Via MCP privado, use `sema_finalizar_mudanca`.
+
+## Relação Com Contratos
+
+Essas ferramentas não substituem `sema_resumo`, `sema_inspecionar`, `sema_drift` ou `sema_validar`. Elas adicionam a camada remota privada para agentes fora da máquina local. O contrato continua sendo o portao: criar, editar ou remover contrato antes de qualquer ação e obrigatorio em todo tipo de Sema.