@semacode/cli 1.5.28 → 1.5.30

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

@@ -1,187 +0,0 @@
-# Fluxo Pratico para IA Antes de Editar `.sema`
-
-<!-- sema:i18n -->
-> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
-
-
-Este documento descreve o fluxo operacional recomendado para qualquer IA antes, durante e depois de alterar arquivos `.sema`.
-
-Se a IA seguir isso, ela trabalha com contexto. Se não seguir, vira adivinhação gourmet.
-
-O ponto central: Sema não é texto para agradar humano. É contrato semântico IA-first. Humanos autorizam e revisam; a IA consome o contrato para decidir o próximo movimento.
-
-## Fluxo curto
-
-1. ler contexto do projeto
-2. identificar a capacidade da IA
-3. identificar o módulo alvo
-4. consultar o menor artefato semântico suficiente
-5. editar
-6. formatar
-7. validar
-8. verificar
-
-## Fluxo detalhado
-
-### Etapa 1. Ler contexto mínimo
-
-Antes de tocar em qualquer arquivo, a IA deve ler:
-
-- [README.md](../README.md)
-- [integração-com-ia.md](./integracao-com-ia.md)
-- [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
-
-Se o trabalho estiver ligado a pagamento, ler também:
-
-- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
-
-### Etapa 2. Escolher a faixa de capacidade
-
-Antes de despejar contexto na IA, escolha o que ela aguenta:
-
-- IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
-- IA média: `sema resumo --curto`, `briefing.min.json` e `drift.json`
-- IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-### Etapa 3. Ler o módulo alvo e um exemplo parecido
-
-A IA deve identificar:
-
-- qual arquivo sera editado
-- qual módulo esse arquivo representa
-- qual exemplo oficial mais se parece com o que precisa ser feito
-
-Regra pratica:
-
-- automacao: [automacao.sema](../exemplos/automacao.sema)
-- erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
-- borda pública e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
-
-### Etapa 4. Consultar AST e IR quando fizer sentido
-
-Antes de alterar, a IA deve executar:
-
-```bash
-sema resumo caminho/arquivo.sema --curto --para mudanca
-sema ast caminho/arquivo.sema --json
-sema ir caminho/arquivo.sema --json
-```
-
-Objetivo:
-
-- ver a forma sintatica quando a capacidade aguentar
-- ver a forma semântica resolvida quando a capacidade aguentar
-- evitar interpretar errado o contrato
-
-### Etapa 5. Editar o `.sema`
-
-Ao editar, a IA deve:
-
-- preservar a intenção do módulo
-- seguir a gramática existente
-- evitar criar bloco ou operador não suportado
-- preferir a forma já usada nos exemplos oficiais
-- usar blocos existentes como `auth`, `authz`, `dados`, `audit`, `forbidden`, `execucao`, `use`, `state` e `enum` antes de propor sintaxe nova
-- evitar teste fraco em task sensível; `expect { sucesso: verdadeiro }` sozinho não prova semântica operacional
-
-### Etapa 6. Formatar
-
-Depois da edição:
-
-```bash
-sema formatar caminho/arquivo.sema
-sema formatar caminho/arquivo.sema --check
-```
-
-Se `--check` falhar, o trabalho ainda não está pronto.
-
-### Etapa 7. Validar e diagnosticar
-
-Depois da formatacao:
-
-```bash
-sema validar caminho/arquivo.sema --json
-sema diagnosticos caminho/arquivo.sema --json
-```
-
-Se houver falha:
-
-- usar os diagnósticos estruturados como contrato de correcao
-- não insistir em leitura manual teimosa quando a CLI já disse onde está a merda
-
-### Etapa 7.5. Compilar quando a tarefa pedir código derivado
-
-Se a tarefa não for só editar contrato, mas também gerar base de implementacao, a IA deve rodar explicitamente:
-
-```bash
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-Ou trocar o alvo para `python` ou `dart`, conforme o caso.
-
-Regra pratica:
-
-- se a entrega inclui código derivado, `sema compilar` não é opcional
-- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema já gera sozinha, que é burrice operacional
-
-### Etapa 8. Verificar
-
-No fechamento:
-
-```bash
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-## Fluxo mínimo para automacao
-
-Se voce quiser o menor fluxo aceitavel para uma IA pequena:
-
-```bash
-sema resumo caminho/arquivo.sema --micro --para mudanca
-sema formatar caminho/arquivo.sema
-sema validar caminho/arquivo.sema --json
-```
-
-Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
-
-Se a tarefa envolver código derivado, o fluxo mínimo aceitavel vira:
-
-```bash
-sema ir caminho/arquivo.sema --json
-sema formatar caminho/arquivo.sema
-sema validar caminho/arquivo.sema --json
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-## Checklist de saída
-
-Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
-
-- eu entendi o módulo e o contrato?
-- eu mantive a sintaxe dentro do que a linguagem suporta?
-- eu formatei o arquivo?
-- eu validei?
-- eu olhei diagnósticos se algo falhou?
-- eu fechei com verificação?
-
-Se alguma resposta for "não", ainda não terminou.
-
-## Regra de ouro
-
-Em Sema, a IA não deveria operar no escuro.
-
-Ela deve trabalhar sempre com:
-
-- exemplo oficial
-- AST
-- IR
-- diagnósticos
-- formatador
-
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e não só no discurso bonito.
-
-## Observacao sobre caminhos
-
-Está documentação usa placeholders de arquivo e pasta, não caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface pública principal.

package/docs/instalacao-e-primeiro-uso.md

@@ -1,134 +0,0 @@
-# Installation And First Use
-
-## English
-
-This guide covers the current public installation path for the Sema CLI and VS Code extension. The remote MCP server is a private/commercial authorized service and is not distributed as a public npm package.
-
-Current public version: `1.5.28`.
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-```
-
-## Português
-
-Este guia cobre o caminho público atual da Sema para CLI e extensão VS Code. O servidor MCP remoto é um serviço privado/comercial autorizado e não é distribuído como pacote npm público.
-
-Versão pública atual: `1.5.28`.
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-```
-
-## Español
-
-Esta guía cubre el camino público actual de instalación para la CLI de Sema y la extensión de VS Code. El servidor MCP remoto es un servicio privado/comercial autorizado y no se distribuye como paquete público de npm.
-
-Versión pública actual: `1.5.28`.
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-```
-
-## Referência Operacional
-
-## Requisitos
-
-- Node.js LTS
-- npm funcional
-- Python 3 só se você quiser rodar testes Python gerados
-
-## CLI
-
-Instalação principal:
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-sema docs-impacto --intencao "alterar projeto" --json
-```
-
-Instalação de uma versão específica pelo npm:
-
-```bash
-npm install -g @semacode/cli@1.5.28
-```
-
-Instalação local ao projeto:
-
-```bash
-npm install @semacode/cli
-npx sema --help
-```
-
-## MCP
-
-O MCP da Sema não é mais instalado por npm público. Ele é uma superfície privada/comercial acessada por endpoint remoto, normalmente `https://<host>/mcp`, com OAuth ou bearer configurado fora deste repositório. Veja [mcp.md](./mcp.md).
-
-## Instaladores oficiais
-
-Linux ou macOS:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash
-```
-
-Windows PowerShell:
-
-```powershell
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.ps1 -OutFile install-sema.ps1
-.\install-sema.ps1
-```
-
-Se quiser uma tag específica, troque `main` pela versão desejada.
-
-## Extensão VS Code
-
-```bash
-npm run extensao:empacotar
-code --install-extension .tmp/editor-vscode/sema-language-tools-1.5.28.vsix --force
-```
-
-Os assets versionados da VSIX devem ser anexados manualmente a GitHub Releases quando houver release pública com binários. Se `--with-vscode` for usado antes disso, o instalador mantém a CLI instalada e apenas pula a extensão.
-
-## Primeiro teste
-
-```bash
-mkdir sema-demo
-cd sema-demo
-sema iniciar
-sema validar contratos/pedidos.sema --json
-```
-
-## Primeiro fluxo útil
-
-```bash
-sema validar contratos/pedidos.sema --json
-sema ir contratos/pedidos.sema --json
-sema formatar contratos/pedidos.sema
-sema verificar contratos --saida ./.tmp/verificacao
-```
-
-## Primeiro fluxo IA-first
-
-```bash
-sema inspecionar . --json
-sema resumo contratos/pedidos.sema --micro --para onboarding
-sema drift contratos/pedidos.sema --escopo modulo --json
-sema impacto contratos/pedidos.sema --alvo pedido_id --mudanca "trocar pedido_id por pedido_uuid" --json
-sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto --json
-```
-
-## Primeiro fluxo de persistência vendor-first
-
-```bash
-sema validar contratos/sema/persistencia_vendor_first.sema --json
-sema ir contratos/sema/persistencia_vendor_first.sema --json
-```

package/docs/integracao-com-ia.md

@@ -1,110 +0,0 @@
-# Integração com IA
-
-<!-- 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 foi feita para IA operar software vivo com menos adivinhação. O consumidor principal não é o humano lendo arquivo bonito; e o agente decidindo o que pode tocar, que efeito vai causar e como validar antes de mexer no código vivo.
-
-Humanos entram como autores, revisores e aprovadores do contrato. A ponte da Sema e da intenção operacional para um formato que IA consegue consumir sem transformar contexto em chute.
-
-## Ordem recomendada
-
-1. `sema resumo <arquivo-ou-pasta> --micro --para onboarding`
-2. Liste ou leia os contratos existentes e inspecione o `.sema` mais próximo.
-3. Crie, edite ou remova o contrato aplicavel antes de qualquer ação.
-4. `sema validar <arquivo.sema> --json`
-5. `sema drift <arquivo-ou-pasta> --json`
-6. `sema contexto-ia <arquivo.sema> --saida <diretorio> --json`
-
-Não comece cavando código bruto quando a ferramenta já consegue te dar contrato, score, lacuna e superficie viva. Contrato primeiro vale para Software, Author, Workflow, Ops, Game, Legal, Research e qualquer profile futuro.
-
-## Por capacidade do modelo
-
-IA pequena:
-
-- `sema resumo --micro`
-- `briefing.min.json`
-- `prompt-curto.txt`
-
-IA média:
-
-- `sema resumo --curto`
-- `drift.json`
-- `briefing.min.json`
-
-IA grande:
-
-- `sema contexto-ia`
-- `briefing.json`
-- `ir.json`
-- `ast.json`
-
-## MCP
-
-Se o agente usa MCP, configure o endpoint remoto privado fornecido pelo operador do serviço. O MCP não é mais distribuido como pacote npm público neste GitHub. A variavel `SEMA_MCP_AUTH_TOKEN` no cliente deve conter uma chave comercial `sema_mcp_*` do painel, nao um token fixo do servidor.
-
-Exemplo para clientes que aceitam MCP HTTP:
-
-```toml
-[mcp_servers.sema]
-url = "https://sema.exemplo.com/mcp"
-bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
-tool_timeout_sec = 90
-```
-
-Ferramentas mais úteis no fluxo de mudanca:
-
-- `sema_resumo` para descobrir o estado do projeto
-- `sema_listar_contratos` e `sema_ler_contrato` quando a versão privada expuser a leitura direta dos contratos
-- `sema_inspecionar` para entender o contrato mais próximo
-- `sema_validar` para bloquear contrato inválido antes da ação
-- `sema_drift` para medir coerência viva
-- `sema_impacto` para dizer o que tocar
-- `sema_renomear_semantico` para guiar troca de nomes sem misturar payload antigo e novo
-- `sema_profile_validar` ou os gates Author para validar o profile especifico
-- `sema_docs_impacto` para obrigar leitura das docs relacionadas antes de agir
-- `sema_finalizar_mudanca` para bloquear conclusóo sem leitura documental comprovada
-
-O MCP deve repetir a regra sem ambiguidade: se não ha contrato, crie; se a intenção mudou, edite; se a capacidade saiu do sistema, remova ou aposente. Ação sem ciclo de contrato não é fluxo Sema.
-
-## Portao documental
-
-Depois de resolver e validar o contrato, declare a intenção documental:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Leia todos os itens em `leituraObrigatoria`. Se `docsAusentes` vier preenchido, crie ou complete os documentos antes da ação.
-
-Antes de concluir:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Se houver diagnóstico de severidade 4+, a IA não deve finalizar a mudanca.
-
-## Regras praticas
-
-- trate `.sema` e IR como fonte de verdade semântica
-- trate humanos como donos/aprovadores e agentes como consumidores primarios do contrato
-- trate `drift` como juiz da adoção incremental
-- use `briefing.min.json` antes de abrir dezenas de arquivos
-- não invente sintaxe fora da gramática oficial
-- em task sensível, teste que valida apenas `sucesso` e fraco; inclua output, erro esperado ou garantia observavel
-- em persistência, não assuma que bancos diferentes tem o mesmo contrato operacional
-
-## Arquivos úteis no repo
-
-- `AGENTS.md`
-- `llms.txt`
-- `llms-full.txt`
-- `SEMA_BRIEF.md`
-- `SEMA_INDEX.json`
-- `docs/persistencia-vendor-first.md`
-- `docs/mcp.md`
-- `docs/documentacao.md`