@semacode/cli 1.5.17 → 1.5.19

package/docs/cli.md

@@ -1,20 +1,57 @@
-# CLI da Sema
+# Sema CLI
 
-## Papel da CLI
+## English
 
-A CLI e a interface oficial da Sema para:
+The Sema CLI is the public npm package for local semantic governance. It validates `.sema` contracts, checks drift, maps impact, prepares AI-first context, resolves documentation gates, and runs profile validators before an agent continues.
+
+Current public version: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Português
+
+A CLI da Sema é o pacote público no npm para governança semântica local. Ela valida contratos `.sema`, verifica drift, mapeia impacto, prepara contexto IA-first, resolve gates de documentação e roda validadores de profiles antes de um agente continuar.
+
+Versão pública atual: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Español
+
+La CLI de Sema es el paquete público en npm para gobernanza semántica local. Valida contratos `.sema`, verifica drift, mapea impacto, prepara contexto IA-first, resuelve gates de documentación y ejecuta validadores de profiles antes de que un agente continúe.
+
+Versión pública actual: `1.5.19`.
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema validar contratos/pedidos.sema --json
+```
+
+## Referência Operacional
+
+### Papel da CLI
+
+A CLI é a interface oficial da Sema para:
 
 - validar contratos `.sema`
 - exportar AST e IR
-- medir `drift` entre contrato e codigo vivo
-- importar legado para rascunho revisavel
-- gerar codigo derivado
+- medir `drift` entre contrato e código vivo
+- importar legado para rascunho revisável
+- gerar código derivado
 - preparar contexto IA-first
-- expor profiles operacionais como `sema author`
-- resolver docs obrigatorias por intencao antes de editar ou operar
-- verificar multiplos alvos de geracao
+- resolver docs obrigatórias por intenção antes de editar ou operar
+- verificar múltiplos alvos de geração
 
-## Tres modos de operacao
+### Três Modos De Operação
 
 Projeto novo:
 
@@ -23,52 +60,48 @@ Projeto novo:
 - `sema compilar`
 - `sema verificar`
 
-Projeto ja semantizado:
+Projeto já semantizado:
 
 - `sema inspecionar`
 - `sema resumo`
 - `sema drift`
 - `sema contexto-ia`
 
-Adocao incremental:
+Adoção incremental:
 
 - `sema importar`
 - `sema formatar`
 - `sema validar`
 - `sema drift`
 
-## Persistencia vendor-first
+## Persistência vendor-first
 
-A linha atual adiciona uma secao canonica de persistencia no contrato, no semantico, no IR e no formatador, alem de `drift` com escopo real, `impacto`, renomeacao semantica assistida, `verificar` mais coerente nos alvos gerados, match de metodos JS/TS definidos via `Object.assign(...prototype...)`, leitura de `Preferences`/`localStorage`/`sessionStorage`, fallback para `angular-consumer` standalone sem `.routes`, compatibilidade PHP como codigo vivo e limpeza de runtime da CLI publica para reduzir atrito de instalacao no Windows.
+A linha 1.5.19 mantém persistência vendor-first como seção canônica no contrato, no semântico, na IR e no formatador, além de `drift` com escopo real, `impacto`, renomeação semântica assistida, `verificar` mais coerente nos alvos gerados, match de métodos JS/TS definidos via `Object.assign(...prototype...)`, leitura de `Preferences`/`localStorage`/`sessionStorage`, fallback para `angular-consumer` standalone sem `.routes`, limpeza de runtime da CLI pública no Windows, Sema Author oficial e MCP remoto desmembrado da distribuição pública.
 
-Cobertura publica:
+Cobertura pública:
 
 - `postgres`: `table`, `relationship`, `query`, `schema`, capacidades relacionais
-- `mysql`: `table`, `index`, consultas SQL e diferencas operacionais do engine
+- `mysql`: `table`, `index`, consultas SQL e diferenças operacionais do engine
 - `sqlite`: `table`, `retention`, uso local e edge
 - `mongodb`: `collection`, `document`, `query` em `pipeline`
-- `redis`: `keyspace`, `stream`, `retention`, TTL e superficies de estado
+- `redis`: `keyspace`, `stream`, `retention`, TTL e superfícies de estado
 
-## Drift e codigo vivo
+## Drift e código vivo
 
 `sema drift` agora cruza contrato com recursos reais encontrados em:
 
-- codigo de backend
-- codigo Lua usado como runtime ou bridge
-- codigo PHP usado como backend, controller, runtime ou bridge
+- código de backend
 - DDL `.sql`
 - schema `.prisma`
 - uso de MongoDB
 - uso de Redis, incluindo keyspaces e streams
 
-O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas claras.
+O objetivo não é adivinhar tudo; é produzir um score explicável com lacunas claras.
 
 ## Ajuda IA-first
 
 - `sema ajuda-ia`
 - `sema starter-ia`
-- `sema author`
-- `sema author exemplo --sensivel --json`
 - `sema resumo <arquivo-ou-pasta> --micro|--curto|--medio`
 - `sema prompt-curto <arquivo-ou-pasta> --micro|--curto|--medio`
 - `sema contexto-ia <arquivo.sema> --saida <diretorio>`
@@ -76,7 +109,35 @@ O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas clar
 - `sema docs-impacto --intencao <acao> --criar-ausentes --json`
 - `sema finalizar-mudanca --intencao <acao> --doc-lida <caminho> --json`
 
-## Importadores publicos
+## Profiles Semânticos
+
+Profiles oficiais usam contrato Sema normal e um gate de requisitos obrigatórios. O requisito comum é contrato primeiro: criar, editar ou remover contrato antes de qualquer ação. Se o contrato não declara o mínimo do domínio, o comando falha.
+
+```bash
+sema profile validar software contratos/sema/software.sema --json
+sema profile validar workflow contratos/sema/workflow_ops.sema --json
+sema profile validar ops contratos/sema/workflow_ops.sema --json
+sema profile validar game contratos/sema/game.sema --json
+sema profile validar legal contratos/sema/legal.sema --json
+sema profile validar research contratos/sema/research.sema --json
+```
+
+## Sema Author
+
+Author é um profile oficial para governança autoral IA-first. Ele usa a mesma DSL, sem palavra-chave nova, e organiza contratos em core, agents e flow. Se obra, tom, limite, público ou política muda, edite o contrato antes de gerar ou revisar texto.
+
+```bash
+sema author iniciar --saida contratos/author.sema
+sema author iniciar --tema-sensivel --saida contratos/author.sema
+sema author validar contratos/author.sema --json
+sema author briefing contratos/author.sema --json
+sema author revisar-cliches contratos/author.sema --texto "O escolhido predestinado aceitou a missão." --json
+sema author validar-narrativa contratos/author.sema --texto "Mara perdeu a chave para salvar Raul. Por isso, o capitulo seguinte muda a promessa dela." --texto-anterior "Mara prometeu proteger a chave." --json
+```
+
+O comando `author iniciar` usa os exemplos oficiais `author_obra_comum.sema` ou `author_tema_sensivel.sema` como starter. Ele não sobrescreve contrato existente.
+
+## Importadores Públicos
 
 - `nestjs`
 - `fastapi`
@@ -87,7 +148,6 @@ O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas clar
 - `angular-consumer`
 - `flutter-consumer`
 - `firebase`
-- `php`
 - `dotnet`
 - `java`
 - `go`
@@ -96,7 +156,6 @@ O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas clar
 - `typescript`
 - `python`
 - `dart`
-- `lua`
 
 ## Comandos mais usados
 
@@ -104,16 +163,13 @@ O objetivo nao e adivinhar tudo; e produzir um score explicavel com lacunas clar
 sema validar <arquivo-ou-pasta> --json
 sema diagnosticos <arquivo.sema> --json
 sema ir <arquivo.sema> --json
-sema author --help
-sema author exemplo --sensivel --json
 sema drift <arquivo-ou-pasta> --json
+sema author briefing <arquivo.sema> --json
+sema author revisar-cliches <arquivo.sema> --texto <texto> --json
+sema author validar-narrativa <arquivo.sema> --texto <texto> [--texto-anterior <texto>] --json
 sema importar <fonte> <diretorio> --saida <diretorio> --json
 sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
 sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
 sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua> --saida <diretorio>
 sema verificar <arquivo-ou-pasta> --saida <diretorio>
 ```
