@semacode/cli 1.5.27 → 1.5.29

package/docs/deploy.md

@@ -0,0 +1,93 @@
+# Public Release Runbook
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois.
+> ES: Español al final.
+
+## English
+
+This public runbook covers only the open Sema distribution: source repository, npm CLI package, VS Code extension artifact, release notes, checksums, and public install scripts.
+
+Private hosting, account panels, OAuth endpoints, Supabase projects, billing flows, service accounts, customer data, server paths, and commercial deployment scripts belong in the private repository.
+
+### What Goes Public
+
+- Versioned source for the open language, parser, CLI, base profiles, examples, public docs, and basic extension.
+- Public release assets generated under `.tmp/release-assets`.
+- Generic install scripts that do not embed tokens, private URLs, customer identifiers, or server paths.
+- Release notes in this order: English, Portuguese, Spanish.
+
+### What Stays Private
+
+- Hosted-site code, account panel code, billing, Supabase migrations, OAuth client secrets, MCP key issuing, production Caddy/Nginx files, and server-specific runbooks.
+- Any token, service role, customer identifier, database URL, private endpoint, or local agent configuration.
+- Commercial rule packs and internal dashboards until explicitly approved for public release.
+
+### Public Release Checklist
+
+1. Run `npm run repo:verificar-publico`.
+2. Run `npm run project:check`.
+3. Run `npm run release:preparar-publica`.
+4. Publish the npm package only after `npm dist-tag ls @semacode/cli` can be checked.
+5. Push `main` and the matching `v<version>` tag.
+6. Create the GitHub Release from `.tmp/release-assets` and mark it as latest.
+7. Confirm the GitHub About description is English and product-facing.
+
+## Português
+
+Este runbook público cobre apenas a distribuição aberta da Sema: repositório-fonte, pacote npm da CLI, artefato da extensão VS Code, notas de release, checksums e instaladores públicos.
+
+Hospedagem privada, painéis de conta, endpoints OAuth, projetos Supabase, billing, service accounts, dados de clientes, caminhos de servidor e scripts comerciais de deploy ficam no repositório privado.
+
+### O Que Vai Para o Público
+
+- Código versionado da linguagem aberta, parser, CLI, profiles base, exemplos, docs públicas e extensão básica.
+- Assets públicos de release gerados em `.tmp/release-assets`.
+- Instaladores genéricos sem tokens, URLs privadas, identificadores de cliente ou caminhos de servidor.
+- Notas de release nesta ordem: inglês, português, espanhol.
+
+### O Que Fica Privado
+
+- Código do site hospedado, painel de contas, billing, migrations Supabase, OAuth client secrets, emissão de chaves MCP, Caddy/Nginx de produção e runbooks específicos de servidor.
+- Qualquer token, service role, identificador de cliente, URL de banco, endpoint privado ou configuração local de agentes.
+- Rule packs comerciais e dashboards internos até aprovação explícita para release pública.
+
+### Checklist De Release Pública
+
+1. Rode `npm run repo:verificar-publico`.
+2. Rode `npm run project:check`.
+3. Rode `npm run release:preparar-publica`.
+4. Publique o pacote npm somente depois de conseguir conferir `npm dist-tag ls @semacode/cli`.
+5. Envie `main` e a tag `v<versão>` correspondente.
+6. Crie o GitHub Release a partir de `.tmp/release-assets` e marque como latest.
+7. Confirme que o About do GitHub está em inglês e com posicionamento de produto.
+
+## Español
+
+Este runbook público cubre solo la distribución abierta de Sema: repositorio fuente, paquete npm de la CLI, artefacto de la extensión VS Code, notas de release, checksums e instaladores públicos.
+
+El hosting privado, los paneles de cuenta, endpoints OAuth, proyectos Supabase, billing, service accounts, datos de clientes, rutas de servidor y scripts comerciales de despliegue pertenecen al repositorio privado.
+
+### Qué Va Al Público
+
+- Código versionado del lenguaje abierto, parser, CLI, profiles base, ejemplos, docs públicas y extensión básica.
+- Assets públicos de release generados en `.tmp/release-assets`.
+- Instaladores genéricos sin tokens, URLs privadas, identificadores de cliente ni rutas de servidor.
+- Notas de release en este orden: inglés, portugués, español.
+
+### Qué Queda Privado
+
+- Código del sitio hospedado, panel de cuentas, billing, migrations Supabase, OAuth client secrets, emisión de claves MCP, Caddy/Nginx de producción y runbooks específicos de servidor.
+- Cualquier token, service role, identificador de cliente, URL de base de datos, endpoint privado o configuración local de agentes.
+- Rule packs comerciales y dashboards internos hasta aprobación explícita para release pública.
+
+### Checklist De Release Pública
+
+1. Ejecuta `npm run repo:verificar-publico`.
+2. Ejecuta `npm run project:check`.
+3. Ejecuta `npm run release:preparar-publica`.
+4. Publica el paquete npm solo después de poder verificar `npm dist-tag ls @semacode/cli`.
+5. Envía `main` y la tag `v<versión>` correspondiente.
+6. Crea el GitHub Release desde `.tmp/release-assets` y márcalo como latest.
+7. Confirma que el About de GitHub está en inglés y con posicionamiento de producto.

