@semacode/cli 1.5.31 → 1.5.32

package/docs/deploy.md

@@ -0,0 +1,45 @@
+# Deploy Privado
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
+
+## English
+
+Sema no longer has a public product release runbook. Deploy is private and covers the MCP service, governed CLI runtime, account panel, Supabase control plane, and authorized project mirrors.
+
+Before deploy, run the private boundary check and build:
+
+```bash
+npm run repo:verificar-privado
+npm run build
+```
+
+For the VPS, deploy only the files required by the change, restart `sema-mcp.service` only when runtime code changed, and verify `/healthz` after restart.
+
+## Português
+
+A Sema não tem mais runbook de release pública de produto. O deploy é privado e cobre serviço MCP, runtime governado da CLI, painel de conta, control plane Supabase e espelhos de projeto autorizados.
+
+Antes do deploy, rode a checagem de fronteira privada e o build:
+
+```bash
+npm run repo:verificar-privado
+npm run build
+```
+
+Na VPS, envie apenas os arquivos exigidos pela mudança, reinicie `sema-mcp.service` somente quando código de runtime mudar e valide `/healthz` depois do restart.
+
+## Español
+
+Sema ya no tiene runbook de release pública de producto. El deploy es privado y cubre el servicio MCP, runtime gobernado de la CLI, panel de cuenta, control plane Supabase y espejos de proyecto autorizados.
+
+Antes del deploy, ejecuta la verificación de frontera privada y el build:
+
+```bash
+npm run repo:verificar-privado
+npm run build
+```
+
+En la VPS, envía solo los archivos exigidos por el cambio, reinicia `sema-mcp.service` solo cuando cambie código de runtime y valida `/healthz` después del restart.

package/docs/documentacao.md

@@ -0,0 +1,88 @@
+# Documentation Governance
+
+## English
+
+Sema treats documentation as part of the change, not as a polite afterthought. Before an AI edits a contract, code, configuration, workflow, deploy, Author text, game rule, legal note, research note, or operational runbook, it must resolve the documentation that explains the intended change.
+
+Public documentation follows the exact order defined in [i18n.md](./i18n.md): English, Português, Español. Portuguese and Spanish must keep proper accents. Code blocks, identifiers, paths, command names, and `.sema` symbols are preserved unless a semantic rename contract says otherwise.
+
+### Operational Gate
+
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
+
+If the command reports missing docs, create or complete those docs before changing code, contracts, deploy, or configuration.
+
+### Required Reading
+
+The `docs-impacto` result returns:
+
+- `leituraObrigatoria`: docs, readmes, and contracts that must be read.
+- `docsAusentes`: docs that block the action.
+- `docsCriadas`: docs created automatically when authorized.
+- `bloqueios`: severity 4 diagnostics.
+
+Before declaring the work done, the agent must run:
+
+```bash
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
+```
+
+## Português
+
+A Sema trata documentação como parte da mudança, não como pós-escrito simpático para alguém lembrar depois. Antes de uma IA editar contrato, código, configuração, workflow, deploy, texto Author, regra de jogo, nota jurídica, pesquisa ou runbook operacional, ela precisa resolver a documentação que explica a intenção da mudança.
+
+A documentação pública segue a ordem exata definida em [i18n.md](./i18n.md): English, Português, Español. Português e espanhol precisam preservar acentos. Blocos de código, identificadores, caminhos, nomes de comando e símbolos `.sema` são preservados, exceto quando houver contrato de renomeação semântica.
+
+### Gate Operacional
+
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
+
+Se o comando apontar docs ausentes, crie ou complete essas docs antes de mudar código, contratos, deploy ou configuração.
+
+### Leitura Obrigatória
+
+O resultado de `docs-impacto` retorna:
+
+- `leituraObrigatoria`: docs, readmes e contratos que precisam ser lidos.
+- `docsAusentes`: docs que bloqueiam a ação.
+- `docsCriadas`: docs criadas automaticamente quando autorizado.
+- `bloqueios`: diagnósticos de severidade 4.
+
+Antes de dizer que o trabalho terminou, o agente precisa rodar:
+
+```bash
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
+```
+
+## Español
+
+Sema trata la documentación como parte del cambio, no como una nota amable para recordar después. Antes de que una IA edite contrato, código, configuración, workflow, deploy, texto Author, regla de juego, nota legal, investigación o runbook operativo, debe resolver la documentación que explica la intención del cambio.
+
+La documentación pública sigue el orden exacto definido en [i18n.md](./i18n.md): English, Português, Español. Portugués y español deben conservar sus acentos. Bloques de código, identificadores, rutas, nombres de comando y símbolos `.sema` se preservan, excepto cuando exista un contrato de renombrado semántico.
+
+### Gate Operativo
+
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
+
+Si el comando informa docs ausentes, crea o completa esas docs antes de cambiar código, contratos, deploy o configuración.
+
+### Lectura Obligatoria
+
+El resultado de `docs-impacto` devuelve:
+
+- `leituraObrigatoria`: docs, readmes y contratos que deben leerse.
+- `docsAusentes`: docs que bloquean la acción.
+- `docsCriadas`: docs creadas automáticamente cuando se autoriza.
+- `bloqueios`: diagnósticos de severidad 4.
+
+Antes de decir que el trabajo terminó, el agente debe ejecutar:
+
+```bash
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/documentacao.md --json
+```

