@semacode/cli 1.5.17 → 1.5.19

package/docs/documentacao.md

@@ -1,63 +1,88 @@
-# Governanca de Documentacao
+# Documentation Governance
 
-A Sema trata documentacao como parte da mudanca, nao como pos-escrito simpatico para alguem lembrar depois.
+## English
 
-## Regra principal
+Sema treats documentation as part of the change, not as a polite afterthought. Before an AI edits a contract, code, configuration, workflow, deploy, Author text, game rule, legal note, research note, or operational runbook, it must resolve the documentation that explains the intended change.
 
-Toda IA deve resolver documentacao obrigatoria antes de editar contrato, codigo, configuracao ou executar operacoes como deploy.
+Public documentation follows the exact order defined in [i18n.md](./i18n.md): English, Português, Español. Portuguese and Spanish must keep proper accents. Code blocks, identifiers, paths, command names, and `.sema` symbols are preserved unless a semantic rename contract says otherwise.
+
+### Operational Gate
 
 ```bash
 sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
 ```
 
-Se o comando apontar docs ausentes, crie ou preencha essas docs antes da acao. Para criar runbooks base:
+If the command reports missing docs, create or complete those docs before changing code, contracts, deploy, or configuration.
+
+### Required Reading
+
+The `docs-impacto` result returns:
+
+- `leituraObrigatoria`: docs, readmes, and contracts that must be read.
+- `docsAusentes`: docs that block the action.
+- `docsCriadas`: docs created automatically when authorized.
+- `bloqueios`: severity 4 diagnostics.
+
+Before declaring the work done, the agent must run:
 
 ```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
 ```
 
-## Leitura obrigatoria
+## Português
 
-O resultado de `docs-impacto` traz:
+A Sema trata documentação como parte da mudança, não como pós-escrito simpático para alguém lembrar depois. Antes de uma IA editar contrato, código, configuração, workflow, deploy, texto Author, regra de jogo, nota jurídica, pesquisa ou runbook operacional, ela precisa resolver a documentação que explica a intenção da mudança.
 
-- `leituraObrigatoria`: docs, readmes e contratos que devem ser lidos.
-- `docsAusentes`: docs que bloqueiam a acao.
-- `docsCriadas`: docs criadas automaticamente quando autorizado.
-- `bloqueios`: diagnosticos de severidade 4.
+A documentação pública segue a ordem exata definida em [i18n.md](./i18n.md): English, Português, Español. Português e espanhol precisam preservar acentos. Blocos de código, identificadores, caminhos, nomes de comando e símbolos `.sema` são preservados, exceto quando houver contrato de renomeação semântica.
 
-O conteudo dos documentos existentes vem na resposta para que o agente realmente leia o material antes de agir.
+### Gate Operacional
 
-## Finalizacao
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
 
-Antes de responder que terminou, a IA deve chamar:
+Se o comando apontar docs ausentes, crie ou complete essas docs antes de mudar código, contratos, deploy ou configuração.
+
+### Leitura Obrigatória
+
+O resultado de `docs-impacto` retorna:
+
+- `leituraObrigatoria`: docs, readmes e contratos que precisam ser lidos.
+- `docsAusentes`: docs que bloqueiam a ação.
+- `docsCriadas`: docs criadas automaticamente quando autorizado.
+- `bloqueios`: diagnósticos de severidade 4.
+
+Antes de dizer que o trabalho terminou, o agente precisa rodar:
 
 ```bash
-sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/api.md --json
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
 ```
 
-Se faltar leitura ou documentacao, a conclusao deve ser bloqueada.
+## Español
+
+Sema trata la documentación como parte del cambio, no como una nota amable para recordar después. Antes de que una IA edite contrato, código, configuración, workflow, deploy, texto Author, regla de juego, nota legal, investigación o runbook operativo, debe resolver la documentación que explica la intención del cambio.
 
