@semacode/cli 1.5.47 → 1.5.52

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

@@ -1,30 +0,0 @@
-# Como Ensinar a Sema para IA
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final.
-
-## English
-
-Sema is taught to an AI through operational context, not through vague explanations. The agent needs syntax, semantics, intermediate representation, examples, and the project contract before it touches code or documents.
-
-In local IDEs, the first step is to confirm that `AGENTS.md` exists in the project root and run `sema --version`. If the command is missing, stop and ask the human to open the Sema panel and run the key installer. Then run `sema preflight resumo --json`; if the decision is not `use_cli_local`, stop. With CLI authorized, run `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, and `sema impacto` locally. Do not call remote MCP, `sema_sync`, `sema_contratos_sincronizar`, or `sema mcp-client` to read a local workspace. In web chats, do not download files into the chat environment; call `sema_chat_contexto` and then `sema_sync` with contract, selected code, operational docs, and an index.
-
-The correct framing is simple: contract first, evidence before action, and no guessing from raw code when Sema can provide summary, drift, impact, and required docs.
-
-## Português
-
-A Sema é ensinada para IA por contexto operacional, não por explicação vaga. O agente precisa de sintaxe, semântica, representação intermediária, exemplos e contrato do projeto antes de tocar código ou documentos.
-
-Em IDE local, o primeiro passo é confirmar que `AGENTS.md` existe na raiz do projeto e rodar `sema --version`. Se o comando não existir, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel e rodar o instalador de chave. Depois rode `sema preflight resumo --json`; se a decisão não for `use_cli_local`, pare. Com CLI autorizada, rode `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift` e `sema impacto` localmente. Não chame MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local. Em chats web, não baixe arquivos no ambiente do chat; chame `sema_chat_contexto` e depois `sema_sync` com contrato, código selecionado, docs operacionais e índice.
-
-A moldura correta é simples: contrato primeiro, evidência antes da ação e nada de adivinhar lendo código cru quando a Sema pode entregar resumo, drift, impacto e docs obrigatórias.
-
-## Español
-
-Sema se enseña a una IA con contexto operativo, no con explicaciones vagas. El agente necesita sintaxis, semántica, representación intermedia, ejemplos y contrato del proyecto antes de tocar código o documentos.
-
-En una IDE local, el primer paso es confirmar que `AGENTS.md` existe en la raíz del proyecto y ejecutar `sema --version`. Si el comando no existe, para y pide al humano que abra el panel Sema y ejecute el instalador de clave. Después ejecuta `sema preflight resumo --json`; si la decisión no es `use_cli_local`, para. Con la CLI autorizada, ejecuta `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift` y `sema impacto` localmente. No llames el MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ni `sema mcp-client` para leer un workspace local. En chats web, no descargues archivos en el entorno del chat; llama `sema_chat_contexto` y después `sema_sync` con contrato, código seleccionado, docs operativas e índice.
-
-El encuadre correcto es simple: contrato primero, evidencia antes de la acción y nada de adivinar leyendo código crudo cuando Sema puede entregar resumen, drift, impacto y docs obligatorias.

package/docs/documentacao.md

@@ -1,74 +0,0 @@
-# Governança De Documentação
-
-A Sema trata documentação como parte da mudança. README, runbook, contrato,
-instrução para IA, guia de CLI, deploy e rollback não são enfeites: são
-superfícies governadas.
-
-Antes de uma IA editar contrato, código, configuração, workflow, deploy, texto
-Author, regra de jogo, nota jurídica, pesquisa, operação ou README, ela precisa
-resolver qual documentação explica a intenção da mudança.
-
-## Idioma
-
-Documentação interna da Sema é em PT-BR por padrão, com acentos preservados e
-sem mojibake. Inglês e espanhol não são obrigatórios em documento privado.
-
-Documentação multilíngue só entra quando a superfície for externa ou quando o
-contrato pedir explicitamente outro idioma. Comandos, identificadores, caminhos,
-variáveis, endpoints, pacotes e símbolos `.sema` continuam literais.
-
-## Trava Operacional
-
-```bash
-sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
-```
-
-O resultado informa:
-
-- `leituraObrigatoria`: documentos, READMEs e contratos que precisam ser lidos;
-- `docsAusentes`: documentação que bloqueia a mudança;
-- `docsCriadas`: esqueletos criados automaticamente quando autorizado;
-- `bloqueios`: diagnósticos de severidade 4.
-
-Documento criado automaticamente é rascunho. A IA precisa trocar template
-genérico por procedimento real, validação real e rollback real antes de
-considerar a mudança fechada.
-
-## Fechamento
-
-Antes de dizer que terminou, o agente roda:
-
-```bash
-sema finalizar-mudanca \
-  --intencao "criar rota de pagamento" \
-  --doc-lida README.md \
-  --doc-lida docs/documentacao.md \
-  --json
-```
-
-Se houver leitura obrigatória não comprovada, documento ausente, template cru ou
-diagnóstico de severidade 4, a mudança não está concluída.
-
-## Regra Para README
-
-O README principal deste repositório é manual interno. Ele deve explicar o Sema
-com profundidade suficiente para uma IA local operar sem inventar fluxo:
-
-- superfície CLI local;
-- superfície MCP remoto;
-- pré-checagem e SEMAS;
-- contratos `.sema`;
-- desvio semântico e impacto;
-- geração automática de código;
-- importação de legado;
-- templates de projeto novo;
-- contexto IA;
-- profiles;
-- Author;
-- documentação como trava;
-- comandos de sanidade;
-- fronteira privada.
-
-Se uma função importante existe na CLI, o README deve descrevê-la ou apontar
-para a documentação específica. README curto demais vira convite para IA
-apressada fazer besteira com confiança.

package/docs/extensao-vscode.md

@@ -1,49 +0,0 @@
-# Extensão VS Code
-
-A extensão VS Code faz parte do fluxo privado da Sema. Ela ajuda humanos e IAs
-em IDE local a escrever contratos `.sema`, receber feedback rápido e manter o
-projeto preso ao fluxo correto: CLI local primeiro, contrato antes de código e
-fechamento governado.
-
-Esta extensão é o **Sema Guard**. Ela é guarda, diagnóstico e apoio de autoria.
-Ela não é o Sema Chat, não deve ser tratada como produto principal de chat e não
-deve virar gambiarra visual em cima de botões. O Sema Chat local nasce sobre o
-runtime OpenCode, documentado em
-[`docs/sema-chat-opencode.md`](./sema-chat-opencode.md).
-
-Ela não substitui o painel, a chave local, a CLI, o MCP remoto nem a validação
-final.
-
-## Fluxo Obrigatório
-
-1. Abrir o projeto no VS Code.
-2. Ler `AGENTS.md`.
-3. Rodar `sema --version`.
-4. Se o comando não existir, parar. A IA não acessa o painel Sema: peça ao
-   humano para abrir o painel e rodar o instalador de chave/CLI.
-5. Rodar `sema preflight resumo --json` e exigir `use_cli_local`.
-6. Editar ou criar o contrato `.sema` aplicável antes de alterar código.
-7. Usar a extensão para autoria, snippets, hover, formatação e diagnóstico.
-8. Fechar pela CLI com `validar`, `drift`, `impacto`, testes e
-   `finalizar-mudanca`.
-
-## Empacotar E Instalar Localmente
-
-```bash
-npm run extensao:empacotar
-code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.47.vsix --force
-```
-
-## Limites
-
-A extensão não deve:
-
-- fingir que é chat visual;
-- substituir o runtime OpenCode do Sema Chat;
-- tratar `sema chat doctor --json` como produto final;
-- instalar chave sozinha;
-- consultar o painel como se fosse humano;
-- usar MCP remoto para ler workspace local;
-- publicar pacote;
-- dizer que uma mudança está concluída sem CLI;
-- substituir contrato por README ou comentário de código.

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

@@ -1,215 +0,0 @@
-# Fluxo Pratico para IA Antes de Editar `.sema`
-
-<!-- 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 descreve o fluxo operacional recomendado para qualquer IA antes, durante e depois de alterar arquivos `.sema`.
-
-Se a IA seguir isso, ela trabalha com contexto. Se não seguir, vira adivinhação gourmet.
-
-O ponto central: Sema não é texto para agradar humano. É contrato semântico IA-first. Humanos autorizam e revisam; a IA consome o contrato para decidir o próximo movimento.
-
-Antes de qualquer etapa, classifique a capacidade operacional do agente:
-
-- IA fraca: leia `SEMA_BOOT.md`, `SEMA_SMALL_MODEL.md` e `SEMA_BRIEF.micro.txt`; se Sema não responder, pare.
-- IA média: leia `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt` e `SEMA_INDEX.json`.
-- IA forte: pode usar `SEMA_BRIEF.md`, AST, IR e drift completo, mas ainda começa pelo boot.
-
-Regra de idioma humano: responda no idioma do usuário. Em PT-BR, use acentos, cedilha, pontuação e símbolos normais. A gramática `.sema` pode ser ASCII; texto humano não precisa ser.
-
-Regra de timeout: timeout local do agente não é falha do Sema. Se `sema resumo`, `drift`, `docs-impacto` ou outro gate estourar, aumente o timeout e tente de novo antes de declarar bloqueio. Para projeto grande, escopo menor vem primeiro: `sema resumo caminho/arquivo.sema --micro --para mudanca`.
-
-## Superfície obrigatória
-
-1. IDE local com workspace no disco: rode `sema --version`; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para instalar pelo painel. Depois rode `sema preflight resumo --json`. Se `decisao` não for `use_cli_local`, pare bloqueado.
-2. IDE local autorizada: use somente a CLI local para `resumo`, `docs-impacto`, `inspecionar`, `drift`, `impacto`, `validar`, `verificar` e `finalizar-mudanca`.
-3. IDE local proibida: não chame MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler o workspace local.
-4. Web/chat/remoto sem workspace local: use `sema_chat_contexto`, depois `sema_sync` inline com contrato `.sema`, código selecionado, documentação operacional e índice; use o `projeto` retornado.
-5. Se a IA não consegue identificar se está em IDE local ou web/chat remoto, ela deve parar e declarar bloqueio. Não invente superfície.
-
-## Fluxo curto
-
-1. identificar a superfície: CLI local ou MCP remoto web/chat
-2. em IDE local, rodar `sema --version`; se falhar, parar. A IA não acessa o painel Sema: pedir ao humano para instalar pelo painel; depois rodar `sema preflight resumo --json` e parar se não retornar `use_cli_local`
-3. ler contexto do projeto
-4. identificar a capacidade da IA
-5. identificar o módulo alvo
-6. consultar o menor artefato semântico suficiente
-7. editar
-8. formatar
-9. validar
-10. verificar
-
-## Fluxo detalhado
-
-### Etapa 1. Ler contexto mínimo
-
-Antes de tocar em qualquer arquivo, a IA deve ler:
-
-- [README.md](../README.md)
-- [integração-com-ia.md](./integracao-com-ia.md)
-- [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
-
-Se o trabalho estiver ligado a pagamento, ler também:
-
-- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
-
-### Etapa 2. Escolher a faixa de capacidade
-
-Antes de despejar contexto na IA, escolha o que ela aguenta:
-
-- IA fraca, gratuita ou com pouca disciplina: `sema preflight resumo --json`, `SEMA_BOOT.md`, `SEMA_SMALL_MODEL.md`, `sema resumo --micro` e `briefing.min.json`
-- IA média: `sema preflight resumo --json`, `sema resumo --curto`, `briefing.min.json` e `drift.json`
-- IA forte: `sema preflight resumo --json`, `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-Se qualquer comando Sema acima estourar timeout definido pela própria IA, ela deve aumentar o timeout e repetir. Timeout do agente não autoriza pular Sema nem concluir que a sessão está inativa.
-
-### Etapa 3. Ler o módulo alvo e um exemplo parecido
-
-A IA deve identificar:
-
-- qual arquivo sera editado
-- qual módulo esse arquivo representa
-- qual exemplo oficial mais se parece com o que precisa ser feito
-
-Regra pratica:
-
-- automacao: [automacao.sema](../exemplos/automacao.sema)
-- erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
-- borda pública e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
-
-### Etapa 4. Consultar AST e IR quando fizer sentido
-
-Antes de alterar, a IA deve executar:
-
-```bash
-sema --version
-sema preflight resumo --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 quando a capacidade aguentar
-- ver a forma semântica resolvida quando a capacidade aguentar
-- evitar interpretar errado o contrato
-
-### Etapa 5. Editar o `.sema`
-
-Ao editar, a IA deve:
-
-- preservar a intenção do módulo
-- seguir a gramática existente
-- evitar criar bloco ou operador não suportado
-- preferir a forma já usada nos exemplos oficiais
-- usar blocos existentes como `auth`, `authz`, `dados`, `audit`, `forbidden`, `execucao`, `use`, `state` e `enum` antes de propor sintaxe nova
-- evitar teste fraco em task sensível; `expect { sucesso: verdadeiro }` sozinho não prova semântica operacional
-
-### Etapa 6. Formatar
-
-Depois da edição:
-
-```bash
-sema formatar caminho/arquivo.sema
-sema formatar caminho/arquivo.sema --check
-```
-
-Se `--check` falhar, o trabalho ainda não está pronto.
-
-### Etapa 7. Validar e diagnosticar
-
-Depois da formatacao:
-
-```bash
-sema validar caminho/arquivo.sema --json
-sema diagnosticos caminho/arquivo.sema --json
-```
-
-Se houver falha:
-
-- usar os diagnósticos estruturados como contrato de correcao
-- não insistir em leitura manual teimosa quando a CLI já disse onde está a merda
-
-### Etapa 7.5. Compilar quando a tarefa pedir código derivado
-
-Se a tarefa não for só editar contrato, mas também gerar base de implementacao, a IA deve rodar explicitamente:
-
-```bash
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-Ou trocar o alvo para `python`, `dart`, `lua`, `javascript`, `html` ou `css`, conforme o caso.
-
-Regra pratica:
-
-- se a entrega inclui código derivado, `sema compilar` não é opcional
-- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema já gera sozinha, que é burrice operacional
-
-### Etapa 8. Verificar
-
-No fechamento:
-
-```bash
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-## Fluxo mínimo para automacao
-
-Se voce quiser o menor fluxo aceitavel para uma IA fraca:
-
-```bash
-sema --version
-sema preflight resumo --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`.
-
-Se a tarefa envolver código derivado, o fluxo mínimo aceitavel vira:
-
-```bash
-sema --version
-sema preflight resumo --json
-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 saída
-
-Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
-
-- eu entendi o módulo e o contrato?
-- eu mantive a sintaxe dentro do que a linguagem suporta?
-- eu formatei o arquivo?
-- eu validei?
-- eu olhei diagnósticos se algo falhou?
-- eu fechei com verificação?
-
-Se alguma resposta for "não", ainda não terminou.
-
-## Regra de ouro
-
-Em Sema, a IA não deveria operar no escuro.
-
-Ela deve trabalhar sempre com:
-
-- exemplo oficial
-- AST
-- IR
-- diagnósticos
-- formatador
-
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e não só no discurso bonito.
-
-## Observacao sobre caminhos
-
-Está documentação usa placeholders de arquivo e pasta, não caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface pública principal.

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