-
-`sema author --help` lista as regras automaticas gerais do Author. No `--json`, o campo `regrasAutomaticas` entrega essas regras para agentes e fluxos externos aplicarem sem depender de prompt solto.
-
-Quando um contrato Author gera `contexto-ia`, `resumo`, `prompt-curto` ou `SEMA_BRIEF`, os artefatos compactos tambem incluem `AUTHOR_RULES_AUTO` e `briefing.min.json.regrasAuthorAutomaticas`, para que uma IA com contexto pequeno aplique o piso editorial sem precisar abrir `ir.json`.

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

@@ -1,29 +1,35 @@
 # Como Ensinar a Sema para IA
 
-Este documento explica como fazer uma IA entender a Sema sem depender de memoria previa do modelo. A estrategia correta nao e presumir que a IA "ja conhece a linguagem", e sim entregar contexto suficiente para ela operar com seguranca.
+<!-- 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.
 
-Leia isso do ponto de vista da CLI publica. A IA nao deve assumir que esta dentro do monorepo da Sema, nem que precisa chamar `node pacotes/cli/dist/index.js`.
+
+Este documento explica como fazer uma IA entender a Sema sem depender de memória prévia do modelo. A estratégia correta não é presumir que a IA "já conhece a linguagem", e sim entregar contexto suficiente para ela operar com segurança.
+
+Leia isso do ponto de vista da CLI pública. A IA não deve assumir que está dentro do monorepo da Sema, nem que precisa chamar `node pacotes/cli/dist/index.js`.
 
 ## Principio central
 
 Uma IA entende uma linguagem nova quando recebe quatro camadas de contexto:
 
 1. sintaxe