package/docs/env.md

@@ -0,0 +1,115 @@
+# Env
+
+<!-- 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.
+
+
+Ambiente necessário para publicar a Sema.
+
+## Ferramentas
+
+- Node.js LTS com `npm`.
+- Git com acesso push ao remoto `origin`.
+- GitHub CLI (`gh`) autenticado.
+- VS Code CLI (`code`) para instalar a VSIX localmente.
+- PowerShell no Windows.
+
+## Variaveis suportadas pelos instaladores publicos
+
+- `SEMA_REPO`: repositório GitHub usado para baixar assets. Padrão: `gerlanss/Sema`.
+- `SEMA_NPM_PACKAGE`: pacote da CLI. Padrão: `@semacode/cli`.
+- `SEMA_VERSION`: versão usada pelo `install-sema.sh`. Padrão: `latest`.
+
+No PowerShell, o instalador recebe a versão por parametro:
+
+```powershell
+.\install-sema.ps1 -Version 1.5.29 -WithVSCode
+```
+
+No shell:
+
+```bash
+SEMA_VERSION=1.5.29 ./install-sema.sh --with-vscode
+```
+
+## Credenciais
+
+- NPM deve estar logado antes de publicar: `npm whoami`.
+- GitHub CLI deve estar logado antes de criar release: `gh auth status`.
+- Nunca registre tokens em docs, logs ou release notes.
+
+## Registro NPM
+
+O pacote público é:
+
+- `@semacode/cli`
+
+Antes de publicar, confira:
+
+```bash
+npm view @semacode/cli version
+npm run release:verificar-versao
+```
+
+## Cliente MCP remoto
+
+Variaveis usadas por Codex, VS Code/forks e clientes que aceitam bearer:
+
+- `SEMA_MCP_AUTH_TOKEN`: chave comercial `sema_mcp_*` gerada no painel. E do cliente, nao do servidor.
+- `SEMA_MCP_ENDPOINT`: URL HTTPS `/mcp` usada por clientes que leem endpoint por variavel.
+
+No Windows, instale sem expor a chave em argumento:
+
+```powershell
+Get-Clipboard | sema mcp-instalar-chave --stdin --json
+```
+
+## Servidor MCP remoto privado
+
+Variaveis usadas pelo servidor MCP privado quando roda em modo HTTP:
+
+- `MCP_PORT`: porta HTTP. Quando ausente, o MCP roda em `stdio`.
+- `MCP_HOST`: host de bind. Padrão: `0.0.0.0`.
+- `SEMA_MCP_PUBLIC_BASE_URL`: URL pública HTTPS usada nos metadados OAuth do ChatGPT.
+- `SEMA_MCP_OAUTH_SECRET`: segredo usado para assinar access/refresh tokens OAuth.
+- `SEMA_MCP_OAUTH_PASSCODE`: passcode privado digitado no login OAuth do ChatGPT.
+- `SEMA_MCP_PROJECT_ROOTS`: raizes permitidas para projetos, separadas por `;`.
+- `SEMA_MCP_CORS_ORIGIN`: origem CORS permitida, `*` ou lista separada por `;`.
+- `SEMA_MCP_MAX_CONTRACT_FILE_BYTES`: limite por contrato `.sema` enviado por snapshot ou conteudo inline. Padrao: `262144`.
+- `SEMA_MCP_MAX_CODE_FILE_BYTES`: limite por arquivo de codigo selecionado enviado por snapshot. Padrao: `262144`.
+- `SEMA_MCP_MAX_DOC_FILE_BYTES`: limite por arquivo de documentacao enviado por snapshot. Padrao: `262144`.
+- `SEMA_MCP_MAX_CODE_FILES`: limite de arquivos de codigo selecionado por snapshot. Padrao: `80`.
+- `SEMA_MCP_MAX_DOC_FILES`: limite de arquivos de documentacao por snapshot. Padrao: `80`.
+
+Exemplo operacional privado:
+
+```bash
+MCP_PORT=3333 \
+SEMA_MCP_PUBLIC_BASE_URL="https://sema.exemplo.com" \
+SEMA_MCP_OAUTH_SECRET="segredo-longo-para-oauth" \
+SEMA_MCP_OAUTH_PASSCODE="passcode-privado-chatgpt" \
+SEMA_MCP_PROJECT_ROOTS="/srv/sema/projetos" \
+SEMA_MCP_MAX_CONTRACT_FILE_BYTES=262144 \
+SEMA_MCP_MAX_CODE_FILE_BYTES=262144 \
+SEMA_MCP_MAX_DOC_FILE_BYTES=262144
+```
+
+Nunca publique `/mcp` ou `/sse` na internet sem chave comercial bearer por request ou OAuth configurado, raiz restrita e HTTPS no proxy. Nunca registre chaves `sema_mcp_*`, OAuth secret ou passcode em docs publicas, logs, release notes ou screenshots.
+
+O limite de bytes e validado antes de gravar espelhos remotos ou executar contratos inline. Clientes MCP devem respeitar o limite anunciado no schema da ferramenta e dividir snapshots grandes em arquivos focados, sem enviar repositorio inteiro.
+
+## GitHub Release
+
+O tag público deve seguir `v<versao>`, por exemplo `v1.5.29`.
+
+Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositório.
+
+Depois de publicar, rode:
+
+```bash
+npm run release:verificar-publica
+```
+
+Esse check cruza README/docs, manifestos, npm, GitHub Latest, assets publicados, CLI local e VSIX instalada quando o VS Code CLI está disponivel.

