@semacode/cli 0.9.0 → 1.1.0

package/docs/AGENT_STARTER.md

@@ -2,24 +2,53 @@
 
 Use este texto como starter curto para qualquer IA antes de editar `.sema`.
 
+Ordem canonica de entrada no repo:
+
+1. `llms.txt`
+2. `SEMA_BRIEF.md`
+3. `SEMA_INDEX.json`
+4. `AGENTS.md`
+5. `README.md`
+
+Roteamento por capacidade:
+
+- IA pequena ou gratuita: `llms.txt` -> `SEMA_BRIEF.micro.txt` -> `SEMA_INDEX.json`
+- IA media: `llms.txt` -> `SEMA_BRIEF.curto.txt` -> `SEMA_INDEX.json` -> `README.md`
+- IA grande ou com tool use: `llms-full.txt` -> `SEMA_BRIEF.md` -> `SEMA_INDEX.json` -> `AGENTS.md` -> `README.md`
+
+Tres modos de uso da Sema:
+
+- projeto novo: modele, valide, compile e verifique antes de subir codigo derivado
+- projeto ja semantizado: inspecione, leia resumo, rode drift e gere contexto antes de editar
+- legado sem Sema: importe, revise o rascunho, formate, valide e use drift como arbitro da adocao incremental
+
+Para manter os artefatos gerados da raiz sincronizados:
+
+- `sema sync-ai-entrypoints --json`
+
 ```text
-Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA e backend vivo.
+Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA sobre software vivo em backend e front consumer.
 
 Importante:
-- a Sema e protocolo de governanca semantica, nao gerador magico que deveria fazer tudo
-- a Sema modela contratos, estados, fluxos, erros, efeitos e garantias
+- a Sema e protocolo de governanca semantica desenhado para IA, nao para ergonomia humana
+- leitura humana e bonus toleravel, nao centro do produto
+- a Sema modela contratos, estados, fluxos, erros, efeitos, garantias, vinculos e execucao
 - a Sema gera codigo e scaffolding real para TypeScript, Python e Dart
 - a Sema usa `importar` para bootstrap revisavel, nao para contrato final automatico
 - a Sema usa `drift` para medir diferenca entre contrato e codigo vivo
 - a Sema usa `impl` para ligar task a simbolo real do runtime
+- a Sema usa `resumo` e `prompt-curto` para IA pequena ou gratuita
 - a Sema pode servir de base para interfaces graficas elegantes e coerentes
-- a Sema nao gera uma interface completa sozinha no estado atual
+- a primeira onda consumer oficial agora cobre `Next.js consumer`, `React/Vite consumer`, `Angular consumer` e `flutter-consumer`
+- esses slices oficiais cobrem `consumer bridge + superficies rastreaveis`, nao geracao completa de UI
+- a proxima camada semantica de front (`screen`, `action`, `query`, `form`, `navigation`) esta documentada como roadmap, nao como sintaxe oficial ja suportada
 - trate a Sema como cerebro semantico da aplicacao, nao como gerador magico de front-end pronto
-- se a tarefa envolver UI, prefira pedir Sema + React + TypeScript ou Sema + arquitetura de front-end
+- se a tarefa envolver UI, priorize `appRoutes`, `consumerSurfaces` e `consumerBridges` antes de abrir arquivo aleatorio
 - evite pedir HTML unico solto quando a intencao for testar a Sema de verdade
 
 Regras:
 - nao invente sintaxe fora da gramatica e dos exemplos oficiais
+- se a IA for pequena, comece em `sema resumo` e `briefing.min.json`
 - trate `ir --json` como fonte de verdade semantica
 - trate `diagnosticos --json` como fonte de correcao
 - use `sema formatar` como fonte unica de estilo
@@ -27,13 +56,15 @@ Regras:
 - nao cobre da Sema adivinhacao de negocio que nao esta no contrato nem no codigo
 
 Comandos essenciais:
+- resumo por capacidade: `sema resumo <arquivo-ou-pasta> [--micro|--curto|--medio] [--para <resumo|onboarding|review|mudanca|bug|arquitetura>]`
+- prompt curto: `sema prompt-curto <arquivo-ou-pasta> [--micro|--curto|--medio] [--para <resumo|onboarding|review|mudanca|bug|arquitetura>]`
 - contexto completo do modulo: `sema contexto-ia <arquivo.sema>`
 - estrutura sintatica: `sema ast <arquivo.sema> --json`
 - estrutura semantica: `sema ir <arquivo.sema> --json`
 - validacao: `sema validar <arquivo.sema> --json`
 - diagnosticos: `sema diagnosticos <arquivo.sema> --json`
 - formatacao: `sema formatar <arquivo.sema>`
-- importacao assistida de legado: `sema importar <nestjs|fastapi|flask|typescript|python|dart> <diretorio> --saida <diretorio>`
+- importacao assistida de legado: `sema importar <nestjs|fastapi|flask|nextjs|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|firebase|typescript|python|dart|dotnet|java|go|rust|cpp> <diretorio> --saida <diretorio>`
 - geracao de codigo: `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart> --saida <diretorio>`
 - verificacao final: `sema verificar <arquivo-ou-pasta> [--json]`
 
@@ -44,14 +75,15 @@ Regra pratica de ouro:
 
 Antes de editar:
 1. leia README, docs de IA e um exemplo oficial parecido
-2. consulte AST e IR do modulo alvo
+2. se a IA for pequena, rode `sema resumo <arquivo> --micro`
+3. se a tarefa pedir contexto mais rico, consulte `drift`, `briefing.min.json` e depois AST/IR
 
 Depois de editar:
 1. rode `sema formatar`
 2. rode `sema validar --json`
 3. se houver falha, use `diagnosticos --json`
 4. se a tarefa pedir codigo derivado, rode `sema compilar`
-5. feche com `sema verificar` ou `npm run project:check`
+5. feche com `sema verificar <arquivo-ou-pasta> --json`
 
 Priorize sempre:
 - exemplos oficiais

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

@@ -2,6 +2,8 @@
 
 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.
 
+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`.
+
 ## Principio central
 
 Uma IA entende uma linguagem nova quando recebe quatro camadas de contexto:
@@ -16,6 +18,7 @@ Sem essas quatro camadas, o modelo comeca a adivinhar. E adivinhacao em linguage
 Antes de qualquer outra coisa, a IA tambem precisa receber a **moldura correta**:
 
 - a Sema e um protocolo de governanca de intencao
+- a Sema foi feita para IA, nao para ergonomia humana
 - a Sema nao foi feita para "automatizar tudo"
 - a Sema existe para explicitar, alinhar e verificar contrato contra sistema vivo
 - curadoria humana continua parte da proposta
@@ -28,9 +31,9 @@ A IA precisa saber como a linguagem e escrita.
 
 Fontes principais:
 
-- [gramatica-inicial.md](./gramatica-inicial.md)
+- [README.md](../README.md)
 - [sintaxe.md](./sintaxe.md)
-- [gramatica.ebnf](../pacotes/nucleo/src/parser/gramatica.ebnf)
+- [integracao-com-ia.md](./integracao-com-ia.md)
 
 Objetivo dessa camada:
 
@@ -46,7 +49,7 @@ Depois de saber ler, a IA precisa saber o que cada bloco significa.
 Fontes principais:
 
 - [README.md](../README.md)
-- [especificacao-inicial.md](./especificacao-inicial.md)
+- [integracao-com-ia.md](./integracao-com-ia.md)
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
 Objetivo dessa camada:
@@ -68,22 +71,24 @@ Em vez de confiar que a IA vai interpretar `.sema` cru de primeira, use a CLI co
 Comandos principais:
 
 ```bash
-node pacotes/cli/dist/index.js validar arquivo.sema --json
-node pacotes/cli/dist/index.js diagnosticos arquivo.sema --json
-node pacotes/cli/dist/index.js ast arquivo.sema --json
-node pacotes/cli/dist/index.js ir arquivo.sema --json
-node pacotes/cli/dist/index.js verificar exemplos --json --saida ./.tmp/verificacao-ia
+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 semantico pequeno para IA com janela curta
 - `validar --json`: diz se a base esta 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
 - `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.
+Se a IA puder consumir `ir --json`, melhor ainda. E ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Mas nao seja um animal: para modelo pequeno, comece em `resumo` e `briefing.min.json`.
 
 ## Camada 4. Exemplos reais
 
