@semacode/cli 1.5.48 → 1.5.53

package/docs/comandos.md

@@ -1,807 +0,0 @@
-<!-- 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.