@semacode/cli 1.5.27 → 1.5.29

package/docs/prompt-base-ia-sema.md

@@ -1,111 +1,111 @@
-# Prompt-Base Oficial para IA Trabalhar com 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 arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
-
-O objetivo não é fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema não foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primário e o agente.
-
-## Prompt-base
-
-Use o texto abaixo como base:
-
-```text
-Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
-
-Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
-
-Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
-
-Fontes de verdade, em ordem:
-1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
-2. `SEMA_BRIEF.md`
-3. `SEMA_INDEX.json`
-4. README do projeto
-5. gramatica e documentacao de sintaxe da Sema
-6. especificacao semantica da linguagem
-7. exemplos oficiais, com prioridade para o vertical de pagamento
-8. `sema resumo` e `briefing.min.json` quando a IA for pequena
-9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
-
-Regras de operacao:
-- preserve o significado semantico
-- use o formatador oficial da Sema como fonte unica de estilo
-- use diagnosticos estruturados como contrato de correcao
-- use a IR como fonte de verdade semantica quando houver duvida
-- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
-- nao conclua uma alteracao sem validar e verificar o modulo
-- trate `importar` como bootstrap revisavel, nao como contrato final automatico
-- trate `drift` como medicao de verdade contra codigo vivo
-- trate `impl` como ponte entre task e simbolo real
-- nao invente regra de negocio que o contrato e o codigo nao sustentem
-
-Antes de editar `.sema`, entenda:
-- o module alvo
-- os contratos de task, route, error, effects, guarantees, state e flow
-- os exemplos oficiais relacionados
-
-Depois de editar `.sema`, execute este fluxo:
-1. formatar
-2. validar
-3. diagnosticar, se houver falha
-4. verificar
-
-Se houver conflito entre texto livre e IR/diagnosticos, priorize a IR e os diagnosticos da CLI.
-
-Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao improvise sem base.
-```
-
-## Variacao curta
-
-Se voce quiser um prompt menor para uso frequente:
-
-```text
-Trabalhe com Sema como contrato semantico IA-first orientado a agente. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
-```
-
-Se voce quiser um prompt ainda mais curto e pronto para colar, use:
-
-```bash
-sema prompt-curto caminho/arquivo.sema --curto --para mudanca
-```
-
-## Variacao para revisão
-
-Use está versão quando a IA for revisar `.sema` em vez de criar:
-
-```text
-Revise este modulo Sema como contrato semantico executavel. Procure incoerencias entre input, output, rules, effects, guarantees, state, flow, route e error. Considere a IR e os diagnosticos da CLI como fonte de verdade. Nao critique estilo fora do que o formatador oficial resolveria automaticamente.
-```
-
-## Variacao para geracao
-
-Use está versão quando a IA for escrever módulo novo:
-
-```text
-Gere um modulo Sema seguindo a gramatica oficial, os exemplos do projeto e o estilo do formatador canonico. Estruture o modulo como contrato semantico executavel, com blocos explicitos para entrada, saida, regras, efeitos, garantias, erros, estado, fluxo e testes quando fizer sentido. Nao use sintaxe fora do repertorio ja suportado pela linguagem.
-```
-
-## Variacao para correcao guiada por diagnóstico
-
-Use está versão quando a IA já tiver erro concreto para corrigir:
-
-```text
-Corrija este modulo Sema a partir dos diagnosticos estruturados da CLI. Preserve a intencao do contrato e altere apenas o necessario para eliminar as falhas. Depois da correcao, aplique o formatador oficial e revalide.
-```
-
-## O que sempre anexar junto do prompt
-
-Idealmente, acompanhe o prompt com:
-
-- o arquivo `.sema` alvo
-- o resultado de `sema ast --json`
-- o resultado de `sema ir --json`
-- o resultado de `sema diagnosticos --json`, se houver erro
-- um exemplo oficial parecido
-
-Sem isso, a IA pode até acertar. Com isso, ela trabalha direito.
+# Prompt-Base Oficial para IA Trabalhar com 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 arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
+
+O objetivo não é fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema não foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primário e o agente.
+
+## Prompt-base
+
+Use o texto abaixo como base:
+
+```text
+Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
+
+Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
+
+Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
+
+Fontes de verdade, em ordem:
+1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
+2. `SEMA_BRIEF.md`
+3. `SEMA_INDEX.json`
+4. README do projeto
+5. gramatica e documentacao de sintaxe da Sema
+6. especificacao semantica da linguagem
+7. exemplos oficiais, com prioridade para o vertical de pagamento
+8. `sema resumo` e `briefing.min.json` quando a IA for pequena
+9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
+
+Regras de operacao:
+- preserve o significado semantico
+- use o formatador oficial da Sema como fonte unica de estilo
+- use diagnosticos estruturados como contrato de correcao
+- use a IR como fonte de verdade semantica quando houver duvida
+- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
+- nao conclua uma alteracao sem validar e verificar o modulo
+- trate `importar` como bootstrap revisavel, nao como contrato final automatico
+- trate `drift` como medicao de verdade contra codigo vivo
+- trate `impl` como ponte entre task e simbolo real
+- nao invente regra de negocio que o contrato e o codigo nao sustentem
+
+Antes de editar `.sema`, entenda:
+- o module alvo
+- os contratos de task, route, error, effects, guarantees, state e flow
+- os exemplos oficiais relacionados
+
+Depois de editar `.sema`, execute este fluxo:
+1. formatar
+2. validar
+3. diagnosticar, se houver falha
+4. verificar
+
+Se houver conflito entre texto livre e IR/diagnosticos, priorize a IR e os diagnosticos da CLI.
+
+Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao improvise sem base.
+```
+
+## Variacao curta
+
+Se voce quiser um prompt menor para uso frequente:
+
+```text
+Trabalhe com Sema como contrato semantico IA-first orientado a agente. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
+```
+
+Se voce quiser um prompt ainda mais curto e pronto para colar, use:
+
+```bash
+sema prompt-curto caminho/arquivo.sema --curto --para mudanca
+```
+
+## Variacao para revisão
+
+Use está versão quando a IA for revisar `.sema` em vez de criar:
+
+```text
+Revise este modulo Sema como contrato semantico executavel. Procure incoerencias entre input, output, rules, effects, guarantees, state, flow, route e error. Considere a IR e os diagnosticos da CLI como fonte de verdade. Nao critique estilo fora do que o formatador oficial resolveria automaticamente.
+```
+
+## Variacao para geracao
+
+Use está versão quando a IA for escrever módulo novo:
+
+```text
+Gere um modulo Sema seguindo a gramatica oficial, os exemplos do projeto e o estilo do formatador canonico. Estruture o modulo como contrato semantico executavel, com blocos explicitos para entrada, saida, regras, efeitos, garantias, erros, estado, fluxo e testes quando fizer sentido. Nao use sintaxe fora do repertorio ja suportado pela linguagem.
+```
+
+## Variacao para correcao guiada por diagnóstico
+
+Use está versão quando a IA já tiver erro concreto para corrigir:
+
+```text
+Corrija este modulo Sema a partir dos diagnosticos estruturados da CLI. Preserve a intencao do contrato e altere apenas o necessario para eliminar as falhas. Depois da correcao, aplique o formatador oficial e revalide.
+```
+
+## O que sempre anexar junto do prompt
+
+Idealmente, acompanhe o prompt com:
+
+- o arquivo `.sema` alvo
+- o resultado de `sema ast --json`
+- o resultado de `sema ir --json`
+- o resultado de `sema diagnosticos --json`, se houver erro
+- um exemplo oficial parecido
+
+Sem isso, a IA pode até acertar. Com isso, ela trabalha direito.

