@semacode/cli 1.5.30 → 1.5.32

package/docs/api.md

@@ -0,0 +1,82 @@
+# API and Operational Surfaces
+
+## English
+
+Sema's public repository exposes the open language, CLI, contracts, examples, and editor support. It does not expose the private hosted MCP control plane, account APIs, OAuth internals, dashboards, audit storage, or commercial runtime governance APIs.
+
+### Public Surfaces
+
+- CLI commands documented in `README.md`, `docs/README.md`, and `docs/profiles.md`.
+- `.sema` contracts under `contratos/` and public examples under `exemplos/`.
+- Release artifacts generated by the public release scripts.
+- Editor support and local validation flows.
+
+### Private Or Commercial Surfaces
+
+- Hosted MCP endpoint and OAuth authorization flows.
+- Account, project, usage, billing, dashboard, and audit APIs.
+- Runtime governance, approval gates, private rule packs, and advanced artifact validation.
+- Deployment secrets, environment files, local runbooks, and infrastructure-specific scripts.
+
+### API Rule For Agents
+
+When a change touches an endpoint, webhook, CLI command, or MCP tool, the agent must:
+
+- declare or update the applicable `.sema` contract before code;
+- validate authentication, authorization, tenant/workspace boundaries, idempotency, auditability, and rollback expectations;
+- keep private endpoints and commercial control-plane details out of the public repository;
+- run Sema validation and public repository boundary checks before release.
+
+## Português
+
+O repositório público do Sema expõe a linguagem aberta, CLI, contratos, exemplos e suporte de editor. Ele não expõe o control plane MCP hospedado, APIs de conta, detalhes internos de OAuth, dashboards, armazenamento de auditoria ou APIs comerciais de runtime governance.
+
+### Superfícies Públicas
+
+- Comandos da CLI documentados em `README.md`, `docs/README.md` e `docs/profiles.md`.
+- Contratos `.sema` em `contratos/` e exemplos públicos em `exemplos/`.
+- Artefatos de release gerados pelos scripts públicos de release.
+- Suporte de editor e fluxos locais de validação.
+
+### Superfícies Privadas Ou Comerciais
+
+- Endpoint MCP hospedado e fluxos de autorização OAuth.
+- APIs de conta, projeto, uso, cobrança, dashboard e auditoria.
+- Runtime governance, approval gates, rule packs privados e validação avançada de artefatos.
+- Segredos de deploy, arquivos de ambiente, runbooks locais e scripts específicos de infraestrutura.
+
+### Regra De API Para Agentes
+
+Quando uma mudança toca endpoint, webhook, comando de CLI ou ferramenta MCP, a IA deve:
+
+- declarar ou atualizar o contrato `.sema` aplicável antes do código;
+- validar autenticação, autorização, fronteira de tenant/workspace, idempotência, auditoria e expectativa de rollback;
+- manter endpoints privados e detalhes comerciais do control plane fora do repositório público;
+- rodar validação Sema e checagem de fronteira pública antes do release.
+
+## Español
+
+El repositorio público de Sema expone el lenguaje abierto, CLI, contratos, ejemplos y soporte de editor. No expone el control plane MCP hospedado, APIs de cuenta, detalles internos de OAuth, dashboards, almacenamiento de auditoría ni APIs comerciales de runtime governance.
+
+### Superficies Públicas
+
+- Comandos de la CLI documentados en `README.md`, `docs/README.md` y `docs/profiles.md`.
+- Contratos `.sema` en `contratos/` y ejemplos públicos en `exemplos/`.
+- Artefactos de release generados por los scripts públicos de release.
+- Soporte de editor y flujos locales de validación.
+
+### Superficies Privadas O Comerciales
+
+- Endpoint MCP hospedado y flujos de autorización OAuth.
+- APIs de cuenta, proyecto, uso, facturación, dashboard y auditoría.
+- Runtime governance, approval gates, rule packs privados y validación avanzada de artefactos.
+- Secretos de deploy, archivos de entorno, runbooks locales y scripts específicos de infraestructura.
+
+### Regla De API Para Agentes
+
+Cuando un cambio toca un endpoint, webhook, comando de CLI o herramienta MCP, la IA debe:
+
+- declarar o actualizar el contrato `.sema` aplicable antes del código;
+- validar autenticación, autorización, frontera de tenant/workspace, idempotencia, auditoría y expectativa de rollback;
+- mantener endpoints privados y detalles comerciales del control plane fuera del repositorio público;
+- ejecutar validación Sema y chequeo de frontera pública antes del release.

package/docs/cli.md

