@semacode/cli 1.5.18 → 1.5.25

package/docs/cli.md

@@ -1,106 +1,175 @@
-# CLI da Sema
-
-## Papel da CLI
-
-A CLI e a interface oficial da Sema para:
-
-- validar contratos `.sema`
-- exportar AST e IR
-- medir `drift` entre contrato e codigo vivo
-- importar legado para rascunho revisavel
-- gerar codigo derivado
-- preparar contexto IA-first
-- resolver docs obrigatorias por intencao antes de editar ou operar
-- verificar multiplos alvos de geracao
-
-## Tres modos de operacao
-
-Projeto novo:
-
-- `sema iniciar`
-- `sema validar`
-- `sema compilar`
-- `sema verificar`
-
-Projeto ja semantizado:
-
-- `sema inspecionar`
-- `sema resumo`
-- `sema drift`
-- `sema contexto-ia`
-
-Adocao incremental:
-
-- `sema importar`
-- `sema formatar`
-- `sema validar`
-- `sema drift`
-
-## Persistencia vendor-first
-
-A linha 1.5.18 mantem persistencia vendor-first como secao canonica no contrato, no semantico, na IR e no formatador, alem de `drift` com escopo real, `impacto`, renomeacao semantica assistida, `verificar` mais coerente nos alvos gerados, match de metodos JS/TS definidos via `Object.assign(...prototype...)`, leitura de `Preferences`/`localStorage`/`sessionStorage`, fallback para `angular-consumer` standalone sem `.routes`, limpeza de runtime da CLI publica no Windows e os endurecimentos IA-first de contrato frouxo.
-
-Cobertura publica:
-
-- `postgres`: `table`, `relationship`, `query`, `schema`, capacidades relacionais
-- `mysql`: `table`, `index`, consultas SQL e diferencas operacionais do engine
-- `sqlite`: `table`, `retention`, uso local e edge
-- `mongodb`: `collection`, `document`, `query` em `pipeline`
-- `redis`: `keyspace`, `stream`, `retention`, TTL e superficies de estado
-
-## Drift e codigo vivo
-
-`sema drift` agora cruza contrato com recursos reais encontrados em:
-
-- codigo de backend
-- DDL `.sql`
-- schema `.prisma`
-- uso de MongoDB
-- uso de Redis, incluindo keyspaces e streams
-
-O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas claras.
-
-## Ajuda IA-first
-
-- `sema ajuda-ia`
-- `sema starter-ia`
-- `sema resumo <arquivo-ou-pasta> --micro|--curto|--medio`
-- `sema prompt-curto <arquivo-ou-pasta> --micro|--curto|--medio`
-- `sema contexto-ia <arquivo.sema> --saida <diretorio>`
-- `sema sync-ai-entrypoints --json`
-- `sema docs-impacto --intencao <acao> --criar-ausentes --json`
-- `sema finalizar-mudanca --intencao <acao> --doc-lida <caminho> --json`
-
-## Importadores publicos
-
-- `nestjs`
-- `fastapi`
-- `flask`
-- `nextjs`
-- `nextjs-consumer`
-- `react-vite-consumer`
-- `angular-consumer`
-- `flutter-consumer`
-- `firebase`
-- `dotnet`
-- `java`
-- `go`
-- `rust`
-- `cpp`
-- `typescript`
-- `python`
-- `dart`
-
-## Comandos mais usados
-
-```bash
-sema validar <arquivo-ou-pasta> --json
-sema diagnosticos <arquivo.sema> --json
-sema ir <arquivo.sema> --json
-sema drift <arquivo-ou-pasta> --json
-sema importar <fonte> <diretorio> --saida <diretorio> --json
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>
-sema verificar <arquivo-ou-pasta> --saida <diretorio>
-```
+# Sema CLI
+
+## English
+
+The Sema CLI is the public npm package for local semantic governance. It validates `.sema` contracts, checks drift, maps impact, prepares AI-first context, resolves documentation gates, and runs profile validators before an agent continues.
+
+Current public version: `1.5.25`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Português
+
+A CLI da Sema é o pacote público no npm para governança semântica local. Ela valida contratos `.sema`, verifica drift, mapeia impacto, prepara contexto IA-first, resolve gates de documentação e roda validadores de profiles antes de um agente continuar.
+
+Versão pública atual: `1.5.25`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Español
+
+La CLI de Sema es el paquete público en npm para gobernanza semántica local. Valida contratos `.sema`, verifica drift, mapea impacto, prepara contexto IA-first, resuelve gates de documentación y ejecuta validadores de profiles antes de que un agente continúe.
+
+Versión pública actual: `1.5.25`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Referência Operacional
+
+### Papel da CLI
+
+A CLI é a interface oficial da Sema para:
+
+- validar contratos `.sema`
+- exportar AST e IR
+- medir `drift` entre contrato e código vivo
+- importar legado para rascunho revisável
+- gerar código derivado
+- preparar contexto IA-first
+- resolver docs obrigatórias por intenção antes de editar ou operar
+- verificar múltiplos alvos de geração
+
+### Três Modos De Operação
+
+Projeto novo:
+
+- `sema iniciar`
+- `sema validar`
+- `sema compilar`
+- `sema verificar`
+
+Projeto já semantizado:
+
+- `sema inspecionar`
+- `sema resumo`
+- `sema drift`
+- `sema contexto-ia`
+
+Adoção incremental:
+
+- `sema importar`
+- `sema formatar`
+- `sema validar`
+- `sema drift`
+
+## Persistência vendor-first
+
+A linha 1.5.25 mantém persistência vendor-first como seção canônica no contrato, no semântico, na IR e no formatador, além de `drift` com escopo real, `impacto`, renomeação semântica assistida, `verificar` mais coerente nos alvos gerados, match de métodos JS/TS definidos via `Object.assign(...prototype...)`, leitura de `Preferences`/`localStorage`/`sessionStorage`, fallback para `angular-consumer` standalone sem `.routes`, limpeza de runtime da CLI pública no Windows, Sema Author oficial e MCP remoto desmembrado da distribuição pública.
+
+Cobertura pública:
+
+- `postgres`: `table`, `relationship`, `query`, `schema`, capacidades relacionais
+- `mysql`: `table`, `index`, consultas SQL e diferenças operacionais do engine
+- `sqlite`: `table`, `retention`, uso local e edge
+- `mongodb`: `collection`, `document`, `query` em `pipeline`
+- `redis`: `keyspace`, `stream`, `retention`, TTL e superfícies de estado
+
+## Drift e código vivo
+
+`sema drift` agora cruza contrato com recursos reais encontrados em:
+
+- código de backend
+- DDL `.sql`
+- schema `.prisma`
+- uso de MongoDB
+- uso de Redis, incluindo keyspaces e streams
+
+O objetivo não é adivinhar tudo; é produzir um score explicável com lacunas claras.
+
+## Ajuda IA-first
+
+- `sema ajuda-ia`
+- `sema starter-ia`
+- `sema resumo <arquivo-ou-pasta> --micro|--curto|--medio`
+- `sema prompt-curto <arquivo-ou-pasta> --micro|--curto|--medio`
+- `sema contexto-ia <arquivo.sema> --saida <diretorio>`
+- `sema sync-ai-entrypoints --json`
+- `sema docs-impacto --intencao <acao> --criar-ausentes --json`
+- `sema finalizar-mudanca --intencao <acao> --doc-lida <caminho> --json`
+
+## Profiles Semânticos
+
+Profiles oficiais usam contrato Sema normal e um gate de requisitos obrigatórios. O requisito comum é contrato primeiro: criar, editar ou remover contrato antes de qualquer ação. Se o contrato não declara o mínimo do domínio, o comando falha.
+
+```bash
+sema profile validar software contratos/sema/software.sema --json
+sema profile validar workflow contratos/sema/workflow_ops.sema --json
+sema profile validar ops contratos/sema/workflow_ops.sema --json
+sema profile validar game contratos/sema/game.sema --json
+sema profile validar legal contratos/sema/legal.sema --json
+sema profile validar research contratos/sema/research.sema --json
+```
+
+## Sema Author
+
+Author é um profile oficial para governança autoral IA-first. Ele usa a mesma DSL, sem palavra-chave nova, e organiza contratos em core, agents e flow. Se obra, tom, limite, público ou política muda, edite o contrato antes de gerar ou revisar texto.
+
+```bash
+sema author iniciar --saida contratos/author.sema
+sema author iniciar --tema-sensivel --saida contratos/author.sema
+sema author validar contratos/author.sema --json
+sema author briefing contratos/author.sema --json
+sema author revisar-cliches contratos/author.sema --texto "O escolhido predestinado aceitou a missão." --json
+sema author validar-narrativa contratos/author.sema --texto "Mara perdeu a chave para salvar Raul. Por isso, o capitulo seguinte muda a promessa dela." --texto-anterior "Mara prometeu proteger a chave." --json
+```
+
+O comando `author iniciar` usa os exemplos oficiais `author_obra_comum.sema` ou `author_tema_sensivel.sema` como starter. Ele não sobrescreve contrato existente.
+
+## Importadores Públicos
+
+- `nestjs`
+- `fastapi`
+- `flask`
+- `nextjs`
+- `nextjs-consumer`
+- `react-vite-consumer`
+- `angular-consumer`
+- `flutter-consumer`
+- `firebase`
+- `dotnet`
+- `java`
+- `go`
+- `rust`
+- `cpp`
+- `typescript`
+- `python`
+- `dart`
+
+## Comandos mais usados
+
+```bash
+sema validar <arquivo-ou-pasta> --json
+sema diagnosticos <arquivo.sema> --json
+sema ir <arquivo.sema> --json
+sema drift <arquivo-ou-pasta> --json
+sema author briefing <arquivo.sema> --json
+sema author revisar-cliches <arquivo.sema> --texto <texto> --json
+sema author validar-narrativa <arquivo.sema> --texto <texto> [--texto-anterior <texto>] --json
+sema importar <fonte> <diretorio> --saida <diretorio> --json
+sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
+sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>
+sema verificar <arquivo-ou-pasta> --saida <diretorio>
+```