package/docs/repositories.md

@@ -1,54 +1,54 @@
-# Repository Boundary
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois.
-> ES: Español al final.
-
-## English
-
-Sema uses an open-core repository boundary.
-
-The public repository contains the semantic language, parser, public CLI, base profiles, examples, generic documentation, public tests, and the basic editor extension. It must be useful for adoption, learning, local validation, and community contribution without exposing commercial operations.
-
-The private repository contains the hosted product: commercial website, account panel, OAuth and key issuance flows, Supabase control plane, billing, production deployment, operational runbooks, private integrations, customer data, private rule packs, generated snapshots, and commercial showcases.
-
-Before any public push, release, or npm publication, run:
-
-```bash
-npm run repo:verificar-publico
-```
-
-If the check blocks a file, move it to the private repository or replace it with a public-safe example.
-
-## Português
-
-A Sema usa uma fronteira open-core entre repositórios.
-
-O repositório público contém a linguagem semântica, parser, CLI pública, profiles base, exemplos, documentação genérica, testes públicos e a extensão básica do editor. Ele precisa ser útil para adoção, aprendizado, validação local e contribuição da comunidade sem expor a operação comercial.
-
-O repositório privado contém o produto hospedado: site comercial, painel de conta, fluxos de OAuth e emissão de chaves, control plane Supabase, billing, deploy de produção, runbooks operacionais, integrações privadas, dados de clientes, rule packs privados, snapshots gerados e showcases comerciais.
-
-Antes de qualquer push público, release ou publicação npm, rode:
-
-```bash
-npm run repo:verificar-publico
-```
-
-Se o check bloquear um arquivo, mova para o repositório privado ou substitua por um exemplo seguro para o público.
-
-## Español
-
-Sema usa una frontera open-core entre repositorios.
-
-El repositorio público contiene el lenguaje semántico, parser, CLI pública, perfiles base, ejemplos, documentación genérica, pruebas públicas y la extensión básica del editor. Debe servir para adopción, aprendizaje, validación local y contribución de la comunidad sin exponer la operación comercial.
-
-El repositorio privado contiene el producto hospedado: sitio comercial, panel de cuenta, flujos de OAuth y emisión de claves, control plane Supabase, billing, despliegue de producción, runbooks operativos, integraciones privadas, datos de clientes, rule packs privados, snapshots generados y showcases comerciales.
-
-Antes de cualquier push público, release o publicación npm, ejecuta:
-
-```bash
-npm run repo:verificar-publico
-```
-
-Si el check bloquea un archivo, muévelo al repositorio privado o sustitúyelo por un ejemplo seguro para el público.
+# Repository Boundary
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois.
+> ES: Español al final.
+
+## English
+
+Sema uses an open-core repository boundary.
+
+The public repository contains the semantic language, parser, public CLI, base profiles, examples, generic documentation, public tests, and the basic editor extension. It must be useful for adoption, learning, local validation, and community contribution without exposing commercial operations.
+
+The private repository contains the hosted product: commercial website, account panel, OAuth and key issuance flows, Supabase control plane, billing, production deployment, operational runbooks, private integrations, customer data, private rule packs, generated snapshots, and commercial showcases.
+
+Before any public push, release, or npm publication, run:
+
+```bash
+npm run repo:verificar-publico
+```
+
+If the check blocks a file, move it to the private repository or replace it with a public-safe example.
+
+## Português
+
+A Sema usa uma fronteira open-core entre repositórios.
+
+O repositório público contém a linguagem semântica, parser, CLI pública, profiles base, exemplos, documentação genérica, testes públicos e a extensão básica do editor. Ele precisa ser útil para adoção, aprendizado, validação local e contribuição da comunidade sem expor a operação comercial.
+
+O repositório privado contém o produto hospedado: site comercial, painel de conta, fluxos de OAuth e emissão de chaves, control plane Supabase, billing, deploy de produção, runbooks operacionais, integrações privadas, dados de clientes, rule packs privados, snapshots gerados e showcases comerciais.
+
+Antes de qualquer push público, release ou publicação npm, rode:
+
+```bash
+npm run repo:verificar-publico
+```
+
+Se o check bloquear um arquivo, mova para o repositório privado ou substitua por um exemplo seguro para o público.
+
+## Español
+
+Sema usa una frontera open-core entre repositorios.
+
+El repositorio público contiene el lenguaje semántico, parser, CLI pública, perfiles base, ejemplos, documentación genérica, pruebas públicas y la extensión básica del editor. Debe servir para adopción, aprendizaje, validación local y contribución de la comunidad sin exponer la operación comercial.
+
+El repositorio privado contiene el producto hospedado: sitio comercial, panel de cuenta, flujos de OAuth y emisión de claves, control plane Supabase, billing, despliegue de producción, runbooks operativos, integraciones privadas, datos de clientes, rule packs privados, snapshots generados y showcases comerciales.
+
+Antes de cualquier push público, release o publicación npm, ejecuta:
+
+```bash
+npm run repo:verificar-publico
+```
+
+Si el check bloquea un archivo, muévelo al repositorio privado o sustitúyelo por un ejemplo seguro para el público.

