@semacode/cli 1.5.11 → 1.5.16

package/docs/cli.md

@@ -1,110 +0,0 @@
-# CLI da Sema
-
-## Papel da CLI
-
-A CLI e 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
-- preparar contexto IA-first
-- resolver docs obrigatorias por intencao antes de editar ou operar
-- verificar multiplos alvos de geracao
-
-## Tres modos de operacao
-
-Projeto novo:
-
-- `sema iniciar`
-- `sema validar`
-- `sema compilar`
-- `sema verificar`
-
-Projeto ja semantizado:
-
-- `sema inspecionar`
-- `sema resumo`
-- `sema drift`
-- `sema contexto-ia`
-
-Adocao incremental:
-
-- `sema importar`
-- `sema formatar`
-- `sema validar`
-- `sema drift`
-
-## Persistencia 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.
-
-Cobertura publica:
-
-- `postgres`: `table`, `relationship`, `query`, `schema`, capacidades relacionais
-- `mysql`: `table`, `index`, consultas SQL e diferencas 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
-
-## Drift e codigo 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
-- 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.
-
-## Ajuda IA-first
-
-- `sema ajuda-ia`
-- `sema starter-ia`
-- `sema resumo <arquivo-ou-pasta> --micro|--curto|--medio`
-- `sema prompt-curto <arquivo-ou-pasta> --micro|--curto|--medio`
-- `sema contexto-ia <arquivo.sema> --saida <diretorio>`
-- `sema sync-ai-entrypoints --json`
-- `sema docs-impacto --intencao <acao> --criar-ausentes --json`
-- `sema finalizar-mudanca --intencao <acao> --doc-lida <caminho> --json`
-
-## Importadores publicos
-
-- `nestjs`
-- `fastapi`
-- `flask`
-- `nextjs`
-- `nextjs-consumer`
-- `react-vite-consumer`
-- `angular-consumer`
-- `flutter-consumer`
-- `firebase`
-- `php`
-- `dotnet`
-- `java`
-- `go`
-- `rust`
-- `cpp`
-- `typescript`
-- `python`
-- `dart`
-- `lua`
-
-## Comandos mais usados
-
-```bash
-sema validar <arquivo-ou-pasta> --json
-sema diagnosticos <arquivo.sema> --json
-sema ir <arquivo.sema> --json
-sema drift <arquivo-ou-pasta> --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>
-```

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

