@semacode/cli 1.5.30 → 1.5.32

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.

package/docs/pagamento-ponta-a-ponta.md

@@ -0,0 +1,171 @@
+# Pagamento Ponta a Ponta na 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 vertical oficial de pagamento da Sema no fluxo público atual.
+
+O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
+
+- contrato público
+- segurança e autorizacao
+- classificacao de dados
+- segredos e proibicoes explicitas
+- regras
+- efeitos operacionais
+- execução, idempotencia, retry e compensacao
+- transicoes de estado
+- orquestração
+- erros publicos
+- testes executaveis com saída, status ou erro observavel
+
+## Arquivos de referência
+
+- `exemplos/pagamento_dominio.sema`
+- `exemplos/pagamento.sema`
+
+## Como o vertical foi dividido
+
+### `exemplos.pagamento.dominio`
+
+Centraliza os contratos compartilhados:
+
+- `entity Pagamento`
+- `enum StatusPagamento`
+- `state ciclo_pagamento`
+
+### `exemplos.pagamento`
+
+Centraliza a operação do vertical:
+
+- `task processar_pagamento`
+- `task confirmar_pagamento`
+- `task notificar_falha_pagamento`
+- `task registrar_timeout_pagamento`
+- `flow orquestracao_pagamento`
+- `route processar_pagamento_publico`
+
+## Narrativa do caso
+
+### Entrada pública
+
+A operação entra por:
+
+- `route processar_pagamento_publico`
+
+Esse contrato pública:
+
+- `pagamento_id`
+- `valor`
+- `token`
+
+É expoe:
+
+- `pagamento`
+- `status`
+- erros publicos coerentes com a `task`
+
+### Task interna
+
+A `task processar_pagamento` faz o trabalho central:
+
+- exige `authz`
+- classifica `dados`
+- declara `segredos`, `audit` e `forbidden`
+- valida entrada
+- consulta o gateway
+- persiste o pagamento
+- emite evento
+- notifica comprovante
+- registra auditoria
+- declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
+- garante consistencia da saída
+
+### Estado e transicoes
+
+O `state ciclo_pagamento` ancora o contrato de transicao:
+
+- `PENDENTE -> AUTORIZADO`
+- `AUTORIZADO -> PROCESSADO`
+- `PENDENTE -> RECUSADO`
+
+A `task` explícita quais transicoes ela realmente usa.
+
+### Flow de orquestração
+
+O `flow orquestracao_pagamento` demonstra:
+
+- passagem de contexto
+- confirmação em caso de sucesso
+- notificação em caso de recusa
+- registro de timeout em caso de indisponibilidade
+- ramificacao por erro tipado
+
+### Efeitos operacionais
+
+O vertical usa as 5 categorias oficiais da Sema:
+
+- `persistencia`
+- `consulta`
+- `evento`
+- `notificacao`
+- `auditoria`
+
+Também usa `criticidade` para deixar claro o peso operacional do efeito.
+
+### Falhas reais
+
+O vertical cobre explicitamente:
+
+- autorizacao negada
+- saldo insuficiente
+- timeout de gateway
+
+## Fluxo de trabalho recomendado
+
+### 1. Escrever ou ajustar os arquivos `.sema`
+
+Use o domínio compartilhado em um módulo e a operação em outro módulo.
+
+### 2. Aplicar o formato canônico
+
+```bash
+sema formatar exemplos
+```
+
+### 3. Validar semanticamente
+
+```bash
+sema validar exemplos/pagamento.sema
+```
+
+### 4. Gerar código
+
+```bash
+sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
+sema compilar exemplos/pagamento.sema --alvo python --saida ./.tmp/pagamento-py
+```
+
+### 5. Verificar o vertical completo
+
+```bash
+sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamento
+```
+
+## O que esse vertical prova
+
+Se esse vertical passa, a Sema já consegue demonstrar que:
+
+- modela contrato público
+- modela superficie sensível sem deixar segurança invisível
+- modela efeitos operacionais
+- modela falhas reais
+- modulariza domínio com `use`
+- declara idempotencia e execução crítica sem criar sintaxe nova
+- gera artefatos coerentes para TypeScript e Python
+- executa testes gerados sem gambiarra conceitual
+
+Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.

