@semacode/cli 1.5.17 → 1.5.19

package/docs/integracao-com-ia.md

@@ -1,15 +1,25 @@
-# Integracao com IA
+# Integração com IA
 
-Sema foi feita para IA operar software vivo com menos adivinhacao.
+<!-- 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 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`
+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`
 
-Nao comece cavando codigo bruto quando a ferramenta ja consegue te dar contrato, score, lacuna e superficie viva.
+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
 
@@ -19,7 +29,7 @@ IA pequena:
 - `briefing.min.json`
 - `prompt-curto.txt`
 
-IA media:
+IA média:
 
 - `sema resumo --curto`
 - `drift.json`
@@ -34,44 +44,41 @@ IA grande:
 
 ## MCP
 
-Se o agente usa 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.
 
-```bash
-npm install -g @semacode/cli @semacode/mcp
-```
+Exemplo para clientes que aceitam MCP HTTP:
 
-Depois configure:
-
-```json
-{
-  "mcpServers": {
-    "sema": {
-      "command": "npx",
-      "args": ["-y", "@semacode/mcp"]
-    }
-  }
-}
+```toml
+[mcp_servers.sema]
+url = "https://sema.exemplo.com/mcp"
+bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
+tool_timeout_sec = 90
 ```
 
-Ferramentas mais uteis no fluxo de mudanca:
+Ferramentas mais úteis no fluxo de mudanca:
 
-- `sema_drift` para medir coerencia viva
+- `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 conclusao sem leitura documental comprovada
+- `sema_finalizar_mudanca` para bloquear conclusóo sem leitura documental comprovada
 
-As ferramentas MCP usam a CLI como backend operacional. Portanto, suporte de linguagem como Lua em `use`, `impl`, IR, `drift` e importacao fica disponivel no MCP quando `@semacode/cli` e `@semacode/mcp` estao na mesma linha publica.
+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
 
-Antes de editar ou executar operacao sensivel, declare a intencao:
+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 acao.
+Leia todos os itens em `leituraObrigatoria`. Se `docsAusentes` vier preenchido, crie ou complete os documentos antes da ação.
 
 Antes de concluir:
 
@@ -79,17 +86,19 @@ Antes de concluir:
 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.
+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 semantica
-- trate `drift` como juiz da adocao incremental
+- 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 adoção incremental
 - use `briefing.min.json` antes de abrir dezenas de arquivos
-- nao invente sintaxe fora da gramatica oficial
-- em persistencia, nao assuma que bancos diferentes tem o mesmo contrato operacional
+- 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 uteis no repo
+## Arquivos úteis no repo
 
 - `AGENTS.md`
 - `llms.txt`

package/docs/mcp.md

@@ -1,53 +1,292 @@
-# MCP
+# Private 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.
+## English
 
-## Fluxo obrigatorio para agentes
+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.
 
-Antes de uma acao operacional, a IA deve declarar a intencao e chamar:
+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.
 
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+## 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
 ```
 
-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.
+Para clientes legados que ainda pedem SSE:
 
-Antes de concluir, a IA deve comprovar leitura:
+```text
+https://sema.exemplo.com/sse
+```
 
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
+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
 ```
 
-Via MCP, use `sema_finalizar_mudanca`.
+Para ambientes sem suporte a bearer do cliente, use OAuth quando disponivel. OAuth nao deve reutilizar uma chave fixa de servidor.
 
-## Ferramentas de documentacao
+## IDE Local Vs App Remoto
 
-- `sema_docs_impacto`: resolve docs obrigatorias por intencao, arquivos alvo e categoria inferida.
-- `sema_finalizar_mudanca`: bloqueia conclusao sem docs lidas ou docs ausentes.
+O MCP só deve ler arquivos do ambiente onde ele roda.
 
-## Quando criar docs
+- 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 a intencao exige um runbook e ele nao existe, rode `sema_docs_impacto` com `criar_ausentes: true`. Exemplos:
+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.
 
-- 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`.
+Exemplo de drift remoto focado:
 
-O documento criado e um ponto de partida. A IA ainda deve preencher detalhes reais do projeto antes de executar a acao.
+```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.
 
-## Regra de conclusao
+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.
 
-Uma mudanca nao deve ser considerada concluida enquanto `sema_finalizar_mudanca` retornar diagnostico de severidade 4 ou maior. Isso inclui:
+`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.
 
-- documento obrigatorio ausente
-- leitura obrigatoria nao comprovada
-- runbook criado mas ainda nao revisado para a operacao real
+## 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
+```
 
-## Relacao com contratos
+Via MCP privado, use `sema_finalizar_mudanca`.
 
-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.
+## Relação Com Contratos
 
-O MCP acompanha a semantica entregue pela CLI. Quando a CLI aceita uma origem viva, como Lua em `use`, `impl`, IR, `drift` e `sema importar`, a ferramenta MCP correspondente passa a operar esse contrato desde que CLI e MCP estejam na mesma versao.
+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.

package/docs/pagamento-ponta-a-ponta.md

@@ -1,18 +1,28 @@
 # Pagamento Ponta a Ponta na Sema
 
-Este documento descreve o vertical oficial de pagamento da Sema no fluxo publico atual.
+<!-- 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.
 
-O objetivo nao e mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem ja consegue modelar um fluxo de negocio real com:
 
