@semacode/cli 1.5.46 → 1.5.48

package/docs/comandos.md

@@ -0,0 +1,807 @@
+<!-- sema:agent-entrypoint:start -->
+# Catalogo de comandos Sema
+
+Use este arquivo quando a IA nao souber qual comando chamar. Comando Sema e gate operacional; nao substitua por relatorio Markdown.
+
+## Fluxo minimo local
+
+```bash
+sema --version
+sema preflight resumo --json
+sema resumo
+sema docs-impacto --intencao "<acao>" --json
+```
+
+Depois leia as docs obrigatorias retornadas por `docs-impacto`.
+
+## Contrato e descoberta
+
+- `sema iniciar --template <template>`: cria projeto Sema novo com contrato, docs, exemplos e kit IA.
+- `sema validar <arquivo-ou-pasta> --json`: valida contrato `.sema`.
+- `sema diagnosticos <arquivo.sema> --json`: detalha erros e avisos.
+- `sema formatar <arquivo-ou-pasta>`: formata contrato.
+- `sema inspecionar <arquivo-ou-pasta> --json`: mostra modulos, tasks, routes, entidades, vinculos e arquivos esperados.
+- `sema ast <arquivo.sema> --json`: mostra AST para depurar sintaxe.
+- `sema ir <arquivo.sema> --json`: mostra a IR que os gates e geradores enxergam.
+
+## Mudanca e fechamento
+
+- `sema docs-impacto --intencao "<acao>" --json`: descobre docs obrigatorias e bloqueios documentais.
+- `sema drift <arquivo-ou-pasta> --escopo modulo --json`: compara contrato e implementacao.
+- `sema impacto <arquivo-ou-pasta> --alvo <token> --mudanca "<descricao>" --json`: mapeia impacto antes de alterar comportamento.
+- `sema verificar <arquivo-ou-pasta> --json`: verificacao final agregada.
+- `sema finalizar-mudanca --intencao "<acao>" --doc-lida <arquivo> --json`: comprova leitura documental antes de concluir.
+
+Fechamento honesto: trate o JSON do drift como fonte de verdade. `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes` ou impls quebradas significam que a mudanca ainda nao esta concluida. Nao relate "drift limpo" sem esse JSON verde.
+
+## Sema Codigo
+
+- `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua|javascript|html|css> --saida <diretorio>`: gera esqueleto/artefatos de apoio a partir do contrato.
+- `sema testar <arquivo.sema> --alvo <alvo> --saida <diretorio-temporario>`: gera e executa testes locais quando o alvo suporta.
+- `sema importar <fonte> <diretorio> --saida <diretorio> --json`: importa projeto legado para contratos iniciais.
+- `sema renomear-semantico <arquivo-ou-pasta> --de <nome> --para <nome> --json`: ajuda a renomear simbolos semanticamente.
+
+Regra de `--saida`: a pasta informada em `sema compilar --saida` e saida gerada. Ela nao e entrega final por si so. A entrega final sao os arquivos alvo/vinculos declarados no contrato. Se o contrato pede `index.html`, `css/styles.css` e `js/app.js`, criar apenas `saida/controle_despesas.ts` nao conclui a tarefa.
+
+Regra de rastreabilidade do Sema Codigo: os artefatos gerados devem apontar o modulo/contrato de origem e preservar que um mesmo arquivo final pode ser governado por varios contratos `.sema` via `vinculos`. Nao force relacao 1:1 contrato-arquivo e nao trate `saida/` como projeto final.
+
+Regra de UI pronta: se a tarefa gerar app, site, dashboard, formulario ou HTML estatico, rode validacao visual desktop/mobile quando a superficie permitir. Em mobile estreito (ex. 390px), `scrollWidth <= clientWidth` precisa passar; layout que empilha mas estoura horizontalmente nao e responsivo.
+
+## Listas canonicas de sintaxe
+
+- Origens de `use` e `impl`: `ts/typescript`, `js/javascript`, `py/python`, `dart`, `lua`, `cs/dotnet`, `java`, `go`, `rust`, `cpp`.
+- Categorias frequentes de `effects`: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.
+- Valores aceitos em `audit.motivo`: `obrigatorio`, `opcional`, `dispensado`.
+
+`sema compilar --alvo javascript` e alvo de geracao. `impl { js: ... }` e origem do codigo vivo. Nao troque um pelo outro.
+
+## IA e contexto
+
+- `sema ajuda-ia`: orientacao curta para agentes.
+- `sema starter-ia`: starter de operacao.
+- `sema contexto-ia <arquivo.sema> --saida <dir> --json`: pacote de contexto para IA.
+- `sema prompt-curto <arquivo-ou-pasta> --json`: prompt compacto.
+- `sema sync-ai-entrypoints --json`: sincroniza AGENTS, boot, pack e docs locais.
+- `sema instalar-exemplos --json`: instala exemplos oficiais no workspace.
+- `sema exemplos-prompt-ia`: mostra exemplos de prompts, nao exemplos `.sema`.
+
+## Profiles e Author
+
+- `sema author iniciar|validar|briefing|revisar-cliches|validar-narrativa|validar-proibicoes`: governa escrita autoral.
+- `sema profile validar <software|workflow|ops|game|legal|research|redacao|propostas|conversas> <arquivo> --json`: valida artefato por profile.
+- `sema profile capabilities --json`: lista profiles/capacidades.
+- `sema rule-packs --profile <profile> --json`: lista pacotes de regras.
+
+## Operacional
+
+- `sema doctor`: diagnostica instalacao local.
+- `sema chat doctor --json`: diagnostica Sema Chat/OpenCode local.
+- `sema mcp-instalar-chave --stdin --json`: instala chave obtida pelo humano no painel.
+- `sema runner validar-remoto --snapshot <arquivo.json|-> --saida <dir> --json`: validacao remota por snapshot.
+
+## Proibido
+
+- Nao usar rota remota, sincronizacao externa ou leitura por espelho para ler workspace local quando `sema --version` funciona.
+- Nao procurar `.sema` no disco inteiro para aprender sintaxe; use `exemplos/`, `docs/sintaxe.md` e este catalogo.
+- Nao encerrar depois de `sema compilar` se os arquivos alvo do contrato ainda nao existem.
+- Nao trocar `sema compilar` por `sema testar` quando o Guard pede Sema Codigo.
+- Nao criar relatorio Markdown para fingir que rodou gate.
+- Nao dizer que drift passou quando `sema drift --json` retornou `sucesso:false`, vinculo quebrado, rota divergente ou impl quebrada.
+- Nao declarar UI responsiva sem prova mobile/desktop; scroll horizontal em 390px bloqueia.
+
+Politica de codigo governado: Arquivos de codigo gerados ou governados pela Sema devem manter cabecalho curto com modulo de origem, contrato .sema aplicavel e descricao humana. Validacao inline prova apenas o payload enviado; o arquivo fisico ainda precisa de SEMA-GOVERNED para orientar a proxima IA. Codigo governado avisa acima de 1000 linhas e bloqueia acima de 2000. Contrato .sema avisa acima de 300 linhas e bloqueia criacao, edicao, drift, finalizacao, geracao e snapshot acima de 500. O split de .sema deve ser por dominio/capacidade, nunca parte_1/parte_2; varios contratos podem governar o mesmo arquivo de codigo via vinculos. Sema Codigo deve preservar essa rastreabilidade em cabecalhos e saidas geradas. Documentacao Markdown nao entra nesse limite de codigo; continua governada por docs-impacto, limite de bytes e verificacao de segredos. Payload inline acima de 262144 caracteres nao e caso de aumentar timeout: divida por responsabilidade ou use anexo/caminho de servidor autorizado.
+<!-- sema:agent-entrypoint:end -->
+
+# 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.
+
+### Listas canonicas que a IA deve usar
+
+- Origens de `use` e `impl`: `ts/typescript`, `js/javascript`, `py/python`, `dart`, `lua`, `cs/dotnet`, `java`, `go`, `rust`, `cpp`.
+- Categorias frequentes de `effects`: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.
+- Valores aceitos em `audit.motivo`: `obrigatorio`, `opcional`, `dispensado`.
+
+`sema compilar --alvo javascript` e alvo de geracao. `impl { js: ... }` e
+origem do codigo vivo. Se o projeto e JavaScript puro, declare `impl { js: ... }`
+ou `impl { javascript: ... }`, nao force `ts:` so porque o gerador ou o parser
+usa TypeScript internamente.
+
+### 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.