-## Docs que podem nascer automaticamente
+La documentación pública sigue el orden exacto definido en [i18n.md](./i18n.md): English, Português, Español. Portugués y español deben conservar sus acentos. Bloques de código, identificadores, rutas, nombres de comando y símbolos `.sema` se preservan, excepto cuando exista un contrato de renombrado semántico.
 
-O Sema cria runbooks base para categorias operacionais:
+### Gate Operativo
 
-- `docs/deploy.md`
-- `docs/env.md`
-- `docs/rollback.md`
-- `docs/api.md`
-- `docs/auth.md`
-- `docs/seguranca.md`
-- `docs/database.md`
-- `docs/frontend.md`
-- `docs/testes.md`
-- `docs/mcp.md`
-- `docs/documentacao.md`
-- `docs/extensao-vscode.md`
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
 
-Esses arquivos sao esqueletos seguros. Eles devem ser completados com detalhes reais do projeto quando a operacao exigir.
+Si el comando informa docs ausentes, crea o completa esas docs antes de cambiar código, contratos, deploy o configuración.
 
-## O que nao fazer
+### Lectura Obligatoria
 
-- Nao concluir uma mudanca sem rodar o portao documental.
-- Nao usar doc criada automaticamente como evidencia final se ela ainda esta generica.
-- Nao editar codigo sem contrato e sem leitura das docs relacionadas.
+El resultado de `docs-impacto` devuelve:
+
+- `leituraObrigatoria`: docs, readmes y contratos que deben leerse.
+- `docsAusentes`: docs que bloquean la acción.
+- `docsCriadas`: docs creadas automáticamente cuando se autoriza.
+- `bloqueios`: diagnósticos de severidad 4.
+
+Antes de decir que el trabajo terminó, el agente debe ejecutar:
+
+```bash
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
+```

package/docs/env.md

@@ -1,6 +1,12 @@
 # Env
 
-Ambiente necessario para publicar a Sema.
+<!-- 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.
+
+
+Ambiente necessário para publicar a Sema.
 
 ## Ferramentas
 
@@ -10,23 +16,22 @@ Ambiente necessario para publicar a Sema.
 - VS Code CLI (`code`) para instalar a VSIX localmente.
 - PowerShell no Windows.
 
-## Variaveis suportadas pelos instaladores
+## Variaveis suportadas pelos instaladores publicos
 
-- `SEMA_REPO`: repositorio GitHub usado para baixar assets. Padrao: `gerlanss/Sema`.
-- `SEMA_NPM_PACKAGE`: pacote da CLI. Padrao: `@semacode/cli`.
-- `SEMA_MCP_NPM_PACKAGE`: pacote do MCP. Padrao: `@semacode/mcp`.
-- `SEMA_VERSION`: versao usada pelo `install-sema.sh`. Padrao: `latest`.
+- `SEMA_REPO`: repositório GitHub usado para baixar assets. Padrão: `gerlanss/Sema`.
+- `SEMA_NPM_PACKAGE`: pacote da CLI. Padrão: `@semacode/cli`.
+- `SEMA_VERSION`: versão usada pelo `install-sema.sh`. Padrão: `latest`.
 
-No PowerShell, o instalador recebe a versao por parametro:
+No PowerShell, o instalador recebe a versão por parametro:
 
 ```powershell
-.\install-sema.ps1 -Version 1.5.10 -WithVSCode -WithMcp
+.\install-sema.ps1 -Version 1.5.19 -WithVSCode
 ```
 
 No shell:
 
 ```bash
-SEMA_VERSION=1.5.10 ./install-sema.sh --with-vscode --with-mcp
+SEMA_VERSION=1.5.19 ./install-sema.sh --with-vscode
 ```
 
 ## Credenciais
@@ -37,20 +42,64 @@ SEMA_VERSION=1.5.10 ./install-sema.sh --with-vscode --with-mcp
 
 ## Registro NPM
 
-Os pacotes publicos sao:
+O pacote público é:
 
 - `@semacode/cli`