@@ -1,149 +0,0 @@
-# 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.
-
-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`.
-
-## Principio central
-
-Uma IA entende uma linguagem nova quando recebe quatro camadas de contexto:
-
-1. sintaxe
-2. semantica
-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.
-
-Antes de qualquer outra coisa, a IA tambem 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 existe para explicitar, alinhar e verificar contrato contra sistema vivo
-- curadoria humana continua parte da proposta
-
-Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar feito um animal apressado.
-
-## Camada 1. Sintaxe
-
-A IA precisa saber como a linguagem e escrita.
-
-Fontes principais:
-
-- [README.md](../README.md)
-- [sintaxe.md](./sintaxe.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
-
-Objetivo dessa camada:
-
-- reconhecer blocos validos
-- entender delimitadores
-- nao inventar palavras-chave
-- respeitar a organizacao canonicamente formatada
-
-## Camada 2. Semantica
-
-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)
-- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
-
-Objetivo dessa camada:
-
-- distinguir contrato interno de `task`
-- distinguir contrato publico de `route`
-- entender `effects`, `guarantees`, `error`, `state` e `flow`
-- operar na linguagem como especificacao executavel, nao como texto decorativo
-- entender que `importar` e bootstrap
-- entender que `drift` e regua de coerencia contra o runtime
-- entender que `impl` e ponte rastreavel para simbolo vivo
-
-## Camada 3. Estrutura intermediaria estavel
-
-Essa e a camada que faz a parada parar de ser um cassino.
-
-Em vez de confiar que a IA vai interpretar `.sema` cru de primeira, use a CLI como tradutora oficial da linguagem.
-
-Comandos principais:
-
-```bash
-sema resumo arquivo.sema --micro --para onboarding
-sema validar arquivo.sema --json
-sema diagnosticos arquivo.sema --json
-sema ast arquivo.sema --json
-sema ir arquivo.sema --json
-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
-- `diagnosticos --json`: devolve erros e avisos como contrato estruturado
-- `ast --json`: mostra a forma sintatica escrita
-- `ir --json`: mostra a forma semantica 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`.
-
-## Camada 4. Exemplos reais
-
-Modelo aprende muito por padrao. Por isso, bons exemplos valem quase tanto quanto especificacao.
-
-Arquivos recomendados:
-
-- [pagamento.sema](../exemplos/pagamento.sema)
-- [pagamento_dominio.sema](../exemplos/pagamento_dominio.sema)
-- [automacao.sema](../exemplos/automacao.sema)
-- [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 que a IA nao deve fazer
-
-- inventar palavras-chave fora da gramatica
-- 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
-- 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
-- rodar o formatador antes de considerar o trabalho pronto
-- validar e verificar a mudanca no mesmo fluxo
-
-## Estrategia recomendada
-
-Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
-
-1. [README.md](../README.md)
-2. [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
-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
-
-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.
-
-Ela entende bem quando recebe:
-
-- especificacao
-- exemplos
-- JSON estrutural
-- feedback automatico
-
-Sem isso, ate o modelo mais caro vira estagiario emocionado.

package/docs/deploy.md

@@ -1,70 +0,0 @@
-# Deploy
-
-Este runbook governa a publicacao publica da Sema: CLI, MCP, VSIX, instaladores e release assets.
-
-## Pre-condicoes
-
-- `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/`.
-
-## Sequencia segura
-
-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.
-
-## Validacao minima
-
-```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
-sema validar contratos/sema/governanca_ia.sema --json
-sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
-```
-
-Depois de publicar:
-
-```bash
-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
-```
-
-## Release assets
-
-`npm run release:preparar-publica` deve gerar:
-
-- `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`
-
-## Sinais de parada
-
-- 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.

package/docs/documentacao.md

@@ -1,63 +0,0 @@
-# Governanca de Documentacao
-
-A Sema trata documentacao como parte da mudanca, nao como pos-escrito simpatico para alguem lembrar depois.
-
-## Regra principal
-
-Toda IA deve resolver documentacao obrigatoria antes de editar contrato, codigo, configuracao ou executar operacoes como deploy.
-
-```bash
-sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
-```
-
-Se o comando apontar docs ausentes, crie ou preencha essas docs antes da acao. Para criar runbooks base:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-## Leitura obrigatoria
-
-O resultado de `docs-impacto` traz:
-
-- `leituraObrigatoria`: docs, readmes e contratos que devem ser lidos.
-- `docsAusentes`: docs que bloqueiam a acao.
-- `docsCriadas`: docs criadas automaticamente quando autorizado.
-- `bloqueios`: diagnosticos de severidade 4.
-
-O conteudo dos documentos existentes vem na resposta para que o agente realmente leia o material antes de agir.
-
-## Finalizacao
-
-Antes de responder que terminou, a IA deve chamar:
-
-```bash
-sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/api.md --json
-```
-
-Se faltar leitura ou documentacao, a conclusao deve ser bloqueada.
-
-## Docs que podem nascer automaticamente
-
-O Sema cria runbooks base para categorias operacionais:
-
-- `docs/deploy.md`
-- `docs/env.md`
-- `docs/rollback.md`
-- `docs/api.md`
-- `docs/auth.md`
-- `docs/seguranca.md`
-- `docs/database.md`
-- `docs/frontend.md`
-- `docs/testes.md`
-- `docs/mcp.md`
-- `docs/documentacao.md`
-- `docs/extensao-vscode.md`
-
-Esses arquivos sao esqueletos seguros. Eles devem ser completados com detalhes reais do projeto quando a operacao exigir.
-
-## O que nao fazer
-
-- Nao concluir uma mudanca sem rodar o portao documental.
-- Nao usar doc criada automaticamente como evidencia final se ela ainda esta generica.
-- Nao editar codigo sem contrato e sem leitura das docs relacionadas.

package/docs/env.md

@@ -1,56 +0,0 @@
-# Env
-
-Ambiente necessario 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
-
-- `SEMA_REPO`: repositorio GitHub usado para baixar assets. Padrao: `gerlanss/Sema`.
-- `SEMA_NPM_PACKAGE`: pacote da CLI. Padrao: `@semacode/cli`.
-- `SEMA_MCP_NPM_PACKAGE`: pacote do MCP. Padrao: `@semacode/mcp`.
-- `SEMA_VERSION`: versao usada pelo `install-sema.sh`. Padrao: `latest`.
-
-No PowerShell, o instalador recebe a versao por parametro:
-
-```powershell
-.\install-sema.ps1 -Version 1.5.10 -WithVSCode -WithMcp
-```
-
-No shell:
-
-```bash
-SEMA_VERSION=1.5.10 ./install-sema.sh --with-vscode --with-mcp
-```
-
-## 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
-
-Os pacotes publicos sao:
-
-- `@semacode/cli`
-- `@semacode/mcp`
-
-Antes de publicar, confira:
-
-```bash
-npm view @semacode/cli version
-npm view @semacode/mcp version
-```
-
-## GitHub Release
-
-O tag publico deve seguir `v<versao>`, por exemplo `v1.5.10`.
-
-Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositorio.

package/docs/extensao-vscode.md

@@ -1,45 +0,0 @@
-# Extensao VS Code
-
-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: Sincronizar EntryPoints IA do Projeto`.
-5. Abra um `.sema` e confirme diagnosticos, highlight e formatação.
-
-## Cuidados
-
-- O `extension.js` deve apontar o LSP para `server.js`.
-- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP quando novos comandos forem adicionados.
-- A versao da extensao deve bater com a versao publica preparada por `release:preparar-publica`.

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

