@semacode/cli 1.5.28 → 1.5.29

package/docs/extensao-vscode.md

@@ -1,53 +1,53 @@
-# 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
-
-- `pacotes/editor-vscode/package.json`
-- `pacotes/editor-vscode/extension.js`
-- `pacotes/editor-vscode/server.js`
-- `pacotes/editor-vscode/README.md`
-- `pacotes/editor-vscode/CHANGELOG.md`
-
-## Empacotar
-
-```bash
-npm run extensao:empacotar
-```
-
-O pacote versionado deve aparecer em `.tmp/editor-vscode/sema-language-tools-<versao>.vsix`.
-
-## Instalar localmente
-
-```bash
-npm run extensao:instalar-local
-```
-
-Ou:
-
-```bash
-code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --force
-```
-
-## Smoke test
-
-1. Abra um projeto com `.sema`.
-2. Confirme que o Language Server inicia sem crash.
-3. Rode `Sema: Diagnosticar CLI`.
-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 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`.
+# 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
+
+- `pacotes/editor-vscode/package.json`
+- `pacotes/editor-vscode/extension.js`
+- `pacotes/editor-vscode/server.js`
+- `pacotes/editor-vscode/README.md`
+- `pacotes/editor-vscode/CHANGELOG.md`
+
+## Empacotar
+
+```bash
+npm run extensao:empacotar
+```
+
+O pacote versionado deve aparecer em `.tmp/editor-vscode/sema-language-tools-<versao>.vsix`.
+
+## Instalar localmente
+
+```bash
+npm run extensao:instalar-local
+```
+
+Ou:
+
+```bash
+code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --force
+```
+
+## Smoke test
+
+1. Abra um projeto com `.sema`.
+2. Confirme que o Language Server inicia sem crash.
+3. Rode `Sema: Diagnosticar CLI`.
+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 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,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.