@semacode/cli 1.5.18 → 1.5.25

package/docs/deploy.md

@@ -1,70 +1,258 @@
 # Deploy
 
-Este runbook governa a publicacao publica da Sema: CLI, MCP, VSIX, instaladores e release assets.
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
 
-## Pre-condicoes
+## EN
 
-- `sema resumo` executado no projeto antes da mudanca.
-- `sema inspecionar contratos/sema/governanca_ia.sema --json` executado para confirmar o contrato relacionado.
-- `sema drift contratos/sema/governanca_ia.sema --escopo modulo --json` sem diagnosticos bloqueantes.
-- `sema docs-impacto --intencao "<release>" --criar-ausentes --json` executado e todos os docs obrigatorios lidos.
-- `npm whoami` autenticado com uma conta que pode publicar `@semacode/cli` e `@semacode/mcp`.
-- `gh auth status` autenticado com permissao de push e release em `gerlanss/Sema`.
-- Workspace revisado para nao incluir lixo local, caches ou artefatos temporarios fora de `.tmp/`.
+This runbook covers two different deploy surfaces for Sema:
 
-## Sequencia segura
+- Sema public website and private MCP server at `https://sema.otimitare.online`.
+- Public package releases for CLI/VSIX/NPM/GitHub.
 
-1. Escolha uma versao que ainda nao exista no NPM.
-2. Atualize `package.json`, workspaces, lockfiles, changelog e docs antes de empacotar.
-3. Rode `npm run build`.
-4. Rode os testes focados e checagens de release.
-5. Rode `npm run release:preparar-publica` para gerar `.tmp/release-assets`.
-6. Publique NPM com `npm run release:publicar-npm`.
-7. Instale a CLI e o MCP publicados para smoke test.
-8. Empacote e instale a VSIX localmente para smoke test da extensao.
-9. Rode `sema finalizar-mudanca` com as docs lidas antes de concluir.
-10. Commit, push, tag e GitHub Release com os assets gerados.
+The production website/MCP target is the **Sema VPS**, not the OtimiTare application VPS.
 
-## Validacao minima
+### Sema Production VPS
+
+Operational facts:
+
+- Domain: `sema.otimitare.online`
+- Current public DNS target: resolve the domain before deploy, do not trust an old IP.
+- SSH user: use the operational server user configured outside this repository.
+- SSH identity: resolve it from local SSH config or a secret manager outside this repository.
+- Static site root: `/srv/sema/site`
+- Caddy config in this repo: `deploy/caddy/sema-site.Caddyfile`
+- MCP service: `sema-mcp.service`
+- MCP upstream: `127.0.0.1:3010`
+
+Do not use the stale `otimitare` SSH alias for Sema deploy. It points to an old host/key pair and is not the source of truth.
+
+Never commit private key content, private-key filenames, local key paths, IPs that are not already public DNS, or secret inventory details.
+
+### Website Deploy
+
+Before publishing:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirm the target:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Create a remote backup and publish static files:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Validate after deploy:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
+
+Expected result:
+
+- `/healthz` returns healthy.
+- `/painel.html` serves the current static panel.
+- `/mcp` without token does not expose data; it should return an auth challenge or unauthorized response.
+
+### Public Package Release
+
+Before publishing a CLI or VSIX release:
 
 ```bash
 npm run build
 npm run format:check
 npm run status:check
-node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia|mcp cli responde" testes/integracao/cli-json-e-editor.test.ts
+node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia" testes/integracao/cli-json-e-editor.test.ts
 sema validar contratos/sema/governanca_ia.sema --json
 sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
+npm run release:verificar-versao
 ```
 
-Depois de publicar:
+Then:
 
 ```bash
+npm run release:preparar-publica
+npm run release:publicar-npm
 npm view @semacode/cli version
-npm view @semacode/mcp version
 npm install -g @semacode/cli@<versao>
-npm install -g @semacode/mcp@<versao>
 sema --version
-sema docs-impacto --intencao "smoke release" --json
-sema-mcp --help
+npm run release:verificar-publica
 ```
 