-- `@semacode/mcp`
 
 Antes de publicar, confira:
 
 ```bash
 npm view @semacode/cli version
-npm view @semacode/mcp version
+npm run release:verificar-versao
+```
+
+## Cliente MCP remoto
+
+Variaveis usadas por Codex, VS Code/forks e clientes que aceitam bearer:
+
+- `SEMA_MCP_AUTH_TOKEN`: chave comercial `sema_mcp_*` gerada no painel. E do cliente, nao do servidor.
+- `SEMA_MCP_ENDPOINT`: URL HTTPS `/mcp` usada por clientes que leem endpoint por variavel.
+
+No Windows, instale sem expor a chave em argumento:
+
+```powershell
+Get-Clipboard | sema mcp-instalar-chave --stdin --json
+```
+
+## Servidor MCP remoto privado
+
+Variaveis usadas pelo servidor MCP privado quando roda em modo HTTP:
+
+- `MCP_PORT`: porta HTTP. Quando ausente, o MCP roda em `stdio`.
+- `MCP_HOST`: host de bind. Padrão: `0.0.0.0`.
+- `SEMA_MCP_PUBLIC_BASE_URL`: URL pública HTTPS usada nos metadados OAuth do ChatGPT.
+- `SEMA_MCP_OAUTH_SECRET`: segredo usado para assinar access/refresh tokens OAuth.
+- `SEMA_MCP_OAUTH_PASSCODE`: passcode privado digitado no login OAuth do ChatGPT.
+- `SEMA_MCP_PROJECT_ROOTS`: raizes permitidas para projetos, separadas por `;`.
+- `SEMA_MCP_CORS_ORIGIN`: origem CORS permitida, `*` ou lista separada por `;`.
+
+Exemplo operacional privado:
+
+```bash
+MCP_PORT=3333 \
+SEMA_MCP_PUBLIC_BASE_URL="https://sema.exemplo.com" \
+SEMA_MCP_OAUTH_SECRET="segredo-longo-para-oauth" \
+SEMA_MCP_OAUTH_PASSCODE="passcode-privado-chatgpt" \
+SEMA_MCP_PROJECT_ROOTS="/srv/sema/projetos"
 ```
 
+Nunca publique `/mcp` ou `/sse` na internet sem chave comercial bearer por request ou OAuth configurado, raiz restrita e HTTPS no proxy. Nunca registre chaves `sema_mcp_*`, OAuth secret ou passcode em docs publicas, logs, release notes ou screenshots.
+
 ## GitHub Release
 
-O tag publico deve seguir `v<versao>`, por exemplo `v1.5.10`.
+O tag público deve seguir `v<versao>`, por exemplo `v1.5.19`.
+
+Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositório.
+
+Depois de publicar, rode:
+
+```bash
+npm run release:verificar-publica
+```
 
-Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositorio.
+Esse check cruza README/docs, manifestos, npm, GitHub Latest, assets publicados, CLI local e VSIX instalada quando o VS Code CLI está disponivel.

package/docs/extensao-vscode.md

@@ -1,5 +1,11 @@
 # Extensao VS Code
 
+<!-- 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.
+
+
 Runbook da extensao `Sema Language Tools`.
 
 ## Arquivos principais
@@ -35,11 +41,13 @@ code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --
 1. Abra um projeto com `.sema`.
 2. Confirme que o Language Server inicia sem crash.
 3. Rode `Sema: Diagnosticar CLI`.
-4. Rode `Sema: Sincronizar EntryPoints IA do Projeto`.
-5. Abra um `.sema` e confirme diagnosticos, highlight e formatação.
+4. Rode `Sema: Instalar Chave MCP`, cole uma chave `sema_mcp_*` do painel e confirme que a CLI grava a variavel do usuario sem argumento com segredo.
+5. Rode `Sema: Sincronizar EntryPoints IA do Projeto`.
+6. Abra um `.sema` e confirme diagnosticos, highlight e formatacao.
 
 ## Cuidados
 
 - O `extension.js` deve apontar o LSP para `server.js`.
-- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP quando novos comandos forem adicionados.
-- A versao da extensao deve bater com a versao publica preparada por `release:preparar-publica`.
+- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP privadas quando novos comandos remotos forem adicionados.
+- A chave MCP do painel deve ser instalada via comando da extensao ou `sema mcp-instalar-chave --stdin`; nao trate `SEMA_MCP_AUTH_TOKEN` como token fixo do servidor.
+- A versão da extensao deve bater com a versão pública preparada por `release:preparar-publica`.

package/docs/fluxo-pratico-ia-sema.md

@@ -1,15 +1,23 @@
 # Fluxo Pratico para IA Antes de Editar `.sema`
 
+<!-- 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.
+
+
 Este documento descreve o fluxo operacional recomendado para qualquer IA antes, durante e depois de alterar arquivos `.sema`.
 
-Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao gourmet.
+Se a IA seguir isso, ela trabalha com contexto. Se não seguir, vira adivinhação gourmet.
+
+O ponto central: Sema não é texto para agradar humano. É contrato semântico IA-first. Humanos autorizam e revisam; a IA consome o contrato para decidir o próximo movimento.
 
 ## Fluxo curto
 
 1. ler contexto do projeto
 2. identificar a capacidade da IA
-3. identificar o modulo alvo
-4. consultar o menor artefato semantico suficiente
+3. identificar o módulo alvo
+4. consultar o menor artefato semântico suficiente
 5. editar
 6. formatar
 7. validar
@@ -17,15 +25,15 @@ Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao
 
 ## Fluxo detalhado
 