package/docs/persistencia-vendor-first.md

@@ -0,0 +1,151 @@
+# Persistência Vendor-First
+
+<!-- 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.
+
+
+Sema 1.5.29 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
+
+## Engines publicas
+
+- `postgres`
+- `mysql`
+- `sqlite`
+- `mongodb`
+- `redis`
+
+## Exemplo PostgreSQL
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+## Exemplo MySQL
+
+```sema
+database principal_mysql {
+  engine: mysql
+  consistency: forte
+  durability: alta
+  transaction_model: bloqueio
+  query_model: sql
+  table faturamento {
+    table: faturamento
+  }
+  index faturamento_status {
+    table: faturamento
+  }
+  query buscar_faturas {
+    mode: sql
+  }
+}
+```
+
+## Exemplo SQLite
+
+```sema
+database principal_sqlite {
+  engine: sqlite
+  consistency: snapshot
+  durability: media
+  transaction_model: single_thread
+  query_model: sql
+  table cache_local {
+    table: cache_local
+  }
+  retention limpeza_local {
+    retention: "7d"
+  }
+}
+```
+
+## Exemplo MongoDB
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  consistency: eventual
+  durability: alta
+  transaction_model: documento
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+## Exemplo Redis
+
+```sema
+database principal_redis {
+  engine: redis
+  consistency: eventual
+  durability: media
+  transaction_model: single_thread
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+  retention expurgo_cache {
+    retention: "300s"
+  }
+}
+```
+
+## Compatibilidade calculada
+
+Cada recurso recebe compatibilidade por engine:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso deixa explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
+
+- `table` em `redis`
+- `foreign_keys` em engine sem suporte equivalente
+- transação multi-documento tratada como universal
+
+## Onde isso aparece
+
+- parser e AST
+- IR canonica
+- analisador semântico
+- formatador
+- `sema drift`
+- `sema importar`
+- extensao VS Code

package/docs/prompt-base-ia-sema.md