-2. semantica
+2. semântica
 3. estrutura intermediaria estavel
 4. exemplos reais
 
-Sem essas quatro camadas, o modelo comeca a adivinhar. E adivinhacao em linguagem de contrato e pedir para nascer bug feio.
+Sem essas quatro camadas, o modelo comeca a adivinhar. É adivinhação em linguagem de contrato e pedir para nascer bug feio.
 
-Antes de qualquer outra coisa, a IA tambem precisa receber a **moldura correta**:
+Antes de qualquer outra coisa, a IA também precisa receber a **moldura correta**:
 
-- a Sema e um protocolo de governanca de intencao
-- a Sema foi feita para IA, nao para ergonomia humana
-- a Sema nao foi feita para "automatizar tudo"
+- a Sema é um contrato semântico IA-first para agentes operarem software vivo
+- a Sema foi feita para IA, não para ergonomia humana
+- a Sema não foi feita para "automatizar tudo"
 - a Sema existe para explicitar, alinhar e verificar contrato contra sistema vivo
-- curadoria humana continua parte da proposta
+- humanos sao autores, revisores e aprovadores; agentes sao consumidores primarios
 
-Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar feito um animal apressado.
+Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar por adivinhação.
 
 ## Camada 1. Sintaxe
 
@@ -33,33 +39,33 @@ Fontes principais:
 
 - [README.md](../README.md)
 - [sintaxe.md](./sintaxe.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
 
 Objetivo dessa camada:
 
 - reconhecer blocos validos
 - entender delimitadores
-- nao inventar palavras-chave
+- não inventar palavras-chave
 - respeitar a organizacao canonicamente formatada
 
-## Camada 2. Semantica
+## Camada 2. Semântica
 
 Depois de saber ler, a IA precisa saber o que cada bloco significa.
 
 Fontes principais:
 
 - [README.md](../README.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
+- [integração-com-ia.md](./integracao-com-ia.md)
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
 Objetivo dessa camada:
 
 - distinguir contrato interno de `task`
-- distinguir contrato publico de `route`
+- distinguir contrato público de `route`
 - entender `effects`, `guarantees`, `error`, `state` e `flow`
-- operar na linguagem como especificacao executavel, nao como texto decorativo
+- operar na linguagem como especificacao executavel, não como texto decorativo
 - entender que `importar` e bootstrap
-- entender que `drift` e regua de coerencia contra o runtime
+- entender que `drift` e regua de coerência contra o runtime
 - entender que `impl` e ponte rastreavel para simbolo vivo
 
 ## Camada 3. Estrutura intermediaria estavel
@@ -81,18 +87,18 @@ sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
 
 Como cada comando ajuda:
 
-- `resumo`: entrega cartao semantico pequeno para IA com janela curta
-- `validar --json`: diz se a base esta semanticamente valida
+- `resumo`: entrega cartao semântico pequeno para IA com janela curta
+- `validar --json`: diz se a base está semanticamente valida
 - `diagnosticos --json`: devolve erros e avisos como contrato estruturado
 - `ast --json`: mostra a forma sintatica escrita
-- `ir --json`: mostra a forma semantica resolvida
+- `ir --json`: mostra a forma semântica resolvida
 - `verificar --json`: mostra o estado operacional do projeto
 
-Se a IA puder consumir `ir --json`, melhor ainda. E ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Mas nao seja um animal: para modelo pequeno, comece em `resumo` e `briefing.min.json`.
+Se a IA puder consumir `ir --json`, melhor ainda. É ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Para modelo pequeno, comece em `resumo` e `briefing.min.json`.
 
 ## Camada 4. Exemplos reais
 
-Modelo aprende muito por padrao. Por isso, bons exemplos valem quase tanto quanto especificacao.
+Modelo aprende muito por padrão. Por isso, bons exemplos valem quase tanto quanto especificacao.
 
 Arquivos recomendados:
 
@@ -102,27 +108,27 @@ Arquivos recomendados:
 - [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
 - [crud_simples.sema](../exemplos/crud_simples.sema)
 
-O vertical oficial de pagamento deve ser tratado como a referencia principal.
+O vertical oficial de pagamento deve ser tratado como a referência principal.
 
-## O que a IA nao deve fazer
+## O que a IA não deve fazer
 
-- inventar palavras-chave fora da gramatica
+- inventar palavras-chave fora da gramática
 - introduzir blocos inexistentes
-- assumir semantica que nao aparece na especificacao
-- tratar draft importado como contrato final so porque veio da CLI
-- tratar a Sema como gerador magico de sistema completo
+- assumir semântica que não aparece na especificacao
+- tratar draft importado como contrato final só porque veio da CLI
+- tratar a Sema como gerador mágico de sistema completo
 - editar `.sema` sem rodar `sema formatar`
 - encerrar alteracao sem consultar `diagnosticos` quando houver falha
 
 ## O que a IA deve fazer
 
-- usar a gramatica e os exemplos como fonte de estilo
-- usar a IR como fonte de verdade semantica sempre que possivel
-- usar diagnosticos estruturados como guia de correcao
+- usar a gramática e os exemplos como fonte de estilo
+- usar a IR como fonte de verdade semântica sempre que possóvel
+- usar diagnósticos estruturados como guia de correcao
 - rodar o formatador antes de considerar o trabalho pronto
 - validar e verificar a mudanca no mesmo fluxo
 
-## Estrategia recomendada
+## Estratégia recomendada
 
 Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
 
@@ -131,19 +137,19 @@ Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta o
 3. [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 4. [prompt-base-ia-sema.md](./prompt-base-ia-sema.md)
 5. `sema resumo --micro` ou `sema resumo --curto`, conforme a capacidade da IA
-6. `ast --json`, `ir --json` e `diagnosticos --json` do modulo alvo, se a capacidade aguentar
+6. `ast --json`, `ir --json` e `diagnosticos --json` do módulo alvo, se a capacidade aguentar
 
 Essa ordem faz a IA ir de contexto geral para contexto operacional, em vez de cair direto num arquivo cru e sair chutando.
 
 ## Regra de ouro
 
-A Sema foi desenhada para ser entendida por IA, mas isso nao significa que a IA vai adivinhar sozinha.
+A Sema foi desenhada para ser entendida por IA, mas isso não significa que a IA vai adivinhar sozinha.
 
 Ela entende bem quando recebe:
 
 - especificacao
 - exemplos
 - JSON estrutural
-- feedback automatico
+- feedback automático
 
-Sem isso, ate o modelo mais caro vira estagiario emocionado.
+Sem isso, até o modelo mais caro vira estagiário emocionado.

package/docs/deploy.md

@@ -1,70 +1,258 @@
 # Deploy
 
-Este runbook governa a publicacao publica da Sema: CLI, MCP, VSIX, instaladores e release assets.
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
 
-## Pre-condicoes
+## EN
 
-- `sema resumo` executado no projeto antes da mudanca.
-- `sema inspecionar contratos/sema/governanca_ia.sema --json` executado para confirmar o contrato relacionado.
-- `sema drift contratos/sema/governanca_ia.sema --escopo modulo --json` sem diagnosticos bloqueantes.
-- `sema docs-impacto --intencao "<release>" --criar-ausentes --json` executado e todos os docs obrigatorios lidos.
-- `npm whoami` autenticado com uma conta que pode publicar `@semacode/cli` e `@semacode/mcp`.
-- `gh auth status` autenticado com permissao de push e release em `gerlanss/Sema`.
-- Workspace revisado para nao incluir lixo local, caches ou artefatos temporarios fora de `.tmp/`.
+This runbook covers two different deploy surfaces for Sema:
 
-## Sequencia segura
+- Sema public website and private MCP server at `https://sema.otimitare.online`.
+- Public package releases for CLI/VSIX/NPM/GitHub.
 
-1. Escolha uma versao que ainda nao exista no NPM.
-2. Atualize `package.json`, workspaces, lockfiles, changelog e docs antes de empacotar.
-3. Rode `npm run build`.
-4. Rode os testes focados e checagens de release.
-5. Rode `npm run release:preparar-publica` para gerar `.tmp/release-assets`.
-6. Publique NPM com `npm run release:publicar-npm`.
-7. Instale a CLI e o MCP publicados para smoke test.
-8. Empacote e instale a VSIX localmente para smoke test da extensao.
-9. Rode `sema finalizar-mudanca` com as docs lidas antes de concluir.
-10. Commit, push, tag e GitHub Release com os assets gerados.
+The production website/MCP target is the **Sema VPS**, not the OtimiTare application VPS.
 
-## Validacao minima
+### Sema Production VPS
+
+Operational facts:
+
+- Domain: `sema.otimitare.online`
+- Current public DNS target: resolve the domain before deploy, do not trust an old IP.
+- SSH user: use the operational server user configured outside this repository.
+- SSH identity: resolve it from local SSH config or a secret manager outside this repository.
+- Static site root: `/srv/sema/site`
+- Caddy config in this repo: `deploy/caddy/sema-site.Caddyfile`
+- MCP service: `sema-mcp.service`
+- MCP upstream: `127.0.0.1:3010`
+
+Do not use the stale `otimitare` SSH alias for Sema deploy. It points to an old host/key pair and is not the source of truth.
+
+Never commit private key content, private-key filenames, local key paths, IPs that are not already public DNS, or secret inventory details.
+
+### Website Deploy
+
+Before publishing:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirm the target:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Create a remote backup and publish static files:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Validate after deploy:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
+
+Expected result:
+
+- `/healthz` returns healthy.
+- `/painel.html` serves the current static panel.
+- `/mcp` without token does not expose data; it should return an auth challenge or unauthorized response.
+
+### Public Package Release
+
+Before publishing a CLI or VSIX release:
 
 ```bash
 npm run build
 npm run format:check
 npm run status:check
-node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia|mcp cli responde" testes/integracao/cli-json-e-editor.test.ts
+node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia" testes/integracao/cli-json-e-editor.test.ts
 sema validar contratos/sema/governanca_ia.sema --json
 sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
+npm run release:verificar-versao
 ```
 
-Depois de publicar:
+Then:
 
 ```bash
+npm run release:preparar-publica
+npm run release:publicar-npm
 npm view @semacode/cli version
-npm view @semacode/mcp version
 npm install -g @semacode/cli@<versao>
-npm install -g @semacode/mcp@<versao>
 sema --version
-sema docs-impacto --intencao "smoke release" --json
-sema-mcp --help
+npm run release:verificar-publica
 ```
 
-## Release assets
+Stop if NPM already has the version, `gh auth status` fails, `npm whoami` fails, Sema validation fails, or release verification finds a mismatch.
 
-`npm run release:preparar-publica` deve gerar:
+## PT
 
-- `sema-cli-<versao>.tgz`
-- `sema-cli-latest.tgz`
-- `sema-language-tools-<versao>.vsix`
-- `sema-language-tools-latest.vsix`
-- `install-sema.sh`
-- `install-sema.ps1`
-- `SHA256SUMS.txt`
-- `release-notes.md`
+Este runbook cobre duas superfícies diferentes de deploy da Sema:
+
+- site público e servidor MCP privado em `https://sema.otimitare.online`;
+- releases públicos de CLI/VSIX/NPM/GitHub.
+
+O alvo de produção do site/MCP é a **VPS da Sema**, não a VPS da aplicação OtimiTare.
+
+### VPS de Produção da Sema
+
+Fatos operacionais:
+
+- Domínio: `sema.otimitare.online`
+- DNS público atual: resolva o domínio antes do deploy; não confie em IP antigo.
+- Usuário SSH: use o usuário operacional do servidor configurado fora deste repositório.
+- Identidade SSH: resolva pelo SSH config local ou secret manager fora deste repositório.
+- Raiz do site estático: `/srv/sema/site`
+- Configuração Caddy neste repositório: `deploy/caddy/sema-site.Caddyfile`
+- Serviço MCP: `sema-mcp.service`
+- Upstream MCP: `127.0.0.1:3010`
+
+Não use o alias SSH antigo `otimitare` para deploy da Sema. Ele aponta para host/chave antigos e não é fonte da verdade.
+
+Nunca commite conteúdo de chave privada, nomes de arquivos de chave privada, caminhos locais de chave, IPs que não sejam DNS público ou detalhes do inventário de segredos.
+
+### Deploy do Site
+
+Antes de publicar:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirme o alvo:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Crie backup remoto e publique os arquivos estáticos:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Valide depois do deploy:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
+
+Resultado esperado:
+
+- `/healthz` responde saudável.
+- `/painel.html` serve o painel estático atual.
+- `/mcp` sem token não expõe dados; deve devolver desafio de autenticação ou não autorizado.
+
+### Release Público
+
+Antes de publicar CLI ou VSIX:
+
+```bash
+npm run build
+npm run format:check
+npm run status:check
+node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia" testes/integracao/cli-json-e-editor.test.ts
+sema validar contratos/sema/governanca_ia.sema --json
+sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
+npm run release:verificar-versao
+```
+
+Depois:
+
+```bash
+npm run release:preparar-publica
+npm run release:publicar-npm
+npm view @semacode/cli version
+npm install -g @semacode/cli@<versao>
+sema --version
+npm run release:verificar-publica
+```
+
+Pare se a versão já existir no NPM, `gh auth status` falhar, `npm whoami` falhar, a validação Sema falhar ou a verificação de release encontrar desalinhamento.
+
+## ES
+
+Este runbook cubre dos superficies distintas de despliegue de Sema:
+
+- sitio público y servidor MCP privado en `https://sema.otimitare.online`;
+- releases públicos de CLI/VSIX/NPM/GitHub.
+
+El destino de producción del sitio/MCP es la **VPS de Sema**, no la VPS de la aplicación OtimiTare.
+
+### VPS de Producción de Sema
+
+Datos operativos:
+
+- Dominio: `sema.otimitare.online`
+- DNS público actual: resuelve el dominio antes del despliegue; no confíes en una IP antigua.
+- Usuario SSH: usa el usuario operativo del servidor configurado fuera de este repositorio.
+- Identidad SSH: resuélvela desde el SSH config local o secret manager fuera de este repositorio.
+- Raíz del sitio estático: `/srv/sema/site`
+- Configuración Caddy en este repositorio: `deploy/caddy/sema-site.Caddyfile`
+- Servicio MCP: `sema-mcp.service`
+- Upstream MCP: `127.0.0.1:3010`
+
+No uses el alias SSH antiguo `otimitare` para desplegar Sema. Apunta a un host/par de llaves antiguo y no es la fuente de verdad.
+
+Nunca hagas commit del contenido de la llave privada, nombres de archivos de llave privada, rutas locales de llaves, IPs que no sean DNS público o detalles del inventario de secretos.
+
+### Despliegue del Sitio
+
+Antes de publicar:
+
+```powershell
+node pacotes\cli\dist\index.js validar contratos\sema\site_publico.sema --json
+node pacotes\cli\dist\index.js drift contratos\sema\site_publico.sema --escopo modulo --json
+npm run build
+npm run format:check
+```
+
+Confirma el destino:
+
+```powershell
+Resolve-DnsName sema.otimitare.online
+ssh sema-vps "hostname; systemctl is-active sema-mcp.service; ls -ld /srv/sema/site"
+```
+
+Crea backup remoto y publica los archivos estáticos:
+
+```powershell
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+ssh sema-vps "mkdir -p /srv/sema/backups/site-$stamp && cp -a /srv/sema/site/. /srv/sema/backups/site-$stamp/"
+scp -r site\sema\* sema-vps:/srv/sema/site/
+```
+
+Valida después del despliegue:
+
+```powershell
+curl.exe -k -fsS https://sema.otimitare.online/healthz
+curl.exe -k -fsS https://sema.otimitare.online/painel.html
+curl.exe -k -fsS -D - https://sema.otimitare.online/mcp -o NUL
+```
 
-## Sinais de parada
+Resultado esperado:
 
-- NPM ja tem a versao escolhida.
-- `npm whoami` falha.
-- `gh auth status` falha.
-- `sema validar`, `sema drift`, build ou testes falham.
-- `release:preparar-publica` encontra versoes desalinhadas entre root, CLI, MCP e extensao.
+- `/healthz` responde saludable.
+- `/painel.html` sirve el panel estático actual.
+- `/mcp` sin token no expone datos; debe devolver desafío de autenticación o no autorizado.