@semacode/cli 1.5.27 → 1.5.29

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

@@ -1,187 +1,187 @@
-# 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 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 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 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.
+# 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 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 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 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,134 +1,134 @@
-# Installation And First Use
-
-## 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.27`.
-
-```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.27`.
-
-```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.27`.
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-```
-
-## Referência Operacional
-
-## Requisitos
-
-- Node.js LTS
-- npm funcional
-- Python 3 só se você quiser rodar testes Python gerados
-
-## CLI
-
-Instalação principal:
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-sema docs-impacto --intencao "alterar projeto" --json
-```
-
-Instalação de uma versão específica pelo npm:
-
-```bash
-npm install -g @semacode/cli@1.5.27
-```
-
-Instalação local ao projeto:
-
-```bash
-npm install @semacode/cli
-npx sema --help
-```
-
-## MCP
-
-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
-
-Linux ou macOS:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash
-```
-
-Windows PowerShell:
-
-```powershell
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.ps1 -OutFile install-sema.ps1
-.\install-sema.ps1
-```
-
-Se quiser uma tag específica, troque `main` pela versão desejada.
-
-## Extensão VS Code
-
-```bash
-npm run extensao:empacotar
-code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.27.vsix --force
-```
-
-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
-
-```bash
-mkdir sema-demo
-cd sema-demo
-sema iniciar
-sema validar contratos/pedidos.sema --json
-```
-
-## Primeiro fluxo útil
-
-```bash
-sema validar contratos/pedidos.sema --json
-sema ir contratos/pedidos.sema --json
-sema formatar contratos/pedidos.sema
-sema verificar contratos --saida ./.tmp/verificacao
-```
-
-## Primeiro fluxo IA-first
-
-```bash
-sema inspecionar . --json
-sema resumo contratos/pedidos.sema --micro --para onboarding
-sema drift contratos/pedidos.sema --escopo modulo --json
-sema impacto contratos/pedidos.sema --alvo pedido_id --mudanca "trocar pedido_id por pedido_uuid" --json
-sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto --json
-```
-
-## Primeiro fluxo de persistência vendor-first
-
-```bash
-sema validar contratos/sema/persistencia_vendor_first.sema --json
-sema ir contratos/sema/persistencia_vendor_first.sema --json
-```
+# Installation And First Use
+
+## 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.29`.
+
+```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.29`.
+
+```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.29`.
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+## Referência Operacional
+
+## Requisitos
+
+- Node.js LTS
+- npm funcional
+- Python 3 só se você quiser rodar testes Python gerados
+
+## CLI
+
+Instalação principal:
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+sema docs-impacto --intencao "alterar projeto" --json
+```
+
+Instalação de uma versão específica pelo npm:
+
+```bash
+npm install -g @semacode/cli@1.5.29
+```
+
+Instalação local ao projeto:
+
+```bash
+npm install @semacode/cli
+npx sema --help
+```
+
+## MCP
+
+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
+
+Linux ou macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.ps1 -OutFile install-sema.ps1
+.\install-sema.ps1
+```
+
+Se quiser uma tag específica, troque `main` pela versão desejada.
+
+## Extensão VS Code
+
+```bash
+npm run extensao:empacotar
+code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.29.vsix --force
+```
+
+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
+
+```bash
+mkdir sema-demo
+cd sema-demo
+sema iniciar
+sema validar contratos/pedidos.sema --json
+```
+
+## Primeiro fluxo útil
+
+```bash
+sema validar contratos/pedidos.sema --json
+sema ir contratos/pedidos.sema --json
+sema formatar contratos/pedidos.sema
+sema verificar contratos --saida ./.tmp/verificacao
+```
+
+## Primeiro fluxo IA-first
+
+```bash
+sema inspecionar . --json
+sema resumo contratos/pedidos.sema --micro --para onboarding
+sema drift contratos/pedidos.sema --escopo modulo --json
+sema impacto contratos/pedidos.sema --alvo pedido_id --mudanca "trocar pedido_id por pedido_uuid" --json
+sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto --json
+```
+
+## Primeiro fluxo de persistência vendor-first
+
+```bash
+sema validar contratos/sema/persistencia_vendor_first.sema --json
+sema ir contratos/sema/persistencia_vendor_first.sema --json
+```