@@ -0,0 +1,111 @@
+# Prompt-Base Oficial para IA Trabalhar com 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 arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
+
+O objetivo não é fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema não foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primário e o agente.
+
+## Prompt-base
+
+Use o texto abaixo como base:
+
+```text
+Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
+
+Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
+
+Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
+
+Fontes de verdade, em ordem:
+1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
+2. `SEMA_BRIEF.md`
+3. `SEMA_INDEX.json`
+4. README do projeto
+5. gramatica e documentacao de sintaxe da Sema
+6. especificacao semantica da linguagem
+7. exemplos oficiais, com prioridade para o vertical de pagamento
+8. `sema resumo` e `briefing.min.json` quando a IA for pequena
+9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
+
+Regras de operacao:
+- preserve o significado semantico
+- use o formatador oficial da Sema como fonte unica de estilo
+- use diagnosticos estruturados como contrato de correcao
+- use a IR como fonte de verdade semantica quando houver duvida
+- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
+- nao conclua uma alteracao sem validar e verificar o modulo
+- trate `importar` como bootstrap revisavel, nao como contrato final automatico
+- trate `drift` como medicao de verdade contra codigo vivo
+- trate `impl` como ponte entre task e simbolo real
+- nao invente regra de negocio que o contrato e o codigo nao sustentem
+
+Antes de editar `.sema`, entenda:
+- o module alvo
+- os contratos de task, route, error, effects, guarantees, state e flow
+- os exemplos oficiais relacionados
+
+Depois de editar `.sema`, execute este fluxo:
+1. formatar
+2. validar
+3. diagnosticar, se houver falha
+4. verificar
+
+Se houver conflito entre texto livre e IR/diagnosticos, priorize a IR e os diagnosticos da CLI.
+
+Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao improvise sem base.
+```
+
+## Variacao curta
+
+Se voce quiser um prompt menor para uso frequente:
+
+```text
+Trabalhe com Sema como contrato semantico IA-first orientado a agente. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
+```
+
+Se voce quiser um prompt ainda mais curto e pronto para colar, use:
+
+```bash
+sema prompt-curto caminho/arquivo.sema --curto --para mudanca
+```
+
+## Variacao para revisão
+
+Use está versão quando a IA for revisar `.sema` em vez de criar:
+
+```text
+Revise este modulo Sema como contrato semantico executavel. Procure incoerencias entre input, output, rules, effects, guarantees, state, flow, route e error. Considere a IR e os diagnosticos da CLI como fonte de verdade. Nao critique estilo fora do que o formatador oficial resolveria automaticamente.
+```
+
+## Variacao para geracao
+
+Use está versão quando a IA for escrever módulo novo:
+
+```text
+Gere um modulo Sema seguindo a gramatica oficial, os exemplos do projeto e o estilo do formatador canonico. Estruture o modulo como contrato semantico executavel, com blocos explicitos para entrada, saida, regras, efeitos, garantias, erros, estado, fluxo e testes quando fizer sentido. Nao use sintaxe fora do repertorio ja suportado pela linguagem.
+```
+
+## Variacao para correcao guiada por diagnóstico
+
+Use está versão quando a IA já tiver erro concreto para corrigir:
+
+```text
+Corrija este modulo Sema a partir dos diagnosticos estruturados da CLI. Preserve a intencao do contrato e altere apenas o necessario para eliminar as falhas. Depois da correcao, aplique o formatador oficial e revalide.
+```
+
+## O que sempre anexar junto do prompt
+
+Idealmente, acompanhe o prompt com:
+
+- o arquivo `.sema` alvo
+- o resultado de `sema ast --json`
+- o resultado de `sema ir --json`
+- o resultado de `sema diagnosticos --json`, se houver erro
+- um exemplo oficial parecido
+
+Sem isso, a IA pode até acertar. Com isso, ela trabalha direito.

package/docs/repositories.md

