@semacode/cli 1.5.28 → 1.5.29

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.28`.
-
-```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.28`.
-
-```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.28`.
-
-```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.28
-```
-
-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.28.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
+```

package/docs/integracao-com-ia.md

@@ -1,110 +1,110 @@
-# Integração com IA
-
-<!-- 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 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`
-
-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
-
-IA pequena:
-
-- `sema resumo --micro`
-- `briefing.min.json`
-- `prompt-curto.txt`
-
-IA média:
-
-- `sema resumo --curto`
-- `drift.json`
-- `briefing.min.json`
-
-IA grande:
-
-- `sema contexto-ia`
-- `briefing.json`
-- `ir.json`
-- `ast.json`
-
-## 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.
-
-Exemplo para clientes que aceitam MCP HTTP:
-
-```toml
-[mcp_servers.sema]
-url = "https://sema.exemplo.com/mcp"
-bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
-tool_timeout_sec = 90
-```
-
-Ferramentas mais úteis no fluxo de mudanca:
-
-- `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 conclusóo sem leitura documental comprovada
-
-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
-
-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 ação.
-
-Antes de concluir:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-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 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
-- 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 úteis no repo
-
-- `AGENTS.md`
-- `llms.txt`
-- `llms-full.txt`
-- `SEMA_BRIEF.md`
-- `SEMA_INDEX.json`
-- `docs/persistencia-vendor-first.md`
-- `docs/mcp.md`
-- `docs/documentacao.md`
+# Integração com IA
+
+<!-- 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 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`
+
+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
+
+IA pequena:
+
+- `sema resumo --micro`
+- `briefing.min.json`
+- `prompt-curto.txt`
+
+IA média:
+
+- `sema resumo --curto`
+- `drift.json`
+- `briefing.min.json`
+
+IA grande:
+
+- `sema contexto-ia`
+- `briefing.json`
+- `ir.json`
+- `ast.json`
+
+## 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.
+
+Exemplo para clientes que aceitam MCP HTTP:
+
+```toml
+[mcp_servers.sema]
+url = "https://sema.exemplo.com/mcp"
+bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
+tool_timeout_sec = 90
+```
+
+Ferramentas mais úteis no fluxo de mudanca:
+
+- `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 conclusóo sem leitura documental comprovada
+
+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
+
+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 ação.
+
+Antes de concluir:
+
+```bash
+sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
+```
+
+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 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
+- 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 úteis no repo
+
+- `AGENTS.md`
+- `llms.txt`
+- `llms-full.txt`
+- `SEMA_BRIEF.md`
+- `SEMA_INDEX.json`
+- `docs/persistencia-vendor-first.md`
+- `docs/mcp.md`
+- `docs/documentacao.md`