@semacode/cli 1.5.18 → 1.5.25

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

@@ -1,181 +1,187 @@
-# Fluxo Pratico para IA Antes de Editar `.sema`
-
+# 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.
-
-O ponto central: Sema nao e texto para agradar humano. E contrato semantico IA-first. Humanos autorizam e revisam; a IA consome o contrato para decidir o proximo 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
-5. editar
-6. formatar
-7. validar
-8. verificar
-
-## Fluxo detalhado
-
-### Etapa 1. Ler contexto minimo
-
-Antes de tocar em qualquer arquivo, a IA deve ler:
-
-- [README.md](../README.md)
-- [integracao-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:
-
-- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
-
-### Etapa 2. Escolher a faixa de capacidade
-
-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 grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-### Etapa 3. Ler o modulo alvo e um exemplo parecido
-
-A IA deve identificar:
-
-- qual arquivo sera editado
-- qual modulo 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)
-
-### Etapa 4. Consultar AST e IR quando fizer sentido
-
-Antes de alterar, a IA deve executar:
-
-```bash
-sema resumo caminho/arquivo.sema --curto --para mudanca
-sema ast caminho/arquivo.sema --json
-sema ir caminho/arquivo.sema --json
-```
-
-Objetivo:
-
-- ver a forma sintatica quando a capacidade aguentar
-- ver a forma semantica resolvida quando a capacidade aguentar
-- evitar interpretar errado o contrato
-
-### Etapa 5. Editar o `.sema`
-
+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 módulo alvo
+4. consultar o menor artefato semântico suficiente
+5. editar
+6. formatar
+7. validar
+8. verificar
+
+## Fluxo detalhado
+
+### Etapa 1. Ler contexto mínimo
+
+Antes de tocar em qualquer arquivo, a IA deve ler:
+
+- [README.md](../README.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 também:
+
+- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
+
+### Etapa 2. Escolher a faixa de capacidade
+
+Antes de despejar contexto na IA, escolha o que ela aguenta:
+
+- IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.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 módulo alvo e um exemplo parecido
+
+A IA deve identificar:
+
+- qual arquivo sera editado
+- 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 pública e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
+
+### Etapa 4. Consultar AST e IR quando fizer sentido
+
+Antes de alterar, a IA deve executar:
+
+```bash
+sema resumo caminho/arquivo.sema --curto --para mudanca
+sema ast caminho/arquivo.sema --json
+sema ir caminho/arquivo.sema --json
+```
+
+Objetivo:
+
+- ver a forma sintatica 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 sensivel; `expect { sucesso: verdadeiro }` sozinho nao prova semantica operacional
-
-### Etapa 6. Formatar
-
-Depois da edicao:
-
-```bash
-sema formatar caminho/arquivo.sema
-sema formatar caminho/arquivo.sema --check
-```
-
-Se `--check` falhar, o trabalho ainda nao esta pronto.
-
-### Etapa 7. Validar e diagnosticar
-
-Depois da formatacao:
-
-```bash
-sema validar caminho/arquivo.sema --json
-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
-
-### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
-
-Se a tarefa nao for so editar contrato, mas tambem 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` 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
-
-### Etapa 8. Verificar
-
-No fechamento:
-
-```bash
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-## Fluxo minimo para automacao
-
-Se voce quiser o menor fluxo aceitavel para uma IA pequena:
-
-```bash
-sema resumo caminho/arquivo.sema --micro --para mudanca
-sema formatar caminho/arquivo.sema
-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:
-
-```bash
-sema ir caminho/arquivo.sema --json
-sema formatar caminho/arquivo.sema
-sema validar caminho/arquivo.sema --json
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-## Checklist de saida
-
-Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
-
-- eu entendi o modulo 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?
-
-Se alguma resposta for "nao", ainda nao terminou.
-
-## Regra de ouro
-
-Em Sema, a IA nao deveria operar no escuro.
-
-Ela deve trabalhar sempre com:
-
-- exemplo oficial
-- AST
-- IR
-- diagnosticos
-- formatador
-
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so 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.
+- evitar teste fraco em task sensível; `expect { sucesso: verdadeiro }` sozinho não prova semântica operacional
+
+### Etapa 6. Formatar
+
+Depois da edição:
+
+```bash
+sema formatar caminho/arquivo.sema
+sema formatar caminho/arquivo.sema --check
+```
+
+Se `--check` falhar, o trabalho ainda não está pronto.
+
+### Etapa 7. Validar e diagnosticar
+
+Depois da formatacao:
+
+```bash
+sema validar caminho/arquivo.sema --json
+sema diagnosticos caminho/arquivo.sema --json
+```
+
+Se houver falha:
+
+- 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 código derivado
+
+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` ou `dart`, conforme o caso.
+
+Regra pratica:
+
+- 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
+
+No fechamento:
+
+```bash
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
+```
+
+## Fluxo mínimo para automacao
+
+Se voce quiser o menor fluxo aceitavel para uma IA pequena:
+
+```bash
+sema resumo caminho/arquivo.sema --micro --para mudanca
+sema formatar caminho/arquivo.sema
+sema validar caminho/arquivo.sema --json
+```
+
+Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
+
+Se a tarefa envolver código derivado, o fluxo mínimo aceitavel vira:
+
+```bash
+sema ir caminho/arquivo.sema --json
+sema formatar caminho/arquivo.sema
+sema validar caminho/arquivo.sema --json
+sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
+```
+
+## Checklist de saída
+
+Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
+
+- 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 diagnósticos se algo falhou?
+- eu fechei com verificação?
+
+Se alguma resposta for "não", ainda não terminou.
+
+## Regra de ouro
+
+Em Sema, a IA não deveria operar no escuro.
+
+Ela deve trabalhar sempre com:
+
+- exemplo oficial
+- AST
+- IR
+- diagnósticos
+- formatador
+
+Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e não só no discurso bonito.
+
+## Observacao sobre caminhos
+
+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.25`.
+
+```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.25`.
+
+```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.25`.
+
+```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.25
 ```
 
-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.25.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