-## Release assets
+Stop if NPM already has the version, `gh auth status` fails, `npm whoami` fails, Sema validation fails, or release verification finds a mismatch.
 
-`npm run release:preparar-publica` deve gerar:
+## PT
 
-- `sema-cli-<versao>.tgz`
-- `sema-cli-latest.tgz`
-- `sema-language-tools-<versao>.vsix`
-- `sema-language-tools-latest.vsix`
-- `install-sema.sh`
-- `install-sema.ps1`
-- `SHA256SUMS.txt`
-- `release-notes.md`
+Este runbook cobre duas superfícies diferentes de deploy da Sema:
+
+- site público e servidor MCP privado em `https://sema.otimitare.online`;
+- releases públicos de CLI/VSIX/NPM/GitHub.
+
+O alvo de produção do site/MCP é a **VPS da Sema**, não a VPS da aplicação OtimiTare.
+
+### VPS de Produção da Sema
+
+Fatos operacionais:
+
+- Domínio: `sema.otimitare.online`
+- DNS público atual: resolva o domínio antes do deploy; não confie em IP antigo.
+- Usuário SSH: use o usuário operacional do servidor configurado fora deste repositório.
+- Identidade SSH: resolva pelo SSH config local ou secret manager fora deste repositório.
+- Raiz do site estático: `/srv/sema/site`
+- Configuração Caddy neste repositório: `deploy/caddy/sema-site.Caddyfile`
+- Serviço MCP: `sema-mcp.service`
+- Upstream MCP: `127.0.0.1:3010`
+
+Não use o alias SSH antigo `otimitare` para deploy da Sema. Ele aponta para host/chave antigos e não é fonte da verdade.
+
+Nunca commite conteúdo de chave privada, nomes de arquivos de chave privada, caminhos locais de chave, IPs que não sejam DNS público ou detalhes do inventário de segredos.
+
+### Deploy do Site
+
+Antes de publicar:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirme o alvo:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Crie backup remoto e publique os arquivos estáticos:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Valide depois do deploy:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
+
+Resultado esperado:
+
+- `/healthz` responde saudável.
+- `/painel.html` serve o painel estático atual.
+- `/mcp` sem token não expõe dados; deve devolver desafio de autenticação ou não autorizado.
+
+### Release Público
+
+Antes de publicar CLI ou VSIX:
+
+```bash
+npm run build
+npm run format:check
+npm run status:check
+node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia" testes/integracao/cli-json-e-editor.test.ts
+sema validar contratos/sema/governanca_ia.sema --json
+sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
+npm run release:verificar-versao
+```
+
+Depois:
+
+```bash
+npm run release:preparar-publica
+npm run release:publicar-npm
+npm view @semacode/cli version
+npm install -g @semacode/cli@<versao>
+sema --version
+npm run release:verificar-publica
+```
+
+Pare se a versão já existir no NPM, `gh auth status` falhar, `npm whoami` falhar, a validação Sema falhar ou a verificação de release encontrar desalinhamento.
+
+## ES
+
+Este runbook cubre dos superficies distintas de despliegue de Sema:
+
+- sitio público y servidor MCP privado en `https://sema.otimitare.online`;
+- releases públicos de CLI/VSIX/NPM/GitHub.
+
+El destino de producción del sitio/MCP es la **VPS de Sema**, no la VPS de la aplicación OtimiTare.
+
+### VPS de Producción de Sema
+
+Datos operativos:
+
+- Dominio: `sema.otimitare.online`
+- DNS público actual: resuelve el dominio antes del despliegue; no confíes en una IP antigua.
+- Usuario SSH: usa el usuario operativo del servidor configurado fuera de este repositorio.
+- Identidad SSH: resuélvela desde el SSH config local o secret manager fuera de este repositorio.
+- Raíz del sitio estático: `/srv/sema/site`
+- Configuración Caddy en este repositorio: `deploy/caddy/sema-site.Caddyfile`
+- Servicio MCP: `sema-mcp.service`
+- Upstream MCP: `127.0.0.1:3010`
+
+No uses el alias SSH antiguo `otimitare` para desplegar Sema. Apunta a un host/par de llaves antiguo y no es la fuente de verdad.
+
+Nunca hagas commit del contenido de la llave privada, nombres de archivos de llave privada, rutas locales de llaves, IPs que no sean DNS público o detalles del inventario de secretos.
+
+### Despliegue del Sitio
+
+Antes de publicar:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirma el destino:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Crea backup remoto y publica los archivos estáticos:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Valida después del despliegue:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
 