package/docs/extensao-vscode.md

@@ -0,0 +1,42 @@
+# Extensão VS Code
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
+
+## English
+
+The VS Code extension is part of the private Sema workflow. It should help local IDE agents read `AGENTS.md`, run the governed CLI runtime installed from `@semacode/cli`, install MCP keys safely, and synchronize AI entry points without exposing secrets.
+
+Smoke test:
+
+1. Open a project with `.sema` contracts.
+2. Confirm the language server starts.
+3. Run the Sema CLI diagnostic command.
+4. Install an MCP key from the panel without passing the secret as a process argument.
+5. Synchronize AI entry points.
+
+## Português
+
+A extensão VS Code faz parte do fluxo privado da Sema. Ela deve ajudar agentes em IDE local a ler `AGENTS.md`, rodar o runtime governado da CLI instalada por `@semacode/cli`, instalar chaves MCP com segurança e sincronizar entrypoints IA sem expor segredos.
+
+Smoke test:
+
+1. Abra um projeto com contratos `.sema`.
+2. Confirme que o language server inicia.
+3. Rode o diagnóstico da CLI Sema.
+4. Instale uma chave MCP do painel sem passar o segredo como argumento de processo.
+5. Sincronize entrypoints IA.
+
+## Español
+
+La extensión VS Code forma parte del flujo privado de Sema. Debe ayudar a agentes en IDE local a leer `AGENTS.md`, ejecutar el runtime gobernado de la CLI instalada desde `@semacode/cli`, instalar claves MCP con seguridad y sincronizar entrypoints IA sin exponer secretos.
+
+Smoke test:
+
+1. Abre un proyecto con contratos `.sema`.
+2. Confirma que el language server inicia.
+3. Ejecuta el diagnóstico de la CLI Sema.
+4. Instala una clave MCP del panel sin pasar el secreto como argumento de proceso.
+5. Sincroniza entrypoints IA.

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