package/docs/documentacao.md

@@ -1,88 +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
-```
+# 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

@@ -1,105 +1,105 @@
-# 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.27 -WithVSCode
-```
-
-No shell:
-
-```bash
-SEMA_VERSION=1.5.27 ./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 `;`.
-
-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"
-```
-
-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.
-
-## GitHub Release
-
-O tag público deve seguir `v<versao>`, por exemplo `v1.5.27`.
-
-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.
+# 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 `;`.
+
+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"
+```
+
+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.
+
+## 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

@@ -1,53 +1,53 @@
-# Extensao VS Code
-
-<!-- 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.
-
-
-Runbook da extensao `Sema Language Tools`.
-
-## Arquivos principais
-
-- `pacotes/editor-vscode/package.json`
-- `pacotes/editor-vscode/extension.js`
-- `pacotes/editor-vscode/server.js`
-- `pacotes/editor-vscode/README.md`
-- `pacotes/editor-vscode/CHANGELOG.md`
-
-## Empacotar
-
-```bash
-npm run extensao:empacotar
-```
-
-O pacote versionado deve aparecer em `.tmp/editor-vscode/sema-language-tools-<versao>.vsix`.
-
-## Instalar localmente
-
-```bash
-npm run extensao:instalar-local
-```
-
-Ou:
-
-```bash
-code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --force
-```
-
-## Smoke test
-
-1. Abra um projeto com `.sema`.
-2. Confirme que o Language Server inicia sem crash.
-3. Rode `Sema: Diagnosticar CLI`.
-4. Rode `Sema: Instalar Chave MCP`, cole uma chave `sema_mcp_*` do painel e confirme que a CLI grava a variavel do usuario sem argumento com segredo.
-5. Rode `Sema: Sincronizar EntryPoints IA do Projeto`.
-6. Abra um `.sema` e confirme diagnosticos, highlight e formatacao.
-
-## Cuidados
-
-- O `extension.js` deve apontar o LSP para `server.js`.
-- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP privadas quando novos comandos remotos forem adicionados.
-- A chave MCP do painel deve ser instalada via comando da extensao ou `sema mcp-instalar-chave --stdin`; nao trate `SEMA_MCP_AUTH_TOKEN` como token fixo do servidor.
-- A versão da extensao deve bater com a versão pública preparada por `release:preparar-publica`.
+# Extensao VS Code
+
+<!-- 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.
+
+
+Runbook da extensao `Sema Language Tools`.
+
+## Arquivos principais
+
+- `pacotes/editor-vscode/package.json`
+- `pacotes/editor-vscode/extension.js`
+- `pacotes/editor-vscode/server.js`
+- `pacotes/editor-vscode/README.md`
+- `pacotes/editor-vscode/CHANGELOG.md`
+
+## Empacotar
+
+```bash
+npm run extensao:empacotar
+```
+
+O pacote versionado deve aparecer em `.tmp/editor-vscode/sema-language-tools-<versao>.vsix`.
+
+## Instalar localmente
+
+```bash
+npm run extensao:instalar-local
+```
+
+Ou:
+
+```bash
+code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --force
+```
+
+## Smoke test
+
+1. Abra um projeto com `.sema`.
+2. Confirme que o Language Server inicia sem crash.
+3. Rode `Sema: Diagnosticar CLI`.
+4. Rode `Sema: Instalar Chave MCP`, cole uma chave `sema_mcp_*` do painel e confirme que a CLI grava a variavel do usuario sem argumento com segredo.
+5. Rode `Sema: Sincronizar EntryPoints IA do Projeto`.
+6. Abra um `.sema` e confirme diagnosticos, highlight e formatacao.
+
+## Cuidados
+
+- O `extension.js` deve apontar o LSP para `server.js`.
+- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP privadas quando novos comandos remotos forem adicionados.
+- A chave MCP do painel deve ser instalada via comando da extensao ou `sema mcp-instalar-chave --stdin`; nao trate `SEMA_MCP_AUTH_TOKEN` como token fixo do servidor.
+- A versão da extensao deve bater com a versão pública preparada por `release:preparar-publica`.