package/docs/rollback.md

@@ -1,49 +1,49 @@
-# Rollback
-
-<!-- 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.
-
-
-Rollback de release pública da Sema deve preservar rastreabilidade. NPM não deve ser tratado como pasta temporaria: apagar versão publicada e medida extrema e limitada.
-
-## Quando aplicar
-
-- CLI publicada quebra instalação básica.
-- VSIX publicada não inicia ou quebra o Language Server.
-- Instaladores baixam asset errado.
-- Release notes ou checksums apontam para artefato inválido.
-
-## Primeira resposta
-
-1. Marque o problema no GitHub Release.
-2. Reponte `latest` no NPM para a última versão boa, quando necessário:
-
-```bash
-npm dist-tag add @semacode/cli@<versao-boa> latest
-```
-
-3. Se o problema for só VSIX ou asset de release, substitua o asset no GitHub Release ou publique uma release patch.
-4. Prefira publicar patch corretivo (`1.5.27`, por exemplo) quando o pacote já saiu para usuários.
-
-## Validação de rollback
-
-```bash
-npm view @semacode/cli dist-tags --json
-npm install -g @semacode/cli@latest
-sema --version
-```
-
-## Git
-
-Se o commit foi empurrado mas a release falhou antes de publicar NPM, corrija com novo commit. Evite reescrever `main` depois de push público.
-
-Se o tag foi criado errado e ainda não existe release consumida:
-
-```bash
-git tag -d v<versao>
-git push origin :refs/tags/v<versao>
-```
-
-Use isso somente antes de usuários consumirem o tag.
+# Rollback
+
+<!-- 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.
+
+
+Rollback de release pública da Sema deve preservar rastreabilidade. NPM não deve ser tratado como pasta temporaria: apagar versão publicada e medida extrema e limitada.
+
+## Quando aplicar
+
+- CLI publicada quebra instalação básica.
+- VSIX publicada não inicia ou quebra o Language Server.
+- Instaladores baixam asset errado.
+- Release notes ou checksums apontam para artefato inválido.
+
+## Primeira resposta
+
+1. Marque o problema no GitHub Release.
+2. Reponte `latest` no NPM para a última versão boa, quando necessário:
+
+```bash
+npm dist-tag add @semacode/cli@<versao-boa> latest
+```
+
+3. Se o problema for só VSIX ou asset de release, substitua o asset no GitHub Release ou publique uma release patch.
+4. Prefira publicar patch corretivo (`1.5.29`, por exemplo) quando o pacote já saiu para usuários.
+
+## Validação de rollback
+
+```bash
+npm view @semacode/cli dist-tags --json
+npm install -g @semacode/cli@latest
+sema --version
+```
+
+## Git
+
+Se o commit foi empurrado mas a release falhou antes de publicar NPM, corrija com novo commit. Evite reescrever `main` depois de push público.
+
+Se o tag foi criado errado e ainda não existe release consumida:
+
+```bash
+git tag -d v<versao>
+git push origin :refs/tags/v<versao>
+```
+
+Use isso somente antes de usuários consumirem o tag.