@@ -0,0 +1,187 @@
+# 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.
+
+## Fluxo curto
+
+1. ler contexto do projeto
+2. identificar a capacidade da IA
+3. identificar o módulo alvo
+4. consultar o menor artefato semântico suficiente
+5. editar
+6. formatar
+7. validar
+8. 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 pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
+- IA média: `sema resumo --curto`, `briefing.min.json` e `drift.json`
+- IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
+
+### Etapa 3. Ler o 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 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` ou `dart`, 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 pequena:
+
+```bash
+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 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

@@ -0,0 +1,48 @@
+# 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. The MCP endpoint is the primary product surface and coordinates authentication, SEMAS consumption, profiles, pipelines, and project mirrors.
+
+Local IDEs should receive `AGENTS.md` first. Web chats should use `sema_chat_contexto` and `sema_sync` instead of downloading 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 product surface. Do not install the MCP from a public npm package; configure the authorized remote `/mcp` endpoint instead.
+
+## Português
+
+A Sema é privada. O endpoint MCP é a superfície principal do produto e coordena autenticação, consumo de SEMAS, profiles, pipelines e espelhos de projeto.
+
+IDEs locais devem receber `AGENTS.md` primeiro. Chats web devem usar `sema_chat_contexto` e `sema_sync`, não 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 do produto. Não instale o MCP por pacote npm público; configure o endpoint remoto `/mcp` autorizado.
+
+## Español
+
+Sema es privada. El endpoint MCP es la superficie principal del producto y coordina autenticación, consumo de SEMAS, profiles, pipelines y espejos de proyecto.
+
+Las IDEs locales deben recibir `AGENTS.md` primero. Los chats web deben usar `sema_chat_contexto` y `sema_sync`, no 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 del producto. No instales el MCP desde un paquete npm público; configura el endpoint remoto `/mcp` autorizado.

package/docs/integracao-com-ia.md

@@ -0,0 +1,24 @@
+# Integração com IA
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
+
+## English
+
+Sema exists for AI agents operating live systems. The agent should ask Sema for summary, docs impact, drift, impact, profile validation, and finalization instead of guessing from raw code.
+
+In local IDEs, confirm `AGENTS.md` exists before `sema_resumo`. In web chats, use `sema_chat_contexto` first, then `sema_sync` or inline content. The MCP coordinates the flow and charges SEMAS; the CLI executes local or VPS-side checks.
+
+## Português
+
+A Sema existe para agentes de IA operarem sistemas vivos. O agente deve pedir 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 antes de `sema_resumo`. Em chats web, use primeiro `sema_chat_contexto`, depois `sema_sync` ou conteúdo inline. O MCP coordena o fluxo e cobra SEMAS; a CLI executa checks locais ou na VPS.
+
+## Español
+
+Sema existe para agentes de IA que operan sistemas vivos. El agente debe pedir resumen, impacto documental, drift, impacto, validación de profile y finalización a Sema en vez de adivinar desde código crudo.
+
+En IDE local, confirma que `AGENTS.md` existe antes de `sema_resumo`. En chats web, usa primero `sema_chat_contexto`, después `sema_sync` o contenido inline. El MCP coordina el flujo y cobra SEMAS; la CLI ejecuta checks locales o en la VPS.

package/docs/mcp.md

@@ -0,0 +1,48 @@
+# 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/...`.
+
+It must also stay compatible with local IDEs. In that mode, the client sends typed snapshots: contracts, selected code, documentation, and an index. When complete local-code drift is required, the installed CLI may run in the IDE workspace.
+
+The MCP must never pretend that a local Windows path exists on the Linux server. If the server cannot see the 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; it only means project work must use `sema_sync`, an attachment, or inline content. The remote MCP must not ask for or try to read the user's local folder.
+
+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.
+
+## 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/...`.
+
+Ele também precisa continuar compatível com IDEs locais. Nesse modo, o cliente envia snapshots tipados: contratos, código selecionado, documentação e índice. Quando drift completo contra código local for necessário, a CLI instalada pode rodar no workspace da IDE.
+
+O MCP nunca deve fingir que um caminho Windows local existe no servidor Linux. Se o servidor não enxerga o workspace, a próxima ação é pedir ou criar um espelho/snapshot.
+
+O app ou conector deve reconhecer o MCP remoto pela conexao/autenticacao, mesmo sem workspace de projeto sincronizado. Falta de workspace nao e falta de sessao ativa: e apenas o sinal de que a proxima acao de projeto deve usar `sema_sync`, anexo ou conteudo inline. O MCP remoto nao deve pedir nem tentar ler a pasta local do usuario.
+
+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.
+
+## 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/...`.
+
+También debe seguir compatible con IDEs locales. En ese modo, el cliente envía snapshots tipados: contratos, código seleccionado, documentación e índice. Cuando haga falta drift completo contra código local, la CLI instalada puede correr en el workspace de la IDE.
+
+El MCP nunca debe fingir que una ruta local de Windows existe en el servidor Linux. Si el servidor no ve el workspace, la siguiente acción es pedir o crear un espejo/snapshot.
+
+La app o el conector debe reconocer el MCP remoto por conexion/autenticacion, incluso sin workspace de proyecto sincronizado. Falta de workspace no es falta de sesion activa: solo indica que el trabajo de proyecto debe usar `sema_sync`, un adjunto o contenido inline. El MCP remoto no debe pedir ni intentar leer la carpeta local del usuario.
+
+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.