@semacode/cli 1.5.18 → 1.5.19

package/docs/pagamento-ponta-a-ponta.md

@@ -1,22 +1,28 @@
 # Pagamento Ponta a Ponta na Sema
 
-Este documento descreve o vertical oficial de pagamento da Sema no fluxo publico atual.
+<!-- 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.
 
-O objetivo nao e mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem ja consegue modelar um fluxo de negocio real com:
 
-- contrato publico
-- seguranca e autorizacao
+Este documento descreve o vertical oficial de pagamento da Sema no fluxo público atual.
+
+O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
+
+- contrato público
+- segurança e autorizacao
 - classificacao de dados
 - segredos e proibicoes explicitas
 - regras
 - efeitos operacionais
-- execucao, idempotencia, retry e compensacao
+- execução, idempotencia, retry e compensacao
 - transicoes de estado
-- orquestracao
+- orquestração
 - erros publicos
-- testes executaveis com saida, status ou erro observavel
+- testes executaveis com saída, status ou erro observavel
 
-## Arquivos de referencia
+## Arquivos de referência
 
 - `exemplos/pagamento_dominio.sema`
 - `exemplos/pagamento.sema`
@@ -33,7 +39,7 @@ Centraliza os contratos compartilhados:
 
 ### `exemplos.pagamento`
 
-Centraliza a operacao do vertical:
+Centraliza a operação do vertical:
 
 - `task processar_pagamento`
 - `task confirmar_pagamento`
@@ -44,19 +50,19 @@ Centraliza a operacao do vertical:
 
 ## Narrativa do caso
 
-### Entrada publica
+### Entrada pública
 
-A operacao entra por:
+A operação entra por:
 
 - `route processar_pagamento_publico`
 
-Esse contrato publica:
+Esse contrato pública:
 
 - `pagamento_id`
 - `valor`
 - `token`
 
-E expoe:
+É expoe:
 
 - `pagamento`
 - `status`
@@ -76,7 +82,7 @@ A `task processar_pagamento` faz o trabalho central:
 - notifica comprovante
 - registra auditoria
 - declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
-- garante consistencia da saida
+- garante consistencia da saída
 
 ### Estado e transicoes
 
@@ -86,15 +92,15 @@ O `state ciclo_pagamento` ancora o contrato de transicao:
 - `AUTORIZADO -> PROCESSADO`
 - `PENDENTE -> RECUSADO`
 
-A `task` explicita quais transicoes ela realmente usa.
+A `task` explícita quais transicoes ela realmente usa.
 
-### Flow de orquestracao
+### Flow de orquestração
 
 O `flow orquestracao_pagamento` demonstra:
 
 - passagem de contexto
-- confirmacao em caso de sucesso
-- notificacao em caso de recusa
+- confirmação em caso de sucesso
+- notificação em caso de recusa
 - registro de timeout em caso de indisponibilidade
 - ramificacao por erro tipado
 
@@ -108,7 +114,7 @@ O vertical usa as 5 categorias oficiais da Sema:
 - `notificacao`
 - `auditoria`
 
-Tambem usa `criticidade` para deixar claro o peso operacional do efeito.
+Também usa `criticidade` para deixar claro o peso operacional do efeito.
 
 ### Falhas reais
 
@@ -122,9 +128,9 @@ O vertical cobre explicitamente:
 
 ### 1. Escrever ou ajustar os arquivos `.sema`
 
-Use o dominio compartilhado em um modulo e a operacao em outro modulo.
+Use o domínio compartilhado em um módulo e a operação em outro módulo.
 
-### 2. Aplicar o formato canonico
+### 2. Aplicar o formato canônico
 
 ```bash
 sema formatar exemplos
@@ -136,7 +142,7 @@ sema formatar exemplos
 sema validar exemplos/pagamento.sema
 ```
 
