@semacode/cli 1.5.28 → 1.5.29

package/docs/cli.md

@@ -1,175 +1,175 @@
-# 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.28`.
-
-```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.28`.
-
-```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.28`.
-
-```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.28 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>
-```
+# 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.29`.
+
+```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.29`.
+
+```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.29`.
+
+```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.29 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,155 +1,155 @@
-# Como Ensinar a Sema para 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.
-
-
-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. semântica
-3. estrutura intermediaria estavel
-4. exemplos reais
-
-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 também precisa receber a **moldura correta**:
-
-- 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 adivinhação.
-
-## Camada 1. Sintaxe
-
-A IA precisa saber como a linguagem e escrita.
-
-Fontes principais:
-
-- [README.md](../README.md)
-- [sintaxe.md](./sintaxe.md)
-- [integração-com-ia.md](./integracao-com-ia.md)
-
-Objetivo dessa camada:
-
-- reconhecer blocos validos
-- entender delimitadores
-- não inventar palavras-chave
-- respeitar a organizacao canonicamente formatada
-
-## Camada 2. Semântica
-
-Depois de saber ler, a IA precisa saber o que cada bloco significa.
-
-Fontes principais:
-
-- [README.md](../README.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 público de `route`
-- entender `effects`, `guarantees`, `error`, `state` e `flow`
-- operar na linguagem como especificacao executavel, não como texto decorativo
-- entender que `importar` e bootstrap
-- 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
-
-Essa e a camada que faz a parada parar de ser um cassino.
-
-Em vez de confiar que a IA vai interpretar `.sema` cru de primeira, use a CLI como tradutora oficial da linguagem.
-
-Comandos principais:
-
-```bash
-sema resumo arquivo.sema --micro --para onboarding
-sema validar arquivo.sema --json
-sema diagnosticos arquivo.sema --json
-sema ast arquivo.sema --json
-sema ir arquivo.sema --json
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-Como cada comando ajuda:
-
-- `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 semântica resolvida
-- `verificar --json`: mostra o estado operacional do projeto
-
-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 padrão. Por isso, bons exemplos valem quase tanto quanto especificacao.
-
-Arquivos recomendados:
-
-- [pagamento.sema](../exemplos/pagamento.sema)
-- [pagamento_dominio.sema](../exemplos/pagamento_dominio.sema)
-- [automacao.sema](../exemplos/automacao.sema)
-- [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
-- [crud_simples.sema](../exemplos/crud_simples.sema)
-
-O vertical oficial de pagamento deve ser tratado como a referência principal.
-
-## O que a IA não deve fazer
-
-- inventar palavras-chave fora da gramática
-- introduzir blocos inexistentes
-- 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 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
-
-## Estratégia recomendada
-
-Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
-
-1. [README.md](../README.md)
-2. [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
-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 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 não significa que a IA vai adivinhar sozinha.
-
-Ela entende bem quando recebe:
-
-- especificacao
-- exemplos
-- JSON estrutural
-- feedback automático
-
-Sem isso, até o modelo mais caro vira estagiário emocionado.
+# Como Ensinar a Sema para 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.
+
+
+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. semântica
+3. estrutura intermediaria estavel
+4. exemplos reais
+
+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 também precisa receber a **moldura correta**:
+
+- 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 adivinhação.
+
+## Camada 1. Sintaxe
+
+A IA precisa saber como a linguagem e escrita.
+
+Fontes principais:
+
+- [README.md](../README.md)
+- [sintaxe.md](./sintaxe.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
+
+Objetivo dessa camada:
+
+- reconhecer blocos validos
+- entender delimitadores
+- não inventar palavras-chave
+- respeitar a organizacao canonicamente formatada
+
+## Camada 2. Semântica
+
+Depois de saber ler, a IA precisa saber o que cada bloco significa.
+
+Fontes principais:
+
+- [README.md](../README.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 público de `route`
+- entender `effects`, `guarantees`, `error`, `state` e `flow`
+- operar na linguagem como especificacao executavel, não como texto decorativo
+- entender que `importar` e bootstrap
+- 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
+
+Essa e a camada que faz a parada parar de ser um cassino.
+
+Em vez de confiar que a IA vai interpretar `.sema` cru de primeira, use a CLI como tradutora oficial da linguagem.
+
+Comandos principais:
+
+```bash
+sema resumo arquivo.sema --micro --para onboarding
+sema validar arquivo.sema --json
+sema diagnosticos arquivo.sema --json
+sema ast arquivo.sema --json
+sema ir arquivo.sema --json
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
+```
+
+Como cada comando ajuda:
+
+- `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 semântica resolvida
+- `verificar --json`: mostra o estado operacional do projeto
+
+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 padrão. Por isso, bons exemplos valem quase tanto quanto especificacao.
+
+Arquivos recomendados:
+
+- [pagamento.sema](../exemplos/pagamento.sema)
+- [pagamento_dominio.sema](../exemplos/pagamento_dominio.sema)
+- [automacao.sema](../exemplos/automacao.sema)
+- [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
+- [crud_simples.sema](../exemplos/crud_simples.sema)
+
+O vertical oficial de pagamento deve ser tratado como a referência principal.
+
+## O que a IA não deve fazer
+
+- inventar palavras-chave fora da gramática
+- introduzir blocos inexistentes
+- 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 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
+
+## Estratégia recomendada
+
+Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
+
+1. [README.md](../README.md)
+2. [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
+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 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 não significa que a IA vai adivinhar sozinha.
+
+Ela entende bem quando recebe:
+
+- especificacao
+- exemplos
+- JSON estrutural
+- feedback automático
+
+Sem isso, até o modelo mais caro vira estagiário emocionado.