@semacode/cli 1.5.45 → 1.5.47

package/docs/comandos.md

@@ -0,0 +1,702 @@
+# Catalogo de comandos Sema
+
+Este documento e o mapa operacional da CLI Sema para IAs e humanos. Ele explica
+o que cada comando faz, quando usar e qual comando vem depois. Se um agente nao
+souber qual comando chamar, ele deve ler este arquivo antes de improvisar.
+
+## Regra curta para IA
+
+1. Em workspace local, comece por `sema --version`.
+2. Depois rode `sema preflight resumo --json`.
+3. Se a decisao for `use_cli_local`, rode `sema resumo`.
+4. Antes de editar, rode `sema docs-impacto --intencao "<acao>" --json`.
+5. Leia as docs obrigatorias retornadas.
+6. Use `sema inspecionar`, `sema drift` e `sema impacto` antes de mudar codigo.
+7. Se for criar ou corrigir `.sema`, use exemplos oficiais e finalize com `sema validar`.
+8. Se for implementar codigo a partir de contrato, rode `sema compilar` antes de escrever codigo manual.
+9. No fechamento, rode os gates aplicaveis e `sema finalizar-mudanca`.
+
+Nao substitua `validar`, `docs-impacto`, `inspecionar`, `drift`, `impacto`,
+`compilar` ou `finalizar-mudanca` por um relatorio Markdown escrito pela IA.
+Relatorio pode explicar evidencia; nao passa gate.
+
+## Fluxos minimos
+
+### Primeiro contato com projeto local
+
+```bash
+sema --version
+sema preflight resumo --json
+sema resumo
+sema docs-impacto --intencao "descrever a acao" --json
+```
+
+Use quando a IA acabou de abrir um workspace. Se `sema --version` falhar, pare:
+a IA nao acessa o painel Sema e nao deve trocar CLI local por MCP remoto.
+
+### Criar ou corrigir contrato
+
+```bash
+sema instalar-exemplos --json
+sema inspecionar contratos/<modulo>.sema --json
+sema formatar contratos/<modulo>.sema
+sema validar contratos/<modulo>.sema --json
+sema diagnosticos contratos/<modulo>.sema --json
+```
+
+Use exemplos oficiais antes de escrever sintaxe `.sema`. Se a CLI local nao
+tiver um comando `sema exemplos`, use `sema instalar-exemplos --json` para
+materializar exemplos no workspace e `sema exemplos-prompt-ia` para exemplos de
+prompt. Em MCP remoto, use `sema_exemplos`.
+
+### Implementar codigo derivado do contrato
+
+```bash
+sema compilar contratos/<modulo>.sema --alvo javascript --saida .tmp/sema-codigo
+sema testar contratos/<modulo>.sema --alvo javascript --saida .tmp/sema-testes
+sema drift contratos/<modulo>.sema --escopo modulo --json
+sema impacto contratos/<modulo>.sema --alvo <token> --mudanca "descrever a mudanca" --json
+```
+
+`sema compilar` satisfaz o gate Sema Codigo. Ele gera artefatos de apoio na
+pasta indicada por `--saida`. Essa pasta nao e automaticamente a entrega final.
+Depois de compilar, a IA precisa implementar ou ajustar os arquivos alvo
+declarados no contrato, como `index.html`, `css/styles.css` ou `js/app.js`.
+
+Se o gerador produzir um esqueleto TypeScript ou JavaScript mas o usuario pediu
+HTML/CSS/JS pronto no navegador, trate a saida gerada como referencia governada.
+Nao encerre a tarefa dizendo que a pasta `saida/` existe. A entrega so existe
+quando os vinculos do contrato existem fisicamente e passam nos gates.
+
+### Fechar mudanca
+
+```bash
+sema validar contratos/<modulo>.sema --json
+sema drift contratos/<modulo>.sema --escopo modulo --json
+sema impacto contratos/<modulo>.sema --alvo <token> --mudanca "descrever a mudanca" --json
+sema verificar contratos/<modulo>.sema --json
+sema finalizar-mudanca --intencao "descrever a acao" --doc-lida AGENTS.md --json
+```
+
+Use quando a implementacao, documentacao ou contrato ja foi alterado. Se algum
+gate bloquear, corrija antes de finalizar.
+
+## Comandos de boot e contexto
+
+### `sema --version`, `sema --versao`, `sema -v`
+
+Mostra a versao instalada da CLI. Em workspace local e o primeiro comando de
+prova. Se falhar, a IA deve parar e pedir instalacao da CLI pelo painel humano.
+
+Exemplo:
+
+```bash
+sema --version
+```
+
+### `sema preflight [comando] --json`
+
+Decide qual superficie deve ser usada antes de executar um comando. Em IDE local
+o resultado esperado e `decisao: "use_cli_local"`. Se vier outra decisao, pare.
+
+Exemplo:
+
+```bash
+sema preflight resumo --json
+```
+
+### `sema resumo <arquivo-ou-pasta>`
+
+Gera contexto IA-first do projeto, contrato ou modulo. Pode produzir resumo
+micro, curto ou medio e escrever artefatos em `.tmp`.
+
+Exemplo:
+
+```bash
+sema resumo . --curto --para mudanca --saida .tmp/sema-resumo --json
+```
+
+### `sema prompt-curto <arquivo-ou-pasta>`
+
+Gera um prompt compacto para outra IA continuar a tarefa com menos contexto.
+Use para transferir estado ou orientar agente fraco.
+
+Exemplo:
+
+```bash
+sema prompt-curto contratos/pedido.sema --micro --para bug --json
+```
+
+### `sema ajuda-ia`
+
+Imprime orientacao curta para agentes IA operarem Sema sem pular contrato,
+docs-impacto, drift e fechamento.
+
+Exemplo:
+
+```bash
+sema ajuda-ia
+```
+
+### `sema starter-ia`
+
+Mostra um starter operacional para agentes novos. Use quando o agente ainda nao
+conhece o ritual minimo do Sema.
+
+Exemplo:
+
+```bash
+sema starter-ia
+```
+
+### `sema contexto-ia <arquivo.sema>`
+
+Gera pacote de contexto para uma IA trabalhar em um contrato especifico. Pode
+criar resumo, briefing, drift, IR e AST conforme capacidade.
+
+Exemplo:
+
+```bash
+sema contexto-ia contratos/pedido.sema --saida .tmp/contexto-pedido --json
+```
+
+### `sema sync-ai-entrypoints`
+
+Sincroniza entrypoints de agentes, como `SEMA_BOOT.md`,
+`SEMA_SMALL_MODEL.md` e pacotes de contexto. Use quando regras de IA mudaram.
+
+Exemplo:
+
+```bash
+sema sync-ai-entrypoints --json
+```
+
+### `sema instalar-exemplos`
+
+Materializa exemplos oficiais `.sema` no workspace sem depender de busca solta
+no disco. Use antes de criar ou corrigir sintaxe de contrato.
+
+Exemplo:
+
+```bash
+sema instalar-exemplos --json
+```
+
+### `sema prompt-ia`
+
+Mostra prompt base para usar Sema com IA. E orientacao textual, nao gate.
+
+Exemplo:
+
+```bash
+sema prompt-ia
+```
+
+### `sema prompt-ia-ui`
+
+Mostra prompt voltado a tarefas com interface. Use quando o contrato envolve
+site, app, dashboard, jogo, painel ou qualquer entrega visual.
+
+Exemplo:
+
+```bash
+sema prompt-ia-ui
+```
+
+### `sema prompt-ia-react`
+
+Mostra prompt voltado a implementacao React. Use quando o alvo for React ou
+frontend componentizado.
+
+Exemplo:
+
+```bash
+sema prompt-ia-react
+```
+
+### `sema prompt-ia-sema-primeiro`
+
+Mostra prompt que reforca contrato antes de codigo. Use para agentes que tendem
+a sair codando sem Sema.
+
+Exemplo:
+
+```bash
+sema prompt-ia-sema-primeiro
+```
+
+### `sema exemplos-prompt-ia`
+
+Mostra exemplos de prompts para usar Sema com IA. Nao materializa exemplos
+`.sema`; para isso use `sema instalar-exemplos`.
+
+Exemplo:
+
+```bash
+sema exemplos-prompt-ia
+```
+
+## Comandos de contrato e descoberta
+
+### `sema iniciar --template <template>`
+
+Cria um esqueleto inicial de projeto Sema com contrato e docs basicas. E o
+caminho recomendado para projeto novo governado desde o inicio.
+
+Exemplo:
+
+```bash
+sema iniciar --template react-vite-consumer
+```
+
+### `sema init --template <nome> --saida <arquivo.sema> --modulo <nome>`
+
+Comando legado/modular para gerar um contrato a partir de template especifico.
+Use quando precisar de um arquivo `.sema` pontual.
+
+Exemplo:
+
+```bash
+sema init --template crud --saida contratos/produto.sema --modulo app.produto
+```
+
+### `sema init --listar`
+
+Lista templates disponiveis para `sema init`.
+
+Exemplo:
+
+```bash
+sema init --listar
+```
+
+### `sema validar <arquivo-ou-pasta>`
+
+Valida contratos `.sema`: sintaxe, regras, erros SEM e bloqueios. Todo contrato
+criado ou alterado deve passar por este comando.
+
+Exemplo:
+
+```bash
+sema validar contratos/pedido.sema --json
+```
+
+### `sema diagnosticos <arquivo.sema>`
+
+Mostra diagnosticos detalhados de um contrato. Use quando `validar` reprovar ou
+quando o contrato esta valido mas suspeito.
+
+Exemplo:
+
+```bash
+sema diagnosticos contratos/pedido.sema --json
+```
+
+### `sema formatar <arquivo-ou-pasta>`
+
+Formata contratos `.sema`. Com `--check`, apenas verifica se a formatacao esta
+correta.
+
+Exemplo:
+
+```bash
+sema formatar contratos/pedido.sema --check --json
+```
+
+### `sema inspecionar <arquivo-ou-pasta>`
+
+Carrega contratos e mostra modulos, tasks, routes, entidades, vinculos e
+arquivos esperados. Use antes de criar modulo, rota, task ou contrato e tambem
+para entender por que um score esta baixo.
+
+Exemplo:
+
+```bash
+sema inspecionar contratos --json
+```
+
+### `sema ast <arquivo.sema>`
+
+Mostra a AST do contrato. Use para depuracao profunda de parser ou sintaxe.
+
+Exemplo:
+
+```bash
+sema ast contratos/pedido.sema --json
+```
+
+### `sema ir <arquivo.sema>`
+
+Mostra a representacao intermediaria do contrato. Use para conferir o que os
+gates e geradores realmente enxergam.
+
+Exemplo:
+
+```bash
+sema ir contratos/pedido.sema --json
+```
+
+## Comandos de mudanca, drift e fechamento
+
+### `sema docs-impacto --intencao <acao>`
+
+Descobre quais docs precisam ser lidas ou criadas antes de uma mudanca. Se
+retornar docs ausentes ou bloqueios, resolva antes de editar codigo.
+
+Exemplo:
+
+```bash
+sema docs-impacto --intencao "criar controle de despesas" --json
+```
+
+### `sema drift <arquivo-ou-pasta>`
+
+Compara contrato e implementacao. Mostra divergencias, score e vinculos
+quebrados. Use antes e depois de editar codigo governado.
+
+Exemplo:
+
+```bash
+sema drift contratos/controle_despesas.sema --escopo modulo --json
+```
+
+### `sema impacto <arquivo-ou-pasta> --alvo <token>`
+
+Gera mapa de impacto semantico para uma mudanca. Use antes de alterar
+comportamento, API, contrato, dados, fluxo ou entrega visual.
+
+Exemplo:
+
+```bash
+sema impacto contratos/controle_despesas.sema --alvo controle_despesas.tela_principal --mudanca "implementar CRUD localStorage" --json
+```
+
+### `sema verificar <arquivo-ou-pasta>`
+
+Roda uma verificacao final agregada com validacao, geracao e testes possiveis.
+Use no fechamento, mas nao trate como substituto de teste real do projeto.
+
+Exemplo:
+
+```bash
+sema verificar contratos/controle_despesas.sema --saida .tmp/sema-verificar --json
+```
+
+### `sema finalizar-mudanca --intencao <acao>`
+
+Comprova leitura de docs obrigatorias e bloqueia fechamento com doc ausente,
+template cru ou diagnostico severo. Use antes de dizer que terminou.
+
+Exemplo:
+
+```bash
+sema finalizar-mudanca --intencao "implementar controle de despesas" --doc-lida AGENTS.md --doc-lida docs/comandos.md --json
+```
+
+## Comandos de Sema Codigo
+
+### `sema compilar <arquivo-ou-pasta> --alvo <alvo> --saida <diretorio>`
+
+Gera codigo/esqueleto a partir do contrato. Alvos aceitos: `typescript`,
+`python`, `dart`, `lua`, `javascript`, `html` e `css`.
+
+O `--saida` e a pasta de artefatos gerados. Ela pode ser `.tmp/sema-codigo`,
+`saida/`, `saida-ts/` ou outro diretorio. Essa pasta nao substitui os arquivos
+alvo do projeto, a menos que o proprio contrato declare esses arquivos dentro
+dela.
+
+Exemplo:
+
+```bash
+sema compilar contratos/controle_despesas.sema --alvo javascript --saida .tmp/sema-codigo --estrutura flat
+```
+
+Depois de compilar:
+
+- confira quais arquivos foram gerados;
+- use o esqueleto como referencia;
+- implemente os vinculos reais do contrato;
+- rode drift/impacto/testes;
+- nao finalize so porque `saida/` existe.
+
+### `sema gerar`
+
+Alias legado de `sema compilar`. Prefira `sema compilar` em docs e guardrails
+novos, porque e o nome usado pelo gate Sema Codigo.
+
+Exemplo:
+
+```bash
+sema gerar javascript contratos/pedido.sema --saida .tmp/sema-codigo
+```
+
+### `sema testar <arquivo.sema> --alvo <alvo> --saida <diretorio-temporario>`
+
+Gera e executa testes locais quando o alvo suporta. Use depois de `compilar` ou
+quando quiser validar o contrato com testes gerados.
+
+Exemplo:
+
+```bash
+sema testar contratos/controle_despesas.sema --alvo javascript --saida .tmp/sema-testes
+```
+
+Importante: `sema testar` nao substitui `sema compilar` quando o Guard exige o
+gate Sema Codigo. Se o bloqueio pede `sema compilar`, rode `compilar`.
+
+### `sema importar <fonte> <diretorio>`
+
+Importa estrutura de projeto legado e tenta gerar contratos iniciais. Fontes
+incluem `nestjs`, `fastapi`, `flask`, `nextjs`, `react-vite-consumer`,
+`angular-consumer`, `flutter-consumer`, `firebase`, `dotnet`, `java`, `go`,
+`rust`, `cpp`, `typescript`, `python` e `dart`.
+
+Exemplo:
+
+```bash
+sema importar typescript src --saida contratos/importados --namespace app.legado --json
+```
+
+### `sema renomear-semantico <arquivo-ou-pasta> --de <nome> --para <nome>`
+
+Ajuda a renomear simbolos semanticos preservando rastreabilidade entre contrato
+e codigo.
+
+Exemplo:
+
+```bash
+sema renomear-semantico contratos --de pedido_antigo --para pedido --escopo projeto --json
+```
+
+## Comandos de Author e profiles
+
+### `sema author iniciar`
+
+Cria contrato Author para texto governado. Use para obra, roteiro, lore,
+campanha ou escrita autoral.
+
+Exemplo:
+
+```bash
+sema author iniciar --preset roteiro --saida contratos/author.sema
+```
+
+### `sema author validar <arquivo.sema>`
+
+Valida contrato Author.
+
+Exemplo:
+
+```bash
+sema author validar contratos/author.sema --json
+```
+
+### `sema author briefing <arquivo.sema>`
+
+Gera briefing a partir do contrato Author.
+
+Exemplo:
+
+```bash
+sema author briefing contratos/author.sema --json
+```
+
+### `sema author revisar-cliches <arquivo.sema>`
+
+Procura cliches e bloqueios de estilo no texto. Reprova quando houver bloqueio.
+
+Exemplo:
+
+```bash
+sema author revisar-cliches contratos/author.sema --texto-arquivo capitulo.md --json
+```
+
+### `sema author validar-narrativa <arquivo.sema>`
+
+Valida continuidade narrativa, mudanca de estado e aderencia ao contrato Author.
+
+Exemplo:
+
+```bash
+sema author validar-narrativa contratos/author.sema --texto-arquivo cena.md --json
+```
+
+### `sema author validar-proibicoes <arquivo.sema>`
+
+Valida proibicoes literais e regras do contrato Author.
+
+Exemplo:
+
+```bash
+sema author validar-proibicoes contratos/author.sema --texto-arquivo cena.md --json
+```
+
+### `sema profile validar <profile> <arquivo-ou-pasta>`
+
+Valida artefato por perfil semantico. Profiles conhecidos: `software`,
+`workflow`, `ops`, `game`, `legal`, `research`, `redacao`, `propostas` e
+`conversas`.
+
+Exemplo:
+
+```bash
+sema profile validar propostas contratos/sema/propostas_comerciais.sema --maturidade production --preset score90 --artefato-arquivo proposta.md --json
+```
+
+### `sema profile capabilities`
+
+Lista capacidades e profiles disponiveis.
+
+Exemplo:
+
+```bash
+sema profile capabilities --json
+```
+
+### `sema rule-packs`
+
+Lista pacotes de regras por profile. Use para descobrir presets e criterios de
+validacao.
+
+Exemplo:
+
+```bash
+sema rule-packs --profile propostas --json
+```
+
+## Comandos MCP, chat e operacao
+
+### `sema mcp-instalar-chave --stdin`
+
+Instala chave local do MCP/controle quando o humano ja obteve o token pelo
+painel. A IA nao deve pedir segredo se ele ja foi instalado.
+
+Exemplo:
+
+```bash
+Get-Content token.txt | sema mcp-instalar-chave --stdin --json
+```
+
+### `sema chat doctor`
+
+Diagnostica runtimes locais para Sema Chat, especialmente OpenCode. Use quando a
+UI/chat local nao aparece ou quando precisa provar ambiente.
+
+Exemplo:
+
+```bash
+sema chat doctor --json
+```
+
+### `sema doctor`
+
+Diagnostica a instalacao local da CLI e dependencias operacionais. Use para
+separar erro de instalacao de erro de contrato.
+
+Exemplo:
+
+```bash
+sema doctor
+```
+
+### `sema mcp-client`
+
+Comando local que bloqueia uso indevido do MCP remoto em workspace com CLI. Ele
+existe para ensinar o agente a usar CLI local quando `sema --version` funciona.
+
+Exemplo:
+
+```bash
+sema mcp-client --json
+```
+
+### `sema bridge-config`
+
+Configura ponte local para endpoint MCP quando token e endpoint existem no
+ambiente. E operacional, nao substitui CLI local em workspace.
+
+Exemplo:
+
+```bash
+sema bridge-config --json
+```
+
+### `sema contexto-chat <contrato.sema>`
+
+Gera pacote inline/arquivo para chat remoto a partir de contratos selecionados.
+Use quando o contexto precisa sair do workspace local para uma IA sem acesso ao
+disco.
+
+Exemplo:
+
+```bash
+sema contexto-chat contratos/pedido.sema --json
+```
+
+### `sema guard <on|off|status>`
+
+Ativa, desativa ou consulta guarda local experimental da CLI. Nao confunda com
+SemaGuard/OpenCode/Electron, que e outro projeto.
+
+Exemplo:
+
+```bash
+sema guard status --json
+```
+
+### `sema dev`
+
+Modo de desenvolvimento para observar contratos e validar alteracoes. E
+operacional e mais util para desenvolvimento do Sema que para usuario final.
+
+Exemplo:
+
+```bash
+sema dev contratos
+```
+
+### `sema sync prisma`
+
+Integra contratos com Prisma: gera schema, importa schema ou compara
+divergencias.
+
+Exemplo:
+
+```bash
+sema sync prisma --comparar contratos prisma/schema.prisma
+```
+
+### `sema runner validar-remoto`
+
+Executa validacao remota real a partir de snapshot tipado. Cria workspace
+efemero, roda gates e publica relatorio auditavel. Use em infraestrutura de
+validacao remota, nao como atalho para workspace local.
+
+Exemplo:
+
+```bash
+sema runner validar-remoto --snapshot snapshot.json --saida .tmp/runner --json
+```
+
+### `sema runner servidor`
+
+Sobe servidor local do runner de validacao remota.
+
+Exemplo:
+
+```bash
+sema runner servidor --porta 8787 --saida .tmp/runner --json
+```
+
+## O que a IA nao deve fazer
+
+- Nao usar MCP remoto para ler workspace local quando a CLI funciona.
+- Nao procurar `.sema` no disco inteiro para aprender sintaxe; use exemplos
+  oficiais e docs do projeto.
+- Nao tratar `saida/` de `sema compilar` como entrega final.
+- Nao dizer que terminou so porque o bootstrap semantico passou.
+- Nao trocar `sema compilar` por `sema testar` quando o Guard pediu Sema Codigo.
+- Nao criar relatorio Markdown para fingir que rodou gate bloqueado.
+- Nao editar codigo sem contrato ou sem vinculo semantico aplicavel.
+- Nao finalizar sem explicar o que passou, o que bloqueou e qual evidencia foi
+  usada.

package/docs/env.md

@@ -24,13 +24,13 @@ Ambiente necessário para publicar a Sema.
 No PowerShell, o instalador recebe a versão por parametro:
 
 ```powershell
-.\install-sema.ps1 -Version 1.5.45 -WithVSCode
+.\install-sema.ps1 -Version 1.5.47 -WithVSCode
 ```
 
 No shell:
 
 ```bash
-SEMA_VERSION=1.5.45 ./install-sema.sh --with-vscode
+SEMA_VERSION=1.5.47 ./install-sema.sh --with-vscode
 ```
 
 ## Credenciais

package/docs/extensao-vscode.md

@@ -31,7 +31,7 @@ final.
 
 ```bash
 npm run extensao:empacotar
-code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.45.vsix --force
+code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.47.vsix --force
 ```
 
 ## Limites