@semacode/cli 1.5.27 → 1.5.29

package/docs/integracao-com-ia.md

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