package/docs/como-ensinar-a-sema-para-ia.md

@@ -1,29 +1,35 @@
 # Como Ensinar a Sema para IA
 
-Este documento explica como fazer uma IA entender a Sema sem depender de memoria previa do modelo. A estrategia correta nao e presumir que a IA "ja conhece a linguagem", e sim entregar contexto suficiente para ela operar com seguranca.
+<!-- 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.
 
-Leia isso do ponto de vista da CLI publica. A IA nao deve assumir que esta dentro do monorepo da Sema, nem que precisa chamar `node pacotes/cli/dist/index.js`.
+
+Este documento explica como fazer uma IA entender a Sema sem depender de memória prévia do modelo. A estratégia correta não é presumir que a IA "já conhece a linguagem", e sim entregar contexto suficiente para ela operar com segurança.
+
+Leia isso do ponto de vista da CLI pública. A IA não deve assumir que está dentro do monorepo da Sema, nem que precisa chamar `node pacotes/cli/dist/index.js`.
 
 ## Principio central
 
 Uma IA entende uma linguagem nova quando recebe quatro camadas de contexto:
 
 1. sintaxe
-2. semantica
+2. semântica
 3. estrutura intermediaria estavel
 4. exemplos reais
 
-Sem essas quatro camadas, o modelo comeca a adivinhar. E adivinhacao em linguagem de contrato e pedir para nascer bug feio.
+Sem essas quatro camadas, o modelo comeca a adivinhar. É adivinhação em linguagem de contrato e pedir para nascer bug feio.
 
