@semacode/cli 1.5.28 → 1.5.29

package/docs/mcp.md

@@ -1,292 +1,292 @@
-# 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.
+# 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.