-## Sinais de parada
+Resultado esperado:
 
-- NPM ja tem a versao escolhida.
-- `npm whoami` falha.
-- `gh auth status` falha.
-- `sema validar`, `sema drift`, build ou testes falham.
-- `release:preparar-publica` encontra versoes desalinhadas entre root, CLI, MCP e extensao.
+- `/healthz` responde saludable.
+- `/painel.html` sirve el panel estático actual.
+- `/mcp` sin token no expone datos; debe devolver desafío de autenticación o no autorizado.

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,56 +1,105 @@
-# Env
-
-Ambiente necessario para publicar a Sema.
-
-## Ferramentas
-
-- Node.js LTS com `npm`.
-- Git com acesso push ao remoto `origin`.
-- GitHub CLI (`gh`) autenticado.
-- VS Code CLI (`code`) para instalar a VSIX localmente.
-- PowerShell no Windows.
-
-## Variaveis suportadas pelos instaladores
-
-- `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`.
-
-No PowerShell, o instalador recebe a versao por parametro:
-
-```powershell
-.\install-sema.ps1 -Version 1.5.18 -WithVSCode -WithMcp
-```
-
-No shell:
-
-```bash
-SEMA_VERSION=1.5.18 ./install-sema.sh --with-vscode --with-mcp
-```
-
-## Credenciais
-
-- NPM deve estar logado antes de publicar: `npm whoami`.
-- GitHub CLI deve estar logado antes de criar release: `gh auth status`.
-- Nunca registre tokens em docs, logs ou release notes.
-
-## Registro NPM
-
-Os pacotes publicos sao:
-
-- `@semacode/cli`
-- `@semacode/mcp`
-
-Antes de publicar, confira:
-
-```bash
-npm view @semacode/cli version
-npm view @semacode/mcp version
-```
-
-## GitHub Release
-
-O tag publico deve seguir `v<versao>`, por exemplo `v1.5.18`.
-
-Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositorio.
+# Env
+
+<!-- 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
+
+- Node.js LTS com `npm`.
+- Git com acesso push ao remoto `origin`.
+- GitHub CLI (`gh`) autenticado.
+- VS Code CLI (`code`) para instalar a VSIX localmente.
+- PowerShell no Windows.
+
+## Variaveis suportadas pelos instaladores publicos
+
+- `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 versão por parametro:
+
+```powershell
+.\install-sema.ps1 -Version 1.5.25 -WithVSCode
+```
+
+No shell:
+
+```bash
+SEMA_VERSION=1.5.25 ./install-sema.sh --with-vscode
+```
+
+## Credenciais
+
+- NPM deve estar logado antes de publicar: `npm whoami`.
+- GitHub CLI deve estar logado antes de criar release: `gh auth status`.
+- Nunca registre tokens em docs, logs ou release notes.
+
+## Registro NPM
+
+O pacote público é:
+
+- `@semacode/cli`
+
+Antes de publicar, confira:
+
+```bash
+npm view @semacode/cli 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 público deve seguir `v<versao>`, por exemplo `v1.5.25`.
+
+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
+```
+
+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`.