@@ -0,0 +1,69 @@
+# Repository Boundary
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois.
+> ES: Español al final.
+
+## English
+
+Sema is private by default, with one public installation path: `@semacode/cli` on npm. There is no public product repository, no public MCP package surface, and no active `public/` versus `private/` repository split.
+
+The active tree lives at the repository root: `contratos/`, `pacotes/`, `mcp/`, `site/`, `supabase/`, `deploy/`, `docs/`, `scripts/`, and `testes/`.
+
+The operating model is:
+
+- The MCP is the private coordinator: it authenticates clients, selects the right project or mirror, charges SEMAS, decides the required contract/profile flow, and returns the operational verdict.
+- The CLI is distributed as the public npm installer/client `@semacode/cli`, then acts as the governed executor: it reads contracts, validates, checks drift, builds AI-first context, and performs local or server-side actions requested by the MCP.
+- Web chats remain supported because the private MCP keeps a CLI installed on the VPS and runs it against authorized mirrors under `/srv/sema/projetos/...`.
+- Local IDEs remain supported by sending typed snapshots, selected code, docs, and indexes to the MCP; when local full-code drift is required, the installed CLI can run inside the IDE environment.
+
+Public distribution is allowed only for the governed CLI installer. If a script tries to publish the MCP server, product release assets, secrets, control-plane code, or any public package outside `@semacode/cli`, it must fail before any artifact is created.
+
+Use the private boundary check:
+
+```bash
+npm run repo:verificar-privado
+```
+
+## Português
+
+O Sema agora e privado por padrao, com um caminho publico de instalacao: `@semacode/cli` no npm. Nao existe repositorio publico de produto, superficie MCP publica como pacote aberto nem divisao ativa entre `public/` e `private/`.
+
+A arvore ativa vive na raiz do repositorio: `contratos/`, `pacotes/`, `mcp/`, `site/`, `supabase/`, `deploy/`, `docs/`, `scripts/` e `testes/`.
+
+O modelo operacional é:
+
+- O MCP é o coordenador privado: autentica clientes, escolhe o projeto ou espelho correto, cobra SEMAS, decide o fluxo de contrato/profile obrigatório e devolve o veredito operacional.
+- A CLI e distribuida como instalador/cliente publico `@semacode/cli` no npm e depois atua como executor governado: le contratos, valida, mede drift, monta contexto IA-first e executa acoes locais ou no servidor quando o MCP pedir.
+- Chats web continuam suportados porque o MCP privado mantém uma CLI instalada na VPS e executa contra espelhos autorizados em `/srv/sema/projetos/...`.
+- IDEs locais continuam suportadas enviando snapshots tipados, codigo selecionado, docs e indice para o MCP; quando drift completo local for necessario, a CLI instalada pode rodar dentro do ambiente da IDE.
+
+Distribuicao publica so e permitida para o instalador CLI governado. Se algum script tentar publicar o servidor MCP, assets de release de produto, segredos, control plane ou qualquer pacote publico fora de `@semacode/cli`, ele deve falhar antes de criar qualquer artefato.
+
+Use a checagem de fronteira privada:
+
+```bash
+npm run repo:verificar-privado
+```
+
+## Español
+
+Sema ahora es privado por defecto, con una ruta publica de instalacion: `@semacode/cli` en npm. No existe repositorio publico de producto, superficie MCP publica como paquete abierto ni division activa entre `public/` y `private/`.
+
+El arbol activo vive en la raiz del repositorio: `contratos/`, `pacotes/`, `mcp/`, `site/`, `supabase/`, `deploy/`, `docs/`, `scripts/` y `testes/`.
+
+El modelo operativo es:
+
+- El MCP es el coordinador privado: autentica clientes, elige el proyecto o espejo correcto, cobra SEMAS, decide el flujo obligatorio de contrato/profile y devuelve el veredicto operativo.
+- La CLI se distribuye como instalador/cliente publico `@semacode/cli` en npm y luego actua como ejecutor gobernado: lee contratos, valida, mide drift, prepara contexto IA-first y ejecuta acciones locales o del servidor cuando el MCP lo solicita.
+- Los chats web siguen soportados porque el MCP privado mantiene una CLI instalada en la VPS y la ejecuta contra espejos autorizados en `/srv/sema/projetos/...`.
+- Las IDEs locales siguen soportadas enviando snapshots tipados, codigo seleccionado, docs e indice al MCP; cuando haga falta drift completo local, la CLI instalada puede correr dentro del entorno de la IDE.
+
+La distribucion publica solo se permite para el instalador CLI gobernado. Si un script intenta publicar el servidor MCP, assets de release de producto, secretos, control plane o cualquier paquete publico fuera de `@semacode/cli`, debe fallar antes de crear cualquier artefacto.
+
+Usa la verificación de frontera privada:
+
+```bash
+npm run repo:verificar-privado
+```

package/docs/rollback.md

@@ -0,0 +1,24 @@
+# Rollback Privado
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
+
+## English
+
+Rollback is private and must preserve traceability. If the MCP runtime breaks, restore the previous package or dist files, restart `sema-mcp.service`, and verify `/healthz`.
+
+Do not rewrite customer mirrors blindly. Project mirrors under `/srv/sema/projetos/...` must only be reverted when the failed change touched that mirror.
+
+## Português
+
+Rollback é privado e precisa preservar rastreabilidade. Se o runtime MCP quebrar, restaure o pacote ou os arquivos `dist` anteriores, reinicie `sema-mcp.service` e valide `/healthz`.
+
+Não reescreva espelhos de clientes às cegas. Espelhos de projeto em `/srv/sema/projetos/...` só devem ser revertidos quando a mudança com falha tiver tocado aquele espelho.
+
+## Español
+
+El rollback es privado y debe preservar trazabilidad. Si el runtime MCP falla, restaura el paquete o los archivos `dist` anteriores, reinicia `sema-mcp.service` y valida `/healthz`.
+
+No reescribas espejos de clientes a ciegas. Los espejos de proyecto en `/srv/sema/projetos/...` solo deben revertirse cuando el cambio fallido haya tocado ese espejo.