@@ -1,177 +0,0 @@
-# Fluxo Pratico para IA Antes de Editar `.sema`
-
-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 nao seguir, vira adivinhacao gourmet.
-
-## Fluxo curto
-
-1. ler contexto do projeto
-2. identificar a capacidade da IA
-3. identificar o modulo alvo
-4. consultar o menor artefato semantico suficiente
-5. editar
-6. formatar
-7. validar
-8. verificar
-
-## Fluxo detalhado
-
-### Etapa 1. Ler contexto minimo
-
-Antes de tocar em qualquer arquivo, a IA deve ler:
-
-- [README.md](../README.md)
-- [integracao-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 tambem:
-
-- [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 media: `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 modulo alvo e um exemplo parecido
-
-A IA deve identificar:
-
-- qual arquivo sera editado
-- qual modulo 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 publica 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 semantica resolvida quando a capacidade aguentar
-- evitar interpretar errado o contrato
-
-### Etapa 5. Editar o `.sema`
-
-Ao editar, a IA deve:
-
-- preservar a intencao do modulo
-- seguir a gramatica existente
-- evitar criar bloco ou operador nao suportado
-- preferir a forma ja usada nos exemplos oficiais
-
-### Etapa 6. Formatar
-
-Depois da edicao:
-
-```bash
-sema formatar caminho/arquivo.sema
-sema formatar caminho/arquivo.sema --check
-```
-
-Se `--check` falhar, o trabalho ainda nao esta 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 diagnosticos estruturados como contrato de correcao
-- nao insistir em leitura manual teimosa quando a CLI ja disse onde esta a merda
-
-### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
-
-Se a tarefa nao for so editar contrato, mas tambem 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`, `dart` ou `lua`, conforme o caso.
-
-Regra pratica:
-
-- se a entrega inclui codigo derivado, `sema compilar` nao e opcional
-- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema ja gera sozinha, que e burrice operacional
-
-### Etapa 8. Verificar
-
-No fechamento:
-
-```bash
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-## Fluxo minimo 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 codigo derivado, o fluxo minimo 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 saida
-
-Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
-
-- eu entendi o modulo e o contrato?
-- eu mantive a sintaxe dentro do que a linguagem suporta?
-- eu formatei o arquivo?
-- eu validei?
-- eu olhei diagnosticos se algo falhou?
-- eu fechei com verificacao?
-
-Se alguma resposta for "nao", ainda nao terminou.
-
-## Regra de ouro
-
-Em Sema, a IA nao deveria operar no escuro.
-
-Ela deve trabalhar sempre com:
-
-- exemplo oficial
-- AST
-- IR
-- diagnosticos
-- formatador
-
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so no discurso bonito.
-
-## Observacao sobre caminhos
-
-Esta documentacao usa placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.