-### 4. Gerar codigo
+### 4. Gerar código
 
 ```bash
 sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
@@ -151,15 +157,15 @@ sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamen
 
 ## O que esse vertical prova
 
-Se esse vertical passa, a Sema ja consegue demonstrar que:
+Se esse vertical passa, a Sema já consegue demonstrar que:
 
-- modela contrato publico
-- modela superficie sensivel sem deixar seguranca invisivel
+- modela contrato público
+- modela superficie sensível sem deixar segurança invisível
 - modela efeitos operacionais
 - modela falhas reais
-- modulariza dominio com `use`
-- declara idempotencia e execucao critica sem criar sintaxe nova
+- modulariza domínio com `use`
+- declara idempotencia e execução crítica sem criar sintaxe nova
 - gera artefatos coerentes para TypeScript e Python
 - executa testes gerados sem gambiarra conceitual
 
-Esse e o criterio pratico que sustenta o uso publico do vertical de pagamento como referencia para IA e geracao.
+Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.

package/docs/persistencia-vendor-first.md

@@ -1,6 +1,12 @@
-# Persistencia Vendor-First
+# Persistência Vendor-First
 
-Sema 1.5.18 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` tambem materializa persistencia local real em `Preferences`, `localStorage` e `sessionStorage` quando a task esta ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
+<!-- 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 1.5.19 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
 
 ## Engines publicas
 
@@ -128,17 +134,17 @@ Cada recurso recebe compatibilidade por engine:
 - `parcial`
 - `invalido`
 
-Isso deixa explicito quando o contrato esta pedindo portabilidade falsa, por exemplo:
+Isso deixa explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
 
 - `table` em `redis`
 - `foreign_keys` em engine sem suporte equivalente
-- transacao multi-documento tratada como universal
+- transação multi-documento tratada como universal
 
 ## Onde isso aparece
 
 - parser e AST
 - IR canonica
-- analisador semantico
+- analisador semântico
 - formatador
 - `sema drift`
 - `sema importar`

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

@@ -1,8 +1,14 @@
 # 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 nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primario e o agente.
+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
 
@@ -68,9 +74,9 @@ Se voce quiser um prompt ainda mais curto e pronto para colar, use:
 sema prompt-curto caminho/arquivo.sema --curto --para mudanca
 ```
 
-## Variacao para revisao
+## Variacao para revisão
 
-Use esta versao quando a IA for revisar `.sema` em vez de criar:
+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.
@@ -78,15 +84,15 @@ Revise este modulo Sema como contrato semantico executavel. Procure incoerencias
 
 ## Variacao para geracao
 
-Use esta versao quando a IA for escrever modulo novo:
+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 diagnostico
+## Variacao para correcao guiada por diagnóstico
 
-Use esta versao quando a IA ja tiver erro concreto para corrigir:
+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.
@@ -102,4 +108,4 @@ Idealmente, acompanhe o prompt com:
 - o resultado de `sema diagnosticos --json`, se houver erro
 - um exemplo oficial parecido
 
-Sem isso, a IA pode ate acertar. Com isso, ela trabalha direito.
+Sem isso, a IA pode até acertar. Com isso, ela trabalha direito.

package/docs/rollback.md

@@ -1,47 +1,49 @@
 # Rollback
 
-Rollback de release publica da Sema deve preservar rastreabilidade. NPM nao deve ser tratado como pasta temporaria: apagar versao publicada e medida extrema e limitada.
+<!-- 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 ou MCP publicados quebram instalacao basica.
-- VSIX publicada nao inicia ou quebra o Language Server.
+- 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 invalido.
+- 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 ultima versao boa, quando necessario:
+2. Reponte `latest` no NPM para a última versão boa, quando necessário:
 
 ```bash
 npm dist-tag add @semacode/cli@<versao-boa> latest
-npm dist-tag add @semacode/mcp@<versao-boa> latest
 ```
 
-3. Se o problema for so VSIX ou asset de release, substitua o asset no GitHub Release ou publique uma release patch.
-4. Prefira publicar patch corretivo (`1.5.18`, por exemplo) quando o pacote ja saiu para usuarios.
+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.19`, por exemplo) quando o pacote já saiu para usuários.
 