-### Etapa 1. Ler contexto minimo
+### Etapa 1. Ler contexto mínimo
 
 Antes de tocar em qualquer arquivo, a IA deve ler:
 
 - [README.md](../README.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
 - [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
 
-Se o trabalho estiver ligado a pagamento, ler tambem:
+Se o trabalho estiver ligado a pagamento, ler também:
 
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
@@ -34,22 +42,22 @@ Se o trabalho estiver ligado a pagamento, ler tambem:
 Antes de despejar contexto na IA, escolha o que ela aguenta:
 
 - IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
-- IA media: `sema resumo --curto`, `briefing.min.json` e `drift.json`
+- IA média: `sema resumo --curto`, `briefing.min.json` e `drift.json`
 - IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
 
-### Etapa 3. Ler o modulo alvo e um exemplo parecido
+### Etapa 3. Ler o módulo alvo e um exemplo parecido
 
 A IA deve identificar:
 
 - qual arquivo sera editado
-- qual modulo esse arquivo representa
+- qual módulo esse arquivo representa
 - qual exemplo oficial mais se parece com o que precisa ser feito
 
 Regra pratica:
 
 - automacao: [automacao.sema](../exemplos/automacao.sema)
 - erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
-- borda publica e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
+- borda pública e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
 
 ### Etapa 4. Consultar AST e IR quando fizer sentido
 
@@ -64,28 +72,30 @@ sema ir caminho/arquivo.sema --json
 Objetivo:
 
 - ver a forma sintatica quando a capacidade aguentar
-- ver a forma semantica resolvida quando a capacidade aguentar
+- ver a forma semântica resolvida quando a capacidade aguentar
 - evitar interpretar errado o contrato
 
 ### Etapa 5. Editar o `.sema`
 
 Ao editar, a IA deve:
 
-- preservar a intencao do modulo
-- seguir a gramatica existente
-- evitar criar bloco ou operador nao suportado
-- preferir a forma ja usada nos exemplos oficiais
+- preservar a intenção do módulo
+- seguir a gramática existente
+- evitar criar bloco ou operador não suportado
+- preferir a forma já usada nos exemplos oficiais
+- usar blocos existentes como `auth`, `authz`, `dados`, `audit`, `forbidden`, `execucao`, `use`, `state` e `enum` antes de propor sintaxe nova
+- evitar teste fraco em task sensível; `expect { sucesso: verdadeiro }` sozinho não prova semântica operacional
 
 ### Etapa 6. Formatar
 
-Depois da edicao:
+Depois da edição:
 
 ```bash
 sema formatar caminho/arquivo.sema
 sema formatar caminho/arquivo.sema --check
 ```
 
-Se `--check` falhar, o trabalho ainda nao esta pronto.
+Se `--check` falhar, o trabalho ainda não está pronto.
 
 ### Etapa 7. Validar e diagnosticar
 
@@ -98,23 +108,23 @@ sema diagnosticos caminho/arquivo.sema --json
 
 Se houver falha:
 
-- usar os diagnosticos estruturados como contrato de correcao
-- nao insistir em leitura manual teimosa quando a CLI ja disse onde esta a merda
+- usar os diagnósticos estruturados como contrato de correcao
+- não insistir em leitura manual teimosa quando a CLI já disse onde está a merda
 
-### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
+### Etapa 7.5. Compilar quando a tarefa pedir código derivado
 
-Se a tarefa nao for so editar contrato, mas tambem gerar base de implementacao, a IA deve rodar explicitamente:
+Se a tarefa não for só editar contrato, mas também gerar base de implementacao, a IA deve rodar explicitamente:
 
 ```bash
 sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
 ```
 
-Ou trocar o alvo para `python`, `dart` ou `lua`, conforme o caso.
+Ou trocar o alvo para `python` ou `dart`, conforme o caso.
 
 Regra pratica:
 
-- se a entrega inclui codigo derivado, `sema compilar` nao e opcional
-- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema ja gera sozinha, que e burrice operacional
+- se a entrega inclui código derivado, `sema compilar` não é opcional
+- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema já gera sozinha, que é burrice operacional
 
 ### Etapa 8. Verificar
 
@@ -124,7 +134,7 @@ No fechamento:
 sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
 ```
 
-## Fluxo minimo para automacao
+## Fluxo mínimo para automacao
 
 Se voce quiser o menor fluxo aceitavel para uma IA pequena:
 
@@ -136,7 +146,7 @@ sema validar caminho/arquivo.sema --json
 
 Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
 
-Se a tarefa envolver codigo derivado, o fluxo minimo aceitavel vira:
+Se a tarefa envolver código derivado, o fluxo mínimo aceitavel vira:
 
 ```bash
 sema ir caminho/arquivo.sema --json
@@ -145,33 +155,33 @@ sema validar caminho/arquivo.sema --json
 sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
 ```
 
-## Checklist de saida
+## Checklist de saída
 
 Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
 
-- eu entendi o modulo e o contrato?
+- eu entendi o módulo e o contrato?
 - eu mantive a sintaxe dentro do que a linguagem suporta?
 - eu formatei o arquivo?
 - eu validei?
-- eu olhei diagnosticos se algo falhou?
-- eu fechei com verificacao?
+- eu olhei diagnósticos se algo falhou?
+- eu fechei com verificação?
 
-Se alguma resposta for "nao", ainda nao terminou.
+Se alguma resposta for "não", ainda não terminou.
 
 ## Regra de ouro
 
-Em Sema, a IA nao deveria operar no escuro.
+Em Sema, a IA não deveria operar no escuro.
 
 Ela deve trabalhar sempre com:
 
 - exemplo oficial
 - AST
 - IR
-- diagnosticos
+- diagnósticos
 - formatador
 
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so no discurso bonito.
+Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e não só no discurso bonito.
 
 ## Observacao sobre caminhos
 
-Esta documentacao usa placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.
+Está documentação usa placeholders de arquivo e pasta, não caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface pública principal.

package/docs/instalacao-e-primeiro-uso.md

@@ -1,16 +1,52 @@
-# Instalacao e Primeiro Uso
+# Installation And First Use
 
-Este guia cobre o caminho publico atual da Sema para CLI, MCP e extensao.
+## English
+
+This guide covers the current public installation path for the Sema CLI and VS Code extension. The remote MCP server is a private/commercial authorized service and is not distributed as a public npm package.
+
+Current public version: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+## Português
+
+Este guia cobre o caminho público atual da Sema para CLI e extensão VS Code. O servidor MCP remoto é um serviço privado/comercial autorizado e não é distribuído como pacote npm público.
+
+Versão pública atual: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+## Español
+
+Esta guía cubre el camino público actual de instalación para la CLI de Sema y la extensión de VS Code. El servidor MCP remoto es un servicio privado/comercial autorizado y no se distribuye como paquete público de npm.
+
+Versión pública actual: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+## Referência Operacional
 
 ## Requisitos
 
 - Node.js LTS
 - npm funcional
-- Python 3 so se voce quiser rodar testes Python gerados
+- Python 3 só se você quiser rodar testes Python gerados
 
 ## CLI
 
-Instalacao principal:
+Instalação principal:
 
 ```bash
 npm install -g @semacode/cli
@@ -19,13 +55,13 @@ sema doctor
 sema docs-impacto --intencao "alterar projeto" --json
 ```
 
-Instalacao por release:
+Instalação de uma versão específica pelo npm:
 
 ```bash
-npm install -g https://github.com/gerlanss/Sema/releases/latest/download/sema-cli-latest.tgz
+npm install -g @semacode/cli@1.5.19
 ```
 
-Instalacao local ao projeto:
+Instalação local ao projeto:
 
 ```bash
 npm install @semacode/cli
@@ -34,20 +70,7 @@ npx sema --help
 
 ## MCP
 
-Se voce usa cliente MCP:
-
-```bash
-npm install -g @semacode/mcp
-sema-mcp
-```
-
-Ou sem instalar:
-
-```bash
-npx -y @semacode/mcp
-```
-
-As ferramentas MCP incluem `sema_docs_impacto` e `sema_finalizar_mudanca` para obrigar agentes a ler e atualizar docs relacionadas antes de concluir alteracoes.
+O MCP da Sema não é mais instalado por npm público. Ele é uma superfície privada/comercial acessada por endpoint remoto, normalmente `https://<host>/mcp`, com OAuth ou bearer configurado fora deste repositório. Veja [mcp.md](./mcp.md).
 
 ## Instaladores oficiais
 
@@ -55,26 +78,25 @@ Linux ou macOS:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash
-curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash -s -- --with-vscode --with-mcp
 ```
 
 Windows PowerShell:
 
 ```powershell
 Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.ps1 -OutFile install-sema.ps1
-.\install-sema.ps1 -WithVSCode -WithMcp
+.\install-sema.ps1
 ```
 
-Se quiser uma tag especifica, troque `main` pela versao desejada.
+Se quiser uma tag específica, troque `main` pela versão desejada.
 
-## Extensao VS Code
+## Extensão VS Code
 
 ```bash
-curl -L -o sema-language-tools.vsix https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix
-code --install-extension ./sema-language-tools.vsix --force
+npm run extensao:empacotar
+code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.19.vsix --force
 ```
 
-Ou baixe a VSIX antes e instale localmente.
+Os assets versionados da VSIX devem ser anexados manualmente a GitHub Releases quando houver release pública com binários. Se `--with-vscode` for usado antes disso, o instalador mantém a CLI instalada e apenas pula a extensão.
 
 ## Primeiro teste
 
@@ -85,7 +107,7 @@ sema iniciar
 sema validar contratos/pedidos.sema --json
 ```
 
-## Primeiro fluxo util
+## Primeiro fluxo útil
 
 ```bash
 sema validar contratos/pedidos.sema --json
@@ -104,7 +126,7 @@ sema impacto contratos/pedidos.sema --alvo pedido_id --mudanca "trocar pedido_id
 sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto --json
 ```
 
-## Primeiro fluxo de persistencia vendor-first
+## Primeiro fluxo de persistência vendor-first
 
 ```bash
 sema validar contratos/sema/persistencia_vendor_first.sema --json