@@ -97,7 +102,7 @@ Arquivos recomendados:
 - [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
 - [crud_simples.sema](../exemplos/crud_simples.sema)
 
-O vertical de pagamento do `0.5` deve ser tratado como a referencia principal.
+O vertical oficial de pagamento deve ser tratado como a referencia principal.
 
 ## O que a IA nao deve fazer
 
@@ -125,7 +130,8 @@ Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta o
 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. `ast --json`, `ir --json` e `diagnosticos --json` do modulo alvo
+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
 
 Essa ordem faz a IA ir de contexto geral para contexto operacional, em vez de cair direto num arquivo cru e sair chutando.
 

package/docs/fluxo-pratico-ia-sema.md

@@ -7,12 +7,13 @@ Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao
 ## Fluxo curto
 
 1. ler contexto do projeto
-2. identificar o modulo alvo
-3. consultar AST e IR
-4. editar
-5. formatar
-6. validar
-7. verificar
+2. identificar a capacidade da IA
+3. identificar o modulo alvo
+4. consultar o menor artefato semantico suficiente
+5. editar
+6. formatar
+7. validar
+8. verificar
 
 ## Fluxo detalhado
 
@@ -28,7 +29,15 @@ Se o trabalho estiver ligado a pagamento, ler tambem:
 
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
-### Etapa 2. Ler o modulo alvo e um exemplo parecido
+### 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 media: `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 modulo alvo e um exemplo parecido
 
 A IA deve identificar:
 
@@ -42,22 +51,23 @@ Regra pratica:
 - erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
 - borda publica e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
 
-### Etapa 3. Consultar AST e IR
+### Etapa 4. Consultar AST e IR quando fizer sentido
 
 Antes de alterar, a IA deve executar:
 
 ```bash
-node pacotes/cli/dist/index.js ast caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
+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
-- ver a forma semantica resolvida
+- ver a forma sintatica quando a capacidade aguentar
+- ver a forma semantica resolvida quando a capacidade aguentar
 - evitar interpretar errado o contrato
 
-### Etapa 4. Editar o `.sema`
+### Etapa 5. Editar o `.sema`
 
 Ao editar, a IA deve:
 
@@ -66,24 +76,24 @@ Ao editar, a IA deve:
 - evitar criar bloco ou operador nao suportado
 - preferir a forma ja usada nos exemplos oficiais
 
-### Etapa 5. Formatar
+### Etapa 6. Formatar
 
 Depois da edicao:
 
 ```bash
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema --check
+sema formatar caminho/arquivo.sema
+sema formatar caminho/arquivo.sema --check
 ```
 
 Se `--check` falhar, o trabalho ainda nao esta pronto.
 
-### Etapa 6. Validar e diagnosticar
+### Etapa 7. Validar e diagnosticar
 
 Depois da formatacao:
 
 ```bash
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js diagnosticos caminho\\arquivo.sema --json
+sema validar caminho/arquivo.sema --json
+sema diagnosticos caminho/arquivo.sema --json
 ```
 
 Se houver falha:
@@ -91,12 +101,12 @@ Se houver falha:
 - usar os diagnosticos estruturados como contrato de correcao
 - nao insistir em leitura manual teimosa quando a CLI ja disse onde esta a merda
 
-### Etapa 6.5. Compilar quando a tarefa pedir codigo derivado
+### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
 
 Se a tarefa nao for so editar contrato, mas tambem gerar base de implementacao, a IA deve rodar explicitamente:
 
 ```bash
-node pacotes/cli/dist/index.js compilar caminho\\arquivo.sema --alvo typescript --saida .\\saida\\typescript
+sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
 ```
 
 Ou trocar o alvo para `python` ou `dart`, conforme o caso.
@@ -106,28 +116,22 @@ Regra pratica:
 - se a entrega inclui codigo derivado, `sema compilar` nao e opcional
 - se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema ja gera sozinha, que e burrice operacional
 
-### Etapa 7. Verificar
+### Etapa 8. Verificar
 
 No fechamento:
 
 ```bash
-node pacotes/cli/dist/index.js verificar exemplos --json --saida ./.tmp/verificacao-ia
-```
-
-Ou, no fluxo consolidado do projeto:
-
-```bash
-npm run project:check
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
 ```
 
 ## Fluxo minimo para automacao
 
-Se voce quiser o menor fluxo aceitavel para uma IA:
+Se voce quiser o menor fluxo aceitavel para uma IA pequena:
 
 ```bash
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
+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`.
@@ -135,10 +139,10 @@ Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
 Se a tarefa envolver codigo derivado, o fluxo minimo aceitavel vira:
 
 ```bash
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js compilar caminho\\arquivo.sema --alvo typescript --saida .\\saida\\typescript
+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 saida
@@ -170,4 +174,4 @@ Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so
 
 ## Observacao sobre caminhos
 
-Esta documentacao usa caminhos relativos ao repositorio, nao caminhos locais de maquina. Isso permite que qualquer pessoa clone o projeto e use os links e referencias sem depender de uma pasta especifica no proprio ambiente.
+Esta documentacao usa placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.

package/docs/instalacao-e-primeiro-uso.md

@@ -0,0 +1,196 @@
+# Instalacao e Primeiro Uso
+
+Este guia mostra o caminho mais curto para testar a Sema do jeito certo, sem misturar fluxo de usuario com gambiarra de contribuinte.
+
+## Requisitos
+
+- Node.js instalado
+- npm funcionando
+- Python 3 e `pytest` se voce quiser rodar o fluxo completo de testes Python gerados
+
+O repositorio so e necessario se voce quiser contribuir na Sema, rodar o showcase oficial localmente ou empacotar release.
+
+## Caminho oficial
+
+Instalacao via npm:
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+Se preferir o tarball oficial da GitHub Release:
+
+```bash
+npm install -g https://github.com/gerlanss/Sema/releases/latest/download/sema-cli-latest.tgz
+sema --help
+sema doctor
+```
+
+Instalacao local ao projeto:
+
+```bash
+npm install @semacode/cli
+npx sema --help
+```
+
+Instaladores auxiliares para a linha publica atual:
+
+- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.sh | bash`
+- Windows PowerShell: `irm https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.ps1 | iex`
+
+Se voce quiser reproducao estrita, prefira o npm registry ou o tarball da GitHub Release.
+
+## Primeiro teste sem clonar o repo
+
+```bash
+mkdir sema-demo
+cd sema-demo
+sema iniciar
+sema validar contratos/pedidos.sema --json
+```
+
+## Primeiro fluxo util
+
+```bash
+sema validar contratos/pedidos.sema --json
+sema ast contratos/pedidos.sema --json
+sema ir contratos/pedidos.sema --json
+sema formatar contratos/pedidos.sema
+sema verificar contratos --saida ./.tmp/verificacao
+```
+
+## Primeiro fluxo de IA real
+
+Sem clonar o repo, o fluxo que mais mostra a proposta da Sema hoje e:
+
+```bash
+sema inspecionar . --json
+sema resumo contratos/pedidos.sema --micro --para mudanca
+sema drift contratos/pedidos.sema --json
+sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
+```
+
+Esse fluxo mostra:
+
+- base de projeto resolvida
+- cartao semantico curto para IA pequena ou gratuita
+- codigo vivo detectado
+- `impl` e `vinculos` resolvidos
+- score, confianca e lacunas do `drift`
+- `briefing.min.json` e `briefing.json` para IA antes da edicao
+
+## `sema.config.json`
+
+Exemplo de configuracao para projeto real:
+
+```json
+{
+  "origens": ["./contratos"],
+  "saida": "./generated",
+  "alvos": ["typescript", "python"],
+  "alvoPadrao": "typescript",
+  "estruturaSaida": "backend",
+  "framework": "nestjs",
+  "modoEstrito": true,
+  "diretoriosSaidaPorAlvo": {
+    "typescript": "./generated/nestjs",
+    "python": "./generated/fastapi"
+  },
+  "convencoesGeracaoPorProjeto": "backend"
+}
+```
+
+## Gerar codigo
+
+Scaffold base:
+
+```bash
+sema compilar contratos/pedidos.sema --alvo typescript --saida ./saida/typescript
+sema compilar contratos/pedidos.sema --alvo python --saida ./saida/python
+sema compilar contratos/pedidos.sema --alvo dart --saida ./saida/dart
+```
+
+Scaffold backend:
+
+```bash
+sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
+sema compilar contratos/pedidos.sema --alvo python --framework fastapi --estrutura backend --saida ./generated/fastapi
+```
+
+## Extensao VS Code
+
+Via GitHub Release:
+
+```bash
+curl -L -o sema-language-tools.vsix https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix
+code --install-extension ./sema-language-tools.vsix --force
+```
+
+Windows PowerShell:
+
+```powershell
+Invoke-WebRequest -Uri https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix -OutFile sema-language-tools.vsix
+code --install-extension .\sema-language-tools.vsix --force
+```
+
+Pagina oficial:
+
+- [https://github.com/gerlanss/Sema/releases/latest](https://github.com/gerlanss/Sema/releases/latest)
+
+Se voce estiver desenvolvendo a propria extensao localmente, ai sim entra a trilha de contribuinte:
+
+```bash
+npm run extensao:empacotar
+npm run extensao:instalar-local
+```
+
+## Caminho de contribuinte
+
+Se o objetivo for desenvolver a propria Sema:
+
+```bash
+npm install
+npm run build
+npm run cli:instalar-local
+sema validar exemplos/calculadora.sema
+```
+
+Se quiser validar tudo de cara:
+
+```bash
+npm run project:check
+```
+
+## `npm link` continua existindo
+
+Esse fluxo continua util, mas e trilha de contribuinte:
+
+```powershell
+npm run cli:instalar-local
+```
+
+Serve para:
+
+- testar a experiencia de terminal no proprio ambiente
+- desenvolver a CLI
+- usar `sema` como interface principal mesmo durante o desenvolvimento local
+
+Para remover:
+
+```powershell
+npm run cli:desinstalar-local
+```
+
+## Resumo honesto
+
+Hoje o jeito certo de testar a Sema e:
+
+1. instalar a CLI pelo npm ou pela GitHub Release
+2. rodar `sema iniciar`
+3. validar `contratos/pedidos.sema`
+4. usar `inspecionar -> resumo -> drift -> contexto-ia` quando o projeto for vivo
+5. ler `briefing.min.json` ou `briefing.json` antes de mandar a IA sair cavando arquivo
+
+Clone + build + `npm link` continua bom para oficina, nao para landing page publica.