@@ -0,0 +1,93 @@
+# Sema CLI
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois.
+> ES: Español al final.
+
+## English
+
+The Sema CLI is installed from the public npm package `@semacode/cli`. It is not the commercial coordinator and it does not publish the MCP server or product control plane.
+
+Use it for the work the MCP authorizes:
+
+- validate `.sema` contracts;
+- inspect modules, tasks, routes, and effects;
+- check drift against live or selected code;
+- map impact;
+- prepare AI-first context;
+- resolve documentation gates;
+- run profile and pipeline validators;
+- execute local or VPS-side project actions.
+
+The private MCP decides when to charge SEMAS and which operation can continue. The CLI executes the technical work in the environment where it has file access.
+
+```bash
+npm install -g @semacode/cli
+```
+
+```bash
+sema resumo . --curto
+sema validar contratos/pedidos.sema --json
+sema drift contratos/pedidos.sema --escopo modulo --json
+sema docs-impacto --intencao "alterar pedidos" --arquivo contratos/pedidos.sema --json
+sema finalizar-mudanca --intencao "alterar pedidos" --doc-lida README.md --json
+```
+
+## Português
+
+A CLI da Sema é instalada pelo pacote npm público `@semacode/cli`. Ela não é o coordenador comercial e não publica o servidor MCP nem o control plane do produto.
+
+Use a CLI para o trabalho que o MCP autorizar:
+
+- validar contratos `.sema`;
+- inspecionar módulos, tasks, rotas e efeitos;
+- medir drift contra código vivo ou código selecionado;
+- mapear impacto;
+- preparar contexto IA-first;
+- resolver gates de documentação;
+- rodar validadores de profiles e pipelines;
+- executar ações locais ou na VPS.
+
+O MCP privado decide quando cobrar SEMAS e qual operação pode continuar. A CLI executa o trabalho técnico no ambiente onde tem acesso aos arquivos.
+
+```bash
+npm install -g @semacode/cli
+```
+
+```bash
+sema resumo . --curto
+sema validar contratos/pedidos.sema --json
+sema drift contratos/pedidos.sema --escopo modulo --json
+sema docs-impacto --intencao "alterar pedidos" --arquivo contratos/pedidos.sema --json
+sema finalizar-mudanca --intencao "alterar pedidos" --doc-lida README.md --json
+```
+
+## Español
+
+La CLI de Sema se instala desde el paquete npm público `@semacode/cli`. No es el coordinador comercial y no publica el servidor MCP ni el control plane del producto.
+
+Usa la CLI para el trabajo que el MCP autorice:
+
+- validar contratos `.sema`;
+- inspeccionar módulos, tasks, rutas y efectos;
+- medir drift contra código vivo o código seleccionado;
+- mapear impacto;
+- preparar contexto IA-first;
+- resolver gates de documentación;
+- ejecutar validadores de profiles y pipelines;
+- ejecutar acciones locales o en la VPS.
+
+El MCP privado decide cuándo cobrar SEMAS y qué operación puede continuar. La CLI ejecuta el trabajo técnico en el entorno donde tiene acceso a los archivos.
+
+```bash
+npm install -g @semacode/cli
+```
+
+```bash
+sema resumo . --curto
+sema validar contratos/pedidos.sema --json
+sema drift contratos/pedidos.sema --escopo modulo --json
+sema docs-impacto --intencao "alterar pedidos" --arquivo contratos/pedidos.sema --json
+sema finalizar-mudanca --intencao "alterar pedidos" --doc-lida README.md --json
+```

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

@@ -0,0 +1,30 @@
+# Como Ensinar a Sema para IA
+
+<!-- sema:i18n -->
+> EN: English first.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final.
+
+## English
+
+Sema is taught to an AI through operational context, not through vague explanations. The agent needs syntax, semantics, intermediate representation, examples, and the project contract before it touches code or documents.
+
+In local IDEs, the first step is to confirm that `AGENTS.md` exists in the project root. If it does not exist, download `https://sema.otimitare.online/AGENTS.md` into the project. In web chats, do not download files into the chat environment; use `sema_chat_contexto`, `sema_sync`, and inline content.
+
+The correct framing is simple: contract first, evidence before action, and no guessing from raw code when Sema can provide summary, drift, impact, and required docs.
+
+## Português
+
+A Sema é ensinada para IA por contexto operacional, não por explicação vaga. O agente precisa de sintaxe, semântica, representação intermediária, exemplos e contrato do projeto antes de tocar código ou documentos.
+
+Em IDE local, o primeiro passo é confirmar que `AGENTS.md` existe na raiz do projeto. Se não existir, baixe `https://sema.otimitare.online/AGENTS.md` para o projeto. Em chats web, não baixe arquivos no ambiente do chat; use `sema_chat_contexto`, `sema_sync` e conteúdo inline.
+
+A moldura correta é simples: contrato primeiro, evidência antes da ação e nada de adivinhar lendo código cru quando a Sema pode entregar resumo, drift, impacto e docs obrigatórias.
+
+## Español
+
+Sema se enseña a una IA con contexto operativo, no con explicaciones vagas. El agente necesita sintaxis, semántica, representación intermedia, ejemplos y contrato del proyecto antes de tocar código o documentos.
+
+En IDE local, el primer paso es confirmar que `AGENTS.md` existe en la raíz del proyecto. Si no existe, descarga `https://sema.otimitare.online/AGENTS.md` en el proyecto. En chats web, no descargues archivos en el entorno del chat; usa `sema_chat_contexto`, `sema_sync` y contenido inline.
+
+El encuadre correcto es simple: contrato primero, evidencia antes de la acción y nada de adivinar leyendo código crudo cuando Sema puede entregar resumen, drift, impacto y docs obligatorias.

package/docs/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.