@@ -1,60 +0,0 @@
-# Instalação e Primeiro Uso
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final.
-
-## English
-
-Sema is private. Local IDEs use the complete Sema CLI. Web/chat clients without local workspace access use the remote MCP.
-
-In a local IDE, keep `AGENTS.md` in the project root and run `sema --version`. If the command is missing, stop and ask the human to open the Sema panel, download/run the key installer, and repeat `sema --version`. Then run `sema preflight resumo --json` and stop unless `decisao` is `use_cli_local`. After that, use local CLI commands: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar`, and `sema finalizar-mudanca`.
-
-Do not call remote MCP, `sema_sync`, `sema_contratos_sincronizar`, or `sema mcp-client` to read a local workspace. Those paths are forbidden for local IDE work when the CLI is operational.
-
-Web chats should use `sema_chat_contexto` and `sema_sync` with inline contract, selected code, operational docs, and index. Web chats must not download files into the chat environment.
-
-Install the governed CLI/client from npm when a local IDE or VPS mirror needs the `sema` command:
-
-```bash
-npm install -g @semacode/cli
-```
-
-The MCP server remains the private web/chat surface. Do not install the MCP from the npm installer package; configure the authorized remote `/mcp` endpoint only for remote clients.
-
-## Português
-
-A Sema é privada. IDE local usa a CLI completa da Sema. Cliente web/chat sem acesso ao workspace local usa MCP remoto.
-
-Em IDE local, o agente deve manter `AGENTS.md` na raiz e rodar `sema --version`. Se o comando não existir, ele deve parar. A IA não acessa o painel Sema: peça ao humano para abrir o painel, baixar/rodar o instalador de chave e repetir `sema --version`. Depois disso, rode `sema preflight resumo --json` e pare se `decisao` não for `use_cli_local`. Com CLI autorizada, use comandos locais da CLI: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar` e `sema finalizar-mudanca`.
-
-Não chame MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local. Esses caminhos são proibidos em IDE local quando a CLI está operacional.
-
-Chats web devem usar `sema_chat_contexto` e `sema_sync` com contrato inline, código selecionado, docs operacionais e índice. Chats web não devem baixar arquivos no ambiente do chat.
-
-Instale a CLI/cliente governada pelo npm quando uma IDE local ou espelho na VPS precisar do comando `sema`:
-
-```bash
-npm install -g @semacode/cli
-```
-
-O servidor MCP continua sendo a superfície privada para web/chat. Não instale o MCP pelo pacote npm do instalador; configure o endpoint remoto `/mcp` autorizado apenas para clientes remotos.
-
-## Español
-
-Sema es privada. Una IDE local usa la CLI completa de Sema. Un cliente web/chat sin acceso al workspace local usa el MCP remoto.
-
-En una IDE local, deja `AGENTS.md` en la raíz del proyecto y ejecuta `sema --version`. Si el comando no existe, para y pide al humano que abra el panel Sema, descargue/ejecute el instalador de clave y repita `sema --version`. Después ejecuta `sema preflight resumo --json` y para si `decisao` no es `use_cli_local`. Después usa comandos locales de la CLI: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar` y `sema finalizar-mudanca`.
-
-No llames el MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ni `sema mcp-client` para leer un workspace local. Esos caminos están prohibidos en una IDE local cuando la CLI está operacional.
-
-Los chats web deben usar `sema_chat_contexto` y `sema_sync` con contrato inline, código seleccionado, docs operativas e índice. Los chats web no deben descargar archivos en el entorno del chat.
-
-Instala la CLI/cliente gobernada desde npm cuando una IDE local o espejo en la VPS necesite el comando `sema`:
-
-```bash
-npm install -g @semacode/cli
-```
-
-El servidor MCP sigue siendo la superficie privada para web/chat. No instales el MCP desde el paquete npm instalador; configura el endpoint remoto `/mcp` autorizado solo para clientes remotos.

package/docs/integracao-com-ia.md

@@ -1,44 +0,0 @@
-# Integração com IA
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final.
-
-## Regra de idioma humano
-
-Sema pode usar palavras-chave de DSL em ASCII. A IA não deve copiar essa estética para texto humano.
-
-- Se o usuário fala português, responda em português com acentos, cedilha, pontuação e símbolos normais.
-- Preserve o idioma do usuário em propostas, documentação, mensagens de erro, textos Author, briefing, resposta final e comentários.
-- Não traduza comandos, rotas, nomes de arquivos, símbolos de código nem palavras-chave `.sema`.
-
-## Agentes fortes, médios e fracos
-
-- IA fraca: comece por `SEMA_BOOT.md`, `SEMA_SMALL_MODEL.md` e `SEMA_BRIEF.micro.txt`; se Sema não responder, pare.
-- IA média: use `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt` e `SEMA_INDEX.json`.
-- IA forte: pode usar `SEMA_BRIEF.md`, AST, IR e drift completo, mas continua obedecendo contrato primeiro.
-
-## English
-
-Sema exists for AI agents operating live systems. The agent should ask Sema for preflight, summary, docs impact, drift, impact, profile validation, and finalization instead of guessing from raw code.
-
-In local IDEs, confirm `AGENTS.md` exists and run `sema --version`. If the command is missing, stop and ask the human to open the Sema panel and run the key installer. Then run `sema preflight resumo --json` and stop unless the decision is `use_cli_local`. Then use local CLI commands: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar`, and `sema finalizar-mudanca`. Do not call remote MCP, `sema_sync`, `sema_contratos_sincronizar`, or `sema mcp-client` to read a local workspace.
-
-In web chats without workspace access, use `sema_chat_contexto` first, then `sema_sync` with contract, selected code, documentation, and index; then use the returned `projeto`. The CLI and MCP use the same commercial control plane and SEMAS account.
-
-## Português
-
-A Sema existe para agentes de IA operarem sistemas vivos. O agente deve pedir preflight, resumo, impacto documental, drift, impacto, validação de profile e finalização para a Sema em vez de adivinhar pelo código cru.
-
-Em IDE local, confirme que `AGENTS.md` existe e rode `sema --version`. Se o comando não existir, pare. A IA não acessa o painel Sema: peça ao humano para abrir o painel e rodar o instalador de chave. Depois rode `sema preflight resumo --json` e pare se a decisão não for `use_cli_local`. Depois use comandos locais da CLI: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar` e `sema finalizar-mudanca`. Não chame MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local.
-
-Em chats web sem acesso ao workspace, use primeiro `sema_chat_contexto`, depois `sema_sync` com contrato, código selecionado, documentação e índice; depois use o `projeto` retornado. CLI e MCP usam o mesmo control plane comercial e a mesma conta de SEMAS.
-
-## Español
-
-Sema existe para agentes de IA que operan sistemas vivos. El agente debe pedir preflight, resumen, impacto documental, drift, impacto, validación de profile y finalización a Sema en vez de adivinar desde código crudo.
-
-En una IDE local, confirma que `AGENTS.md` existe y ejecuta `sema --version`. Si el comando no existe, para y pide al humano que abra el panel Sema y ejecute el instalador de clave. Después ejecuta `sema preflight resumo --json` y para si la decisión no es `use_cli_local`. Después usa comandos locales de la CLI: `sema resumo`, `sema docs-impacto`, `sema inspecionar`, `sema drift`, `sema impacto`, `sema validar` y `sema finalizar-mudanca`. No llames el MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ni `sema mcp-client` para leer un workspace local.
-
-En chats web sin acceso al workspace, usa primero `sema_chat_contexto`, después `sema_sync` con contrato, código seleccionado, documentación e índice; después usa el `projeto` devuelto. CLI y MCP usan el mismo control plane comercial y la misma cuenta de SEMAS.

package/docs/mcp.md

@@ -1,69 +0,0 @@
-# Private MCP
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois.
-> ES: Español al final.
-
-## English
-
-The Sema MCP is the private coordinator for agents. It authenticates clients, selects the project or mirror, charges SEMAS, chooses profiles/pipelines, asks the CLI to read or execute, and returns a traceable decision.
-
-It must stay compatible with web chats. For ChatGPT, Lovable, GPTs, and similar clients, the MCP runs on the VPS and uses the governed CLI installed there against authorized mirrors such as `/srv/sema/projetos/...`.
-When the MCP is public or runs as `production`, it fails closed unless billing is enabled, Supabase billing is configured, legacy bearer is absent, OAuth passcode fallback is absent, and CORS is not wildcard. A remote tool call must not execute if SEMAS billing is disabled.
-
-Local IDEs should not use remote MCP, `sema_sync`, `sema_contratos_sincronizar`, or `sema mcp-client` to read a local workspace. In that mode, the agent must run `sema --version` locally. If the command is missing, the agent must stop and ask the human to open the Sema panel, download/run the key installer, and then repeat `sema --version`. After that, run `sema preflight resumo --json` and continue locally only when the decision is `use_cli_local`.
-
-The MCP must never pretend that a local Windows path exists on the Linux server. If a local IDE asks the remote MCP to read that path, the next action is to use the local CLI. If a web/chat client has no workspace, the next action is to request or create a mirror/snapshot.
-
-The app or connector must recognize the remote MCP from connection/authentication even when no project workspace has been synchronized. Missing workspace is not a missing active session. In web/chat, project work must use `sema_sync` with the applicable contract, selected code, documentation, and index. In a local IDE, project work must use CLI preflight and local CLI commands. The remote MCP must not ask for or try to read the user's local folder.
-
-Official Sema examples and grammar references must be exposed through `sema_exemplos`. Remote agents must not read `C:\GitHub\Sema\exemplos` or any other local user checkout just to learn the DSL.
-
-Typed snapshot payloads have per-file byte limits for contracts, selected code, and documentation. The MCP exposes those limits in tool schemas and validates them again before writing a mirror or running inline contract operations. Clients must split oversized context into focused files instead of sending an entire repository or hiding the limit from the agent.
-
-For code snapshots, splitting means responsibility boundaries, not artificial chunks. A web app should become files such as `index.html`, `styles/*.css`, `js/state.js`, `js/render/*.js`, and `data/*.json`, each with `SEMA-GOVERNED` and a human description when governed. Names like `index_p1.html` and `index_p2.html` are only acceptable when they represent real responsibilities; otherwise they are just a workaround and must be rejected.
-
-Scores, findings, and agent decisions are useful signals, not proof by themselves. The MCP should help the agent connect every finding to concrete contract, code, behavior, and evidence.
-
-## Português
-
-O MCP da Sema é o coordenador privado dos agentes. Ele autentica clientes, escolhe o projeto ou espelho, cobra SEMAS, seleciona profiles/pipelines, pede para a CLI ler ou executar e devolve uma decisão rastreável.
-
-Ele precisa continuar compatível com chats web. Para ChatGPT, Lovable, GPTs e clientes parecidos, o MCP roda na VPS e usa a CLI governada instalada lá contra espelhos autorizados como `/srv/sema/projetos/...`.
-Quando o MCP é publico ou roda como `production`, ele falha fechado se billing nao estiver habilitado, Supabase de billing nao estiver configurado, bearer legado existir, fallback por passcode OAuth existir ou CORS estiver em wildcard. Chamada remota de ferramenta nao deve executar se a cobranca SEMAS estiver desabilitada.
-
-IDEs locais não devem usar MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` para ler workspace local. Nesse modo, o agente deve rodar `sema --version` localmente. Se o comando não existir, o agente deve parar e pedir ao humano para abrir o painel Sema, baixar/rodar o instalador de chave e repetir `sema --version`. Depois disso, rode `sema preflight resumo --json` e continue localmente somente quando a decisão for `use_cli_local`.
-
-O MCP nunca deve fingir que um caminho Windows local existe no servidor Linux. Se uma IDE local pedir ao MCP remoto para ler esse caminho, a próxima ação é usar a CLI local. Se um cliente web/chat não tiver workspace, a próxima ação é pedir ou criar um espelho/snapshot.
-
-O app ou conector deve reconhecer o MCP remoto pela conexão/autenticação, mesmo sem workspace de projeto sincronizado. Falta de workspace não é falta de sessão ativa. Em web/chat, trabalho de projeto deve usar `sema_sync` com contrato aplicável, código selecionado, documentação e índice. Em IDE local, trabalho de projeto deve usar preflight e comandos locais da CLI. O MCP remoto não deve pedir nem tentar ler a pasta local do usuário.
-
-Exemplos oficiais da Sema e referencias de gramatica devem ser expostos por `sema_exemplos`. Agentes remotos nao devem ler `C:\GitHub\Sema\exemplos` nem qualquer checkout local do usuario so para aprender a DSL.
-
-Snapshots tipados tem limite de bytes por arquivo para contratos, codigo selecionado e documentacao. O MCP anuncia esses limites no schema das ferramentas e valida de novo antes de gravar espelho ou executar contrato inline. Clientes devem quebrar contexto grande em arquivos focados, nao enviar repositorio inteiro nem esconder o limite do agente.
-
-Para snapshots de codigo, quebrar significa separar por responsabilidade, nao criar pedacos artificiais. Um app web deve virar arquivos como `index.html`, `styles/*.css`, `js/state.js`, `js/render/*.js` e `data/*.json`, cada um com `SEMA-GOVERNED` e descricao humana quando for governado. Nomes como `index_p1.html` e `index_p2.html` so fazem sentido se representam responsabilidades reais; caso contrario sao gambiarra para burlar limite e devem ser recusados.
-
-Scores, achados e decisoes do agente sao sinais uteis, nao prova isolada. O MCP deve ajudar a IA a ligar cada achado a contrato, codigo, comportamento e evidencia concreta.
-
-## Español
-
-El MCP de Sema es el coordinador privado de los agentes. Autentica clientes, elige el proyecto o espejo, cobra SEMAS, selecciona profiles/pipelines, pide a la CLI que lea o ejecute y devuelve una decisión trazable.
-
-Debe seguir compatible con chats web. Para ChatGPT, Lovable, GPTs y clientes similares, el MCP corre en la VPS y usa la CLI gobernada instalada allí contra espejos autorizados como `/srv/sema/projetos/...`.
-Cuando el MCP es publico o corre como `production`, falla cerrado si billing no esta habilitado, Supabase de billing no esta configurado, bearer legado existe, fallback por passcode OAuth existe o CORS esta en wildcard. Una llamada remota de herramienta no debe ejecutar si la cobranza SEMAS esta deshabilitada.
-
-Las IDEs locales no deben usar el MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ni `sema mcp-client` para leer un workspace local. En ese modo, el agente debe ejecutar `sema --version` localmente. Si el comando no existe, el agente debe parar y pedir al humano que abra el panel Sema, descargue/ejecute el instalador de clave y repita `sema --version`. Después ejecuta `sema preflight resumo --json` y continúa localmente solo cuando la decisión sea `use_cli_local`.
-
-El MCP nunca debe fingir que una ruta local de Windows existe en el servidor Linux. Si una IDE local pide al MCP remoto leer esa ruta, la siguiente acción es usar la CLI local. Si un cliente web/chat no tiene workspace, la siguiente acción es pedir o crear un espejo/snapshot.
-
-La app o el conector debe reconocer el MCP remoto por conexión/autenticación, incluso sin workspace de proyecto sincronizado. Falta de workspace no es falta de sesión activa. En web/chat, el trabajo de proyecto debe usar `sema_sync` con contrato aplicable, código seleccionado, documentación e índice. En una IDE local, el trabajo de proyecto debe usar preflight y comandos locales de la CLI. El MCP remoto no debe pedir ni intentar leer la carpeta local del usuario.
-
-Los ejemplos oficiales de Sema y las referencias de gramatica deben exponerse mediante `sema_exemplos`. Los agentes remotos no deben leer `C:\GitHub\Sema\exemplos` ni ningun checkout local del usuario solo para aprender la DSL.
-
-Los snapshots tipados tienen limites de bytes por archivo para contratos, codigo seleccionado y documentacion. El MCP anuncia esos limites en los schemas de herramientas y vuelve a validarlos antes de escribir un espejo o ejecutar contratos inline. Los clientes deben dividir contexto grande en archivos enfocados, no enviar todo el repositorio ni ocultar el limite al agente.
-
-Para snapshots de codigo, dividir significa separar por responsabilidad, no crear fragmentos artificiales. Una app web debe convertirse en archivos como `index.html`, `styles/*.css`, `js/state.js`, `js/render/*.js` y `data/*.json`, cada uno con `SEMA-GOVERNED` y descripcion humana cuando este gobernado. Nombres como `index_p1.html` e `index_p2.html` solo tienen sentido si representan responsabilidades reales; de lo contrario son un atajo para burlar el limite y deben rechazarse.
-
-Scores, hallazgos y decisiones del agente son senales utiles, no prueba aislada. El MCP debe ayudar a la IA a conectar cada hallazgo con contrato, codigo, comportamiento y evidencia concreta.