-- contrato publico
+Este documento descreve o vertical oficial de pagamento da Sema no fluxo público atual.
+
+O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
+
+- contrato público
+- segurança e autorizacao
+- classificacao de dados
+- segredos e proibicoes explicitas
 - regras
 - efeitos operacionais
+- execução, idempotencia, retry e compensacao
 - transicoes de estado
-- orquestracao
+- orquestração
 - erros publicos
-- testes executaveis
+- testes executaveis com saída, status ou erro observavel
 
-## Arquivos de referencia
+## Arquivos de referência
 
 - `exemplos/pagamento_dominio.sema`
 - `exemplos/pagamento.sema`
@@ -29,7 +39,7 @@ Centraliza os contratos compartilhados:
 
 ### `exemplos.pagamento`
 
-Centraliza a operacao do vertical:
+Centraliza a operação do vertical:
 
 - `task processar_pagamento`
 - `task confirmar_pagamento`
@@ -40,19 +50,19 @@ Centraliza a operacao do vertical:
 
 ## Narrativa do caso
 
-### Entrada publica
+### Entrada pública
 
-A operacao entra por:
+A operação entra por:
 
 - `route processar_pagamento_publico`
 
-Esse contrato publica:
+Esse contrato pública:
 
 - `pagamento_id`
 - `valor`
 - `token`
 
-E expoe:
+É expoe:
 
 - `pagamento`
 - `status`
@@ -62,13 +72,17 @@ E expoe:
 
 A `task processar_pagamento` faz o trabalho central:
 
+- exige `authz`
+- classifica `dados`
+- declara `segredos`, `audit` e `forbidden`
 - valida entrada
 - consulta o gateway
 - persiste o pagamento
 - emite evento
 - notifica comprovante
 - registra auditoria
-- garante consistencia da saida
+- declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
+- garante consistencia da saída
 
 ### Estado e transicoes
 
@@ -78,15 +92,15 @@ O `state ciclo_pagamento` ancora o contrato de transicao:
 - `AUTORIZADO -> PROCESSADO`
 - `PENDENTE -> RECUSADO`
 
-A `task` explicita quais transicoes ela realmente usa.
+A `task` explícita quais transicoes ela realmente usa.
 
-### Flow de orquestracao
+### Flow de orquestração
 
 O `flow orquestracao_pagamento` demonstra:
 
 - passagem de contexto
-- confirmacao em caso de sucesso
-- notificacao em caso de recusa
+- confirmação em caso de sucesso
+- notificação em caso de recusa
 - registro de timeout em caso de indisponibilidade
 - ramificacao por erro tipado
 
@@ -100,7 +114,7 @@ O vertical usa as 5 categorias oficiais da Sema:
 - `notificacao`
 - `auditoria`
 
-Tambem usa `criticidade` para deixar claro o peso operacional do efeito.
+Também usa `criticidade` para deixar claro o peso operacional do efeito.
 
 ### Falhas reais
 
@@ -114,9 +128,9 @@ O vertical cobre explicitamente:
 
 ### 1. Escrever ou ajustar os arquivos `.sema`
 
-Use o dominio compartilhado em um modulo e a operacao em outro modulo.
+Use o domínio compartilhado em um módulo e a operação em outro módulo.
 
-### 2. Aplicar o formato canonico
+### 2. Aplicar o formato canônico
 
 ```bash
 sema formatar exemplos
@@ -128,7 +142,7 @@ sema formatar exemplos
 sema validar exemplos/pagamento.sema
 ```
 
-### 4. Gerar codigo
+### 4. Gerar código
 
 ```bash
 sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
@@ -143,13 +157,15 @@ sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamen
 
 ## O que esse vertical prova
 
-Se esse vertical passa, a Sema ja consegue demonstrar que:
+Se esse vertical passa, a Sema já consegue demonstrar que:
 
-- modela contrato publico
+- modela contrato público
+- modela superficie sensível sem deixar segurança invisível
 - modela efeitos operacionais
 - modela falhas reais
-- modulariza dominio com `use`
+- modulariza domínio com `use`
+- declara idempotencia e execução crítica sem criar sintaxe nova
 - gera artefatos coerentes para TypeScript e Python
 - executa testes gerados sem gambiarra conceitual
 
-Esse e o criterio pratico que sustenta o uso publico do vertical de pagamento como referencia para IA e geracao.
+Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.

package/docs/persistencia-vendor-first.md

@@ -1,6 +1,12 @@
-# Persistencia Vendor-First
+# Persistência Vendor-First
 
-Sema 1.5.7 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, no IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` tambem materializa persistencia local real em `Preferences`, `localStorage` e `sessionStorage` quando a task esta ancorada no arquivo que usa essas APIs.
+<!-- 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 1.5.19 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
 
 ## Engines publicas
 
@@ -128,17 +134,17 @@ Cada recurso recebe compatibilidade por engine:
 - `parcial`
 - `invalido`
 
-Isso deixa explicito quando o contrato esta pedindo portabilidade falsa, por exemplo:
+Isso deixa explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
 
 - `table` em `redis`
 - `foreign_keys` em engine sem suporte equivalente
-- transacao multi-documento tratada como universal
+- transação multi-documento tratada como universal
 
 ## Onde isso aparece
 
 - parser e AST
 - IR canonica
-- analisador semantico
+- analisador semântico
 - formatador
 - `sema drift`
 - `sema importar`