-Antes de qualquer outra coisa, a IA tambem precisa receber a **moldura correta**:
+Antes de qualquer outra coisa, a IA também precisa receber a **moldura correta**:
 
-- a Sema e um contrato semantico IA-first para agentes operarem software vivo
-- a Sema foi feita para IA, nao para ergonomia humana
-- a Sema nao foi feita para "automatizar tudo"
+- a Sema é um contrato semântico IA-first para agentes operarem software vivo
+- a Sema foi feita para IA, não para ergonomia humana
+- a Sema não foi feita para "automatizar tudo"
 - a Sema existe para explicitar, alinhar e verificar contrato contra sistema vivo
 - humanos sao autores, revisores e aprovadores; agentes sao consumidores primarios
 
-Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar por adivinhacao.
+Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar por adivinhação.
 
 ## Camada 1. Sintaxe
 
@@ -33,33 +39,33 @@ Fontes principais:
 
 - [README.md](../README.md)
 - [sintaxe.md](./sintaxe.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
 
 Objetivo dessa camada:
 
 - reconhecer blocos validos
 - entender delimitadores
-- nao inventar palavras-chave
+- não inventar palavras-chave
 - respeitar a organizacao canonicamente formatada
 
-## Camada 2. Semantica
+## Camada 2. Semântica
 
 Depois de saber ler, a IA precisa saber o que cada bloco significa.
 
 Fontes principais:
 
 - [README.md](../README.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
 Objetivo dessa camada:
 
 - distinguir contrato interno de `task`
-- distinguir contrato publico de `route`
+- distinguir contrato público de `route`
 - entender `effects`, `guarantees`, `error`, `state` e `flow`
-- operar na linguagem como especificacao executavel, nao como texto decorativo
+- operar na linguagem como especificacao executavel, não como texto decorativo
 - entender que `importar` e bootstrap
-- entender que `drift` e regua de coerencia contra o runtime
+- entender que `drift` e regua de coerência contra o runtime
 - entender que `impl` e ponte rastreavel para simbolo vivo
 
 ## Camada 3. Estrutura intermediaria estavel
@@ -81,18 +87,18 @@ sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
 
 Como cada comando ajuda:
 
-- `resumo`: entrega cartao semantico pequeno para IA com janela curta
-- `validar --json`: diz se a base esta semanticamente valida
+- `resumo`: entrega cartao semântico pequeno para IA com janela curta
+- `validar --json`: diz se a base está semanticamente valida
 - `diagnosticos --json`: devolve erros e avisos como contrato estruturado
 - `ast --json`: mostra a forma sintatica escrita
-- `ir --json`: mostra a forma semantica resolvida
+- `ir --json`: mostra a forma semântica resolvida
 - `verificar --json`: mostra o estado operacional do projeto
 
-Se a IA puder consumir `ir --json`, melhor ainda. E ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Para modelo pequeno, comece em `resumo` e `briefing.min.json`.
+Se a IA puder consumir `ir --json`, melhor ainda. É ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Para modelo pequeno, comece em `resumo` e `briefing.min.json`.
 
 ## Camada 4. Exemplos reais
 
-Modelo aprende muito por padrao. Por isso, bons exemplos valem quase tanto quanto especificacao.
+Modelo aprende muito por padrão. Por isso, bons exemplos valem quase tanto quanto especificacao.
 
 Arquivos recomendados:
 
@@ -102,27 +108,27 @@ Arquivos recomendados:
 - [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
 - [crud_simples.sema](../exemplos/crud_simples.sema)
 
-O vertical oficial de pagamento deve ser tratado como a referencia principal.
+O vertical oficial de pagamento deve ser tratado como a referência principal.
 
-## O que a IA nao deve fazer
+## O que a IA não deve fazer
 
-- inventar palavras-chave fora da gramatica
+- inventar palavras-chave fora da gramática
 - introduzir blocos inexistentes
-- assumir semantica que nao aparece na especificacao
-- tratar draft importado como contrato final so porque veio da CLI
-- tratar a Sema como gerador magico de sistema completo
+- assumir semântica que não aparece na especificacao
+- tratar draft importado como contrato final só porque veio da CLI
+- tratar a Sema como gerador mágico de sistema completo
 - editar `.sema` sem rodar `sema formatar`
 - encerrar alteracao sem consultar `diagnosticos` quando houver falha
 
 ## O que a IA deve fazer
 
-- usar a gramatica e os exemplos como fonte de estilo
-- usar a IR como fonte de verdade semantica sempre que possivel
-- usar diagnosticos estruturados como guia de correcao
+- usar a gramática e os exemplos como fonte de estilo
+- usar a IR como fonte de verdade semântica sempre que possóvel
+- usar diagnósticos estruturados como guia de correcao
 - rodar o formatador antes de considerar o trabalho pronto
 - validar e verificar a mudanca no mesmo fluxo
 
-## Estrategia recomendada
+## Estratégia recomendada
 
 Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
 
@@ -131,19 +137,19 @@ Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta o
 3. [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 4. [prompt-base-ia-sema.md](./prompt-base-ia-sema.md)
 5. `sema resumo --micro` ou `sema resumo --curto`, conforme a capacidade da IA
-6. `ast --json`, `ir --json` e `diagnosticos --json` do modulo alvo, se a capacidade aguentar
+6. `ast --json`, `ir --json` e `diagnosticos --json` do módulo alvo, se a capacidade aguentar
 
 Essa ordem faz a IA ir de contexto geral para contexto operacional, em vez de cair direto num arquivo cru e sair chutando.
 
 ## Regra de ouro
 
-A Sema foi desenhada para ser entendida por IA, mas isso nao significa que a IA vai adivinhar sozinha.
+A Sema foi desenhada para ser entendida por IA, mas isso não significa que a IA vai adivinhar sozinha.
 
 Ela entende bem quando recebe:
 
 - especificacao
 - exemplos
 - JSON estrutural
-- feedback automatico
+- feedback automático
 
-Sem isso, ate o modelo mais caro vira estagiario emocionado.
+Sem isso, até o modelo mais caro vira estagiário emocionado.