-## Validacao de rollback
+## Validação de rollback
 
 ```bash
 npm view @semacode/cli dist-tags --json
-npm view @semacode/mcp dist-tags --json
 npm install -g @semacode/cli@latest
-npm install -g @semacode/mcp@latest
 sema --version
-sema-mcp --help
 ```
 
 ## Git
 
-Se o commit foi empurrado mas a release falhou antes de publicar NPM, corrija com novo commit. Evite reescrever `main` depois de push publico.
+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 nao existe release consumida:
+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 usuarios consumirem o tag.
+Use isso somente antes de usuários consumirem o tag.

package/docs/sintaxe.md

@@ -1,61 +1,67 @@
-# Sintaxe Canonica
-
+# Sintaxe Canonica
+
+<!-- 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.
+
+
 A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no contexto de IA. A escrita humana pode ser legivel, mas o alvo principal da sintaxe e gerar contrato consumivel por agente.
-
-## Regras basicas
-
-- um arquivo `.sema` contem um `module` principal
-- cada bloco abre com palavra-chave e fecha com `}`
-- campos usam `nome: valor`
-- blocos declarativos podem aparecer aninhados quando o contrato exigir
-- `tests` usa blocos `caso`
-
-## Blocos de primeira classe
-
-- `module`
-- `use`
-- `database`
-- `type`
-- `entity`
-- `enum`
-- `state`
-- `task`
-- `flow`
-- `route`
-- `worker`
-- `evento`
-- `fila`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-- `tests`
-- `docs`
-- `comments`
-
+
+## Regras basicas
+
+- um arquivo `.sema` contem um `module` principal
+- cada bloco abre com palavra-chave e fecha com `}`
+- campos usam `nome: valor`
+- blocos declarativos podem aparecer aninhados quando o contrato exigir
+- `tests` usa blocos `caso`
+
+## Blocos de primeira classe
+
+- `module`
+- `use`
+- `database`
+- `type`
+- `entity`
+- `enum`
+- `state`
+- `task`
+- `flow`
+- `route`
+- `worker`
+- `evento`
+- `fila`
+- `cron`
+- `webhook`
+- `cache`
+- `storage`
+- `policy`
+- `tests`
+- `docs`
+- `comments`
+
 ## Subblocos comuns
-
-- `input`
-- `output`
-- `rules`
-- `effects`
-- `auth`
-- `authz`
-- `dados`
-- `audit`
-- `segredos`
-- `forbidden`
-- `impl`
-- `vinculos`
-- `execucao`
-- `guarantees`
-- `error`
-- `fields`
-- `invariants`
-- `transitions`
-- `given`
-- `when`
+
+- `input`
+- `output`
+- `rules`
+- `effects`
+- `auth`
+- `authz`
+- `dados`
+- `audit`
+- `segredos`
+- `forbidden`
+- `impl`
+- `vinculos`
+- `execucao`
+- `guarantees`
+- `error`
+- `fields`
+- `invariants`
+- `transitions`
+- `given`
+- `when`
 - `expect`
 
 ## Tipos primitivos
@@ -77,27 +83,27 @@ Tipos primitivos reconhecidos diretamente:
 `Timestamp` e `Objeto` funcionam como aliases primitivos suportados e preservam o texto original na IR.
 
 ## Tipos compostos
-
-```sema
-input {
-  ids: Lista<Id> required
-  metadata: Mapa<Texto, Texto>
-  responsavel: Opcional<Usuario>
-  chave_publica: Texto|Id
-}
-```
-
+
+```sema
+input {
+  ids: Lista<Id> required
+  metadata: Mapa<Texto, Texto>
+  responsavel: Opcional<Usuario>
+  chave_publica: Texto|Id
+}
+```
+
 Formas suportadas:
-
-- `Lista<T>`
-- `Mapa<K, V>`
-- `Opcional<T>`
-- `T1|T2`
+
+- `Lista<T>`
+- `Mapa<K, V>`
+- `Opcional<T>`
+- `T1|T2`
 - `T?`
 
 ## Predicados normalizados
 
-Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor tambem `predicadoCanonico`.
+Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor também `predicadoCanonico`.
 
 Exemplo:
 
@@ -108,105 +114,105 @@ rules {
 }
 ```
 
-Na IR, `email_valido` continua existindo como escrito e pode receber uma normalizacao como `valid_email`; `preenchido` pode receber `filled`. Esse campo e opcional e serve a agente/automacao, nao muda a sintaxe publica.
-
-## Persistencia vendor-first
-
-O bloco `database` modela banco e recursos persistidos sem apagar as diferencas entre engines.
-
-Estrutura base:
-
-```sema
-database principal_postgres {
-  engine: postgres
-  consistency: forte
-  durability: alta
-  transaction_model: mvcc
-  query_model: sql
-}
-```
-
-Recursos canonicamente suportados:
-
-- `table`
-- `index`
-- `relationship`
-- `query`
-- `retention`
-- `lock`
-- `replication`
-- `collection`
-- `document`
-- `keyspace`
-- `stream`
-- `capabilities`
-
-Exemplo relacional:
-
-```sema
-database principal_postgres {
-  engine: postgres
-  schema: public
-  capabilities {
-    joins
-    views
-    foreign_keys
-  }
-  table pedidos {
-    entity: Pedido
-  }
-  relationship pedido_cliente {
-    from: Pedido
-    to: Cliente
-  }
-  query buscar_pedidos {
-    mode: sql
-  }
-}
-```
-
-Exemplo documental:
-
-```sema
-database principal_mongodb {
-  engine: mongodb
-  query_model: documento
-  collection pedidos {
-    collection: pedidos
-  }
-  document pedido_snapshot {
-    entity: PedidoSnapshot
-  }
-  query pipeline_pedido {
-    mode: pipeline
-  }
-}
-```
-
-Exemplo key-value:
-
-```sema
-database principal_redis {
-  engine: redis
-  query_model: chave_valor
-  keyspace cache_pedidos {
-    ttl: "300s"
-  }
-  stream eventos_pedido {
-    surface: fila
-  }
-}
-```
-
-## Compatibilidade declarada
-
-O IR de persistencia calcula compatibilidade por recurso com quatro estados:
-
-- `nativo`
-- `adaptado`
-- `parcial`
-- `invalido`
-
-Isso existe para deixar explicito quando um contrato esta pedindo de um banco algo que ele nao entrega do mesmo jeito.
-
-O mesmo principio vale para runtime de orquestracao. Superficies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra familias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.
+Na IR, `email_valido` continua existindo como escrito e pode receber uma normalizacao como `valid_email`; `preenchido` pode receber `filled`. Esse campo e opcional e serve a agente/automacao, não muda a sintaxe pública.
+
+## Persistência vendor-first
+
+O bloco `database` modela banco e recursos persistidos sem apagar as diferenças entre engines.
+
+Estrutura base:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+}
+```
+
+Recursos canonicamente suportados:
+
+- `table`
+- `index`
+- `relationship`
+- `query`
+- `retention`
+- `lock`
+- `replication`
+- `collection`
+- `document`
+- `keyspace`
+- `stream`
+- `capabilities`
+
+Exemplo relacional:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+Exemplo documental:
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+Exemplo key-value:
+
+```sema
+database principal_redis {
+  engine: redis
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+}
+```
+
+## Compatibilidade declarada
+
+O IR de persistência calcula compatibilidade por recurso com quatro estados:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso existe para deixar explícito quando um contrato está pedindo de um banco algo que ele não entrega do mesmo jeito.
+
+O mesmo principio vale para runtime de orquestração. Superfícies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra famílias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.