@semacode/cli 1.5.48 → 1.5.52

package/dist/initTemplatesBase.js

@@ -79,16 +79,16 @@ Antes de alterar codigo, contrato ou documentacao:
 3. rode \`sema preflight resumo --json\`;
 4. rode \`sema resumo\`;
 5. rode \`sema docs-impacto --intencao "<acao>" --json\`;
-6. leia \`docs/comandos.md\` antes de escolher comando ou interpretar \`--saida\`;
-7. use \`exemplos/\` e \`docs/sintaxe.md\` antes de criar ou corrigir \`.sema\`.
+6. leia \`docs/commands.md\` antes de escolher comando ou interpretar \`--saida\`;
+7. use \`exemplos/\` e \`docs/syntax.md\` antes de criar ou corrigir \`.sema\`.
 
 ## Estrutura criada
 
 - \`contratos/\`: contratos semanticamente governados.
 - \`exemplos/\`: exemplos oficiais da DSL Sema.
-- \`docs/comandos.md\`: catalogo de comandos, gates e regra de \`--saida\`.
-- \`docs/sintaxe.md\`: referencia curta para escrever \`.sema\`.
-- \`docs/fluxo-pratico-ia-sema.md\`: fluxo minimo para agentes.
+- \`docs/commands.md\`: catalogo de comandos, gates e regra de \`--saida\`.
+- \`docs/syntax.md\`: referencia curta para escrever \`.sema\`.
+- \`docs/ai-workflow.md\`: fluxo minimo para agentes.
 - \`SEMA_BOOT.md\`, \`SEMA_SMALL_MODEL.md\`, \`AGENT_CONTEXT_PACK.json\` e \`SEMA_INDEX.json\`: contexto IA-first.
 
 ## Geracao

package/dist/sync/index.js

@@ -63,7 +63,7 @@ generator client {
 
 datasource db {
   provider = "${datasourceProvider}"
-  url      = env("DATABASE_URL")
+  url      = env("SEMA_PRISMA_URL")
 }
 ${models}`;
     // Salvar

package/docs/README.md

@@ -0,0 +1,19 @@
+# Sema Documentation
+
+These docs describe the public local CLI distribution of Sema.
+
+Sema is local-first: agents run the CLI inside a project folder, read `.sema`
+contracts, check drift, map impact, and close changes with documentation
+evidence. Public docs are written in English.
+
+Start here:
+
+- [CLI](./cli.md)
+- [Commands](./commands.md)
+- [Syntax](./syntax.md)
+- [Profiles](./profiles.md)
+- [Documentation Governance](./documentation.md)
+- [Repository Boundary](./repositories.md)
+- [Security](./security.md)
+
+Official support: [suporte@otimitare.online](mailto:suporte@otimitare.online)

package/docs/ai-integration.md

@@ -0,0 +1,90 @@
+# AI Integration
+
+Sema is designed for AI agents with different context sizes and discipline
+levels. The public repository documents the local CLI flow only: agents run the
+CLI inside the project, read contracts, check drift, map impact, and close the
+change with evidence.
+
+Supported capacity labels: fraca, pequena, media, forte, grande.
+
+## Local-Only Rule
+
+For a local workspace, use the local CLI:
+
+```bash
+sema --version
+sema preflight resumo --json
+sema resumo
+```
+
+Continue only when preflight returns `use_cli_local`. Do not replace the local
+CLI with an external workspace source, external sync, or project-name guessing.
+
+## Before Editing
+
+```bash
+sema docs-impacto --intencao "describe the change" --json
+sema inspecionar contratos/example.sema --json
+sema drift contratos/example.sema --escopo modulo --json
+sema impacto contratos/example.sema --alvo app.example --mudanca "describe the change" --json
+```
+
+Read every document listed by `docs-impacto` before changing code, contracts,
+operational docs, generated artifacts, workflows, profiles, or release material.
+
+## Capacity Tiers
+
+Weak agents should start with `SEMA_BOOT.md`,
+`SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt`,
+`AGENT_CONTEXT_PACK.json`, and `SEMA_INDEX.json`. They should stop early
+when a gate is unclear.
+
+Medium agents should start with `SEMA_BOOT.md`,
+`AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt`,
+`SEMA_INDEX.json`, and `AGENTS.md`. They must run docs-impact, drift, and
+impact before edits.
+
+Strong agents may consume `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.md`,
+`SEMA_INDEX.json`, AST, IR, drift, and impact outputs, but larger context does
+not remove the contract-first rule.
+
+## Governed Code
+
+Generated or governed code should keep a short `SEMA-GOVERNED` marker that
+points back to the applicable contract. The marker is not a substitute for
+validation, drift, impact, or finalization gates.
+
+Governed code above 1000 lines requires a
+split plan. Governed code above 2000
+lines blocks closure. Markdown documentation is not counted as governed code
+size, but it is still governed by documentation and publication checks.
+
+## Contract Size
+
+`.sema` contracts above 300 lines require a
+split plan. Above 500 lines, do not keep
+editing the same contract before splitting it by real domain or capability.
+Never create artificial `parte_1` or `parte_2` files to hide a large contract.
+
+## Payload Size
+
+Inline payloads in `arquivos_codigo.conteudo` or `conteudo` are limited to
+262144 characters. That is a transport/input limit,
+not an operational timeout. Split by responsibility or use an authorized file
+path/attachment strategy instead of increasing timeouts to push the same payload.
+
+## UI And Terminal Work
+
+When the task involves a site, app, dashboard, form, game, CLI, TUI, or any
+user-facing experience, closure requires evidence:
+
+- desktop and mobile validation for UI work;
+- no horizontal overflow on narrow mobile viewports such as 390px;
+- clear loading, empty, success, and error states when relevant;
+- structured terminal output, clear errors, help, and smoke checks for CLI/TUI
+  work.
+
+## Platform Policy
+
+Sema governs contract, scope, drift, evidence, and quality. It does not bypass
+platform policies, terms of use, permissions, security controls, or laws.

package/docs/ai-onboarding.md

@@ -0,0 +1,33 @@
+# Teaching Sema To AI Agents
+
+Give agents a short rule: contracts come first, and the local CLI is the source
+of truth.
+
+## Minimal Prompt
+
+```text
+This workspace is governed by Sema. Before editing code, contracts, docs,
+workflows, profiles, or release scripts, run:
+
+1. sema --version
+2. sema preflight resumo --json
+3. sema resumo
+4. sema docs-impacto --intencao "<change>" --json
+5. sema inspecionar on the applicable .sema contract
+6. sema drift before editing existing code
+7. sema impacto before changing behavior
+8. sema finalizar-mudanca before closing
+
+If the CLI is unavailable or preflight does not return use_cli_local, stop.
+Do not replace Sema with manual search or guessed contracts.
+```
+
+## What Agents Should Not Do
+
+- Do not invent `.sema` contracts.
+- Do not implement code without an applicable contract.
+- Do not ignore severity 4+ warnings.
+- Do not publish private or sensitive operational material.
+- Do not replace the local CLI when the local workspace is available.
+
+Support: suporte@otimitare.online

package/docs/ai-workflow.md

@@ -0,0 +1,62 @@
+<!-- sema:agent-entrypoint:start -->
+# Practical AI + Sema Workflow
+
+This is the minimum workflow for agents in a local workspace.
+
+1. Leia `SEMA_BOOT.md`.
+2. Rode `sema --version`.
+3. Rode `sema preflight resumo --json` e continue apenas se retornar `use_cli_local`.
+4. Rode `sema resumo`.
+5. Rode `sema docs-impacto --intencao "<acao>" --json`.
+6. Leia a documentacao obrigatoria retornada.
+7. Antes de escolher comando ou interpretar `--saida`, leia `docs/commands.md`.
+8. Antes de criar ou editar contrato, use `exemplos/` e `docs/syntax.md`.
+9. Antes de editar codigo existente, rode `sema drift` e `sema impacto`.
+10. Depois de alterar `.sema`, rode `sema formatar` e `sema validar`.
+11. Antes de concluir, rode `sema finalizar-mudanca` com as docs lidas.
+
+Contract edit rule: `.sema` has its own size budget. Above 300 lines, plan a split by domain/capability; above 500, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through `vinculos`.
+
+Closing rule: `sema drift --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or broken impls, the task is still blocked. Passing unit tests do not replace green drift.
+
+UI rule: if the task involves an interface, minimum evidence includes desktop and mobile. On a narrow viewport such as 390px, `document.documentElement.scrollWidth <= document.documentElement.clientWidth` must pass; horizontal scroll blocks closure.
+
+## Agent Capacity
+
+- Weak agent: `SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`.
+- Medium agent: `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt`, `SEMA_INDEX.json`, `AGENTS.md`.
+- Strong agent: `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.md`, `SEMA_INDEX.json`, AST, IR, drift, and impact.
+
+## When to Generate Code
+
+If the delivery includes code derived from a contract, run `sema compilar`.
+
+```bash
+sema compilar contratos/orders.sema --alvo javascript --saida ./generated/javascript
+```
+
+Replace `javascript` with `typescript`, `python`, `dart`, `lua`, `html`, or `css` when appropriate.
+
+## Fail Closed
+
+- Se não conseguir chamar Sema, pare e declare bloqueio em vez de editar código ou contrato.
+- Se não houver contrato aplicável ou vínculo semântico do arquivo, inspecione o arquivo, descubra ou crie o .sema aplicável e vincule antes do código.
+- Em IDE local, rode sema --version; se falhar, pare. A IA não acessa o painel Sema: peça ao humano para instalar a CLI pelo painel. Depois rode sema preflight <comando> --json; só continue com use_cli_local; não use fonte externa de workspace para substituir a CLI local.
+- Se não houver workspace local em disco, pare bloqueado e peça o fluxo apropriado; não invente caminho nem substitua a CLI local por ferramenta paralela.
+- Se arquivos_codigo.conteudo ou conteudo inline passar de 262144 caracteres, não aumente timeout para forçar: divida por responsabilidade ou use anexo/caminho de servidor autorizado.
+- Se for criar ou corrigir .sema, use sema_exemplos antes de escrever sintaxe.
+- Se a resposta humana estiver em PT-BR, use vocabulário Sema canônico e preserve acentos mesmo que a DSL use ASCII.
+- Se um arquivo de código tiver SEMA-GOVERNED, consulte Sema e o contrato aplicável antes de editar.
+- Se codigo governado passar de 1000 linhas, planeje divisao; se passar de 2000, pare e divida antes de concluir. Documentacao Markdown nao entra nesse limite de codigo.
+- Se contrato .sema passar de 300 linhas, planeje split por dominio/capacidade; acima de 500, criacao e edicao ficam bloqueadas. Nao use parte_1/parte_2 e nao remova guarantees, tests ou vinculos so para caber.
+- Um mesmo arquivo de codigo pode ser governado por varios contratos .sema via vinculos; Sema Codigo deve preservar essa rastreabilidade.
+- Se score, achados ou decisaoAgente parecerem bons, trate como sinal de triagem e confira evidência concreta no contrato e no código.
+- Se validar artefato inline com 100/100, ainda preserve cabeçalho SEMA-GOVERNED no arquivo físico sincronizado.
+- Se `sema drift` retornar sucesso:false, `vinculos_quebrados`, `rotas_divergentes` ou impls quebradas, a mudanca nao pode ser declarada concluida; corrija contrato/codigo e rode drift de novo.
+- Se a tarefa tiver site, sistema, app, UI, painel, jogo, CLI/TUI ou terminal, nao conclua sem acabamento moderno, contextual e evidenciado; em UI mobile estreita (ex. 390px), `document.documentElement.scrollWidth <= document.documentElement.clientWidth` precisa ser verdadeiro.
+- Se texto visivel PT-BR perder acento ou cedilha em termos como descricao, lancamentos, saude ou alimentacao, trate como defeito bloqueante quando houver i18n/idioma declarado.
+- Se aparecer caminho que não pertence ao workspace local aberto pelo usuário, pare e confirme a fonte antes de agir.
+- Se uma chamada Sema estourar por timeout local, aumente o timeout e tente de novo; timeout do agente não libera ação sem Sema.
+- Se a plataforma bloquear ou alertar política, trate como bloqueio externo ou falso positivo possível; explique sem tentar contornar filtro.
+- Se a tarefa tiver experiência de uso e você não conseguir garantir padrão moderno, contextual e não genérico, pare e peça revisão em vez de entregar coisa engessada.
+<!-- sema:agent-entrypoint:end -->

package/docs/auth.md

@@ -0,0 +1,16 @@
+# Authentication Boundary
+
+The public Sema CLI does not require authentication.
+
+Use local commands:
+
+```bash
+sema --version
+sema preflight resumo --json
+sema validar contratos/example.sema --json
+```
+
+Do not put private or sensitive operational material in this repository.
+
+Application-specific authentication belongs in the application repository that
+owns it.

package/docs/cli.md

@@ -1,118 +1,59 @@
 # Sema CLI
 
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois.
-> ES: Español al final.
+Sema is now a local CLI distribution. The public package reads the workspace on
+the user's machine, validates `.sema` contracts, checks drift, maps impact, and
+generates code without requiring external service credentials.
 
-## English
+Support: suporte@otimitare.online
 
-The Sema CLI is installed from the `@semacode/cli` npm package. In local IDEs it is the complete Sema runtime: it reads the workspace, runs gates, validates contracts, checks drift/impact, and consults the SEMAS control plane before operating.
-
-Use it for local-agent work:
-
-- run `sema preflight <command> --json` before action;
-- 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;
-- generate derived artifacts for TypeScript, Python, Dart, Lua, JavaScript, HTML, and CSS;
-- initialize a new project with `AGENTS.md`, `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`, `docs/sintaxe.md`, `docs/fluxo-pratico-ia-sema.md`, and `exemplos/`;
-- execute local or VPS-side project actions.
-
-The key installer from the site installs Node/npm when missing, installs the CLI, and saves `SEMA_CLI_AUTH_TOKEN`, `SEMA_CLI_CONTROL_PLANE_URL`, and compatibility MCP env vars. In a local IDE, the agent must first run `sema --version`. If it fails, the agent stops and asks the human to open the Sema panel and run the key installer. If `preflight` returns anything other than `decisao=use_cli_local`, stop. Do not call remote MCP, `sema_sync`, `sema_contratos_sincronizar`, or `sema mcp-client` just to read a local workspace.
-
-Remote MCP remains the web/chat surface for ChatGPT, Lovable, GPTs, and similar clients without local workspace access. It uses the same commercial control plane and SEMAS account.
-`sema runner servidor` may run without token only on `localhost`, `127.0.0.1` or `::1`. Any public bind such as `0.0.0.0` requires `--token` or `SEMA_RUNNER_TOKEN`.
+## Install
 
 ```bash
 npm install -g @semacode/cli
-```
-
-```bash
 sema --version
-sema preflight resumo --json
-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 `@semacode/cli`. Em IDE local, ela é o runtime completo da Sema: lê o workspace, roda gates, valida contratos, mede drift/impacto e consulta o control plane de SEMAS antes de operar.
-
-Use a CLI para trabalho de agente local:
-
-- rodar `sema preflight <comando> --json` antes de agir;
-- 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;
-- gerar artefatos derivados para TypeScript, Python, Dart, Lua, JavaScript, HTML e CSS;
-- iniciar projeto novo com `AGENTS.md`, `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`, `docs/sintaxe.md`, `docs/fluxo-pratico-ia-sema.md` e `exemplos/`;
-- executar ações locais ou na VPS.
-
-O instalador do site instala Node/npm quando faltar, instala a CLI e grava `SEMA_CLI_AUTH_TOKEN`, `SEMA_CLI_CONTROL_PLANE_URL` e variáveis MCP de compatibilidade. Se o `preflight` retornar qualquer coisa diferente de `decisao=use_cli_local`, pare. Não chame MCP remoto, `sema_sync`, `sema_contratos_sincronizar` nem `sema mcp-client` só para ler workspace local.
-Em IDE local, o agente deve rodar `sema --version` primeiro. Se falhar, ele para. A IA não acessa o painel Sema: ela pede ao humano para abrir o painel e rodar o instalador de chave.
-
-O MCP remoto continua sendo a superfície web/chat para ChatGPT, Lovable, GPTs e clientes parecidos sem acesso ao workspace local. Ele usa o mesmo control plane comercial e a mesma conta de SEMAS.
-`sema runner servidor` so pode rodar sem token em `localhost`, `127.0.0.1` ou `::1`. Qualquer bind publico como `0.0.0.0` exige `--token` ou `SEMA_RUNNER_TOKEN`.
+For development inside this repository:
 
 ```bash
-npm install -g @semacode/cli
+npm install
+npm run build
+node pacotes/cli/dist/index.js --help
 ```
 
+## Required Local Flow
+
+Agents and humans should use the same local sequence before changing governed
+code, contracts, workflows, release scripts, or operational docs:
+
 ```bash
 sema --version
 sema preflight resumo --json
-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
+sema resumo
+sema docs-impacto --intencao "describe the change" --json
+sema inspecionar contratos/example.sema --json
+sema drift contratos/example.sema --escopo modulo --json
+sema impacto contratos/example.sema --alvo sema.example.target --mudanca "describe the change" --json
 ```
 
-## Español
-
-La CLI de Sema se instala desde el paquete npm `@semacode/cli`. En una IDE local es el runtime completo de Sema: lee el workspace, ejecuta gates, valida contratos, mide drift/impacto y consulta el control plane de SEMAS antes de operar.
+Continue only when `preflight` returns `decisao: "use_cli_local"`. The public
+CLI preflight is an offline local gate; it does not check credits, install
+keys, or call an external control surface.
 
-Usa la CLI para trabajo de agente local:
+## Core Commands
 
-- ejecutar `sema preflight <comando> --json` antes de actuar;
-- 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;
-- generar artefactos derivados para TypeScript, Python, Dart, Lua, JavaScript, HTML y CSS;
-- iniciar un proyecto nuevo con `AGENTS.md`, `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`, `docs/sintaxe.md`, `docs/fluxo-pratico-ia-sema.md` y `exemplos/`;
-- ejecutar acciones locales o en la VPS.
+- `sema iniciar`: create a governed starting point.
+- `sema validar`: validate `.sema` contracts.
+- `sema inspecionar`: inspect the applicable contract surface.
+- `sema drift`: compare contracts and implementation.
+- `sema impacto`: map the blast radius of a planned change.
+- `sema docs-impacto`: identify docs that must be read or updated.
+- `sema finalizar-mudanca`: close the governed change with evidence.
+- `sema compilar`: generate code from contracts.
+- `sema verificar`: run the final local verification bundle.
+- `sema contexto-ia`: build local AI context from a contract.
 
-El instalador del sitio instala Node/npm cuando falten, instala la CLI y guarda `SEMA_CLI_AUTH_TOKEN`, `SEMA_CLI_CONTROL_PLANE_URL` y variables MCP de compatibilidad. En una IDE local, el agente debe ejecutar primero `sema --version`. Si falla, para y pide al humano que abra el panel Sema y ejecute el instalador de clave. Si `preflight` devuelve algo distinto de `decisao=use_cli_local`, para. No llames el MCP remoto, `sema_sync`, `sema_contratos_sincronizar` ni `sema mcp-client` solo para leer un workspace local.
+## Public Boundary
 
-El MCP remoto sigue siendo la superficie web/chat para ChatGPT, Lovable, GPTs y clientes similares sin acceso al workspace local. Usa el mismo control plane comercial y la misma cuenta de SEMAS.
-`sema runner servidor` solo puede correr sin token en `localhost`, `127.0.0.1` o `::1`. Cualquier bind publico como `0.0.0.0` exige `--token` o `SEMA_RUNNER_TOKEN`.
-
-```bash
-npm install -g @semacode/cli
-```
-
-```bash
-sema --version
-sema preflight resumo --json
-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
-```
+Do not publish private or sensitive operational material in public Sema
+artifacts.

package/docs/commands.md

@@ -0,0 +1,90 @@
+<!-- sema:agent-entrypoint:start -->
+# Sema Command Catalog
+
+Use this file when an AI agent does not know which command to run. A Sema command is an operational gate; do not replace it with a Markdown report.
+
+## Minimum Local Flow
+
+```bash
+sema --version
+sema preflight resumo --json
+sema resumo
+sema docs-impacto --intencao "<acao>" --json
+```
+
+Then read every required doc returned by `docs-impacto`.
+
+## Contract and Discovery
+
+- `sema iniciar --template <template>`: creates a new Sema project with a contract, docs, examples, and AI kit.
+- `sema validar <arquivo-ou-pasta> --json`: validates `.sema` contracts.
+- `sema diagnosticos <arquivo.sema> --json`: details errors and warnings.
+- `sema formatar <arquivo-ou-pasta>`: formats contracts.
+- `sema inspecionar <arquivo-ou-pasta> --json`: shows modules, tasks, routes, entities, links, and expected files.
+- `sema ast <arquivo.sema> --json`: shows AST for syntax debugging.
+- `sema ir <arquivo.sema> --json`: shows the IR used by gates and generators.
+
+## Change and Closure
+
+- `sema docs-impacto --intencao "<acao>" --json`: discovers required docs and documentary blockers.
+- `sema drift <arquivo-ou-pasta> --escopo modulo --json`: compares contract and implementation.
+- `sema impacto <arquivo-ou-pasta> --alvo <token> --mudanca "<descricao>" --json`: maps impact before changing behavior.
+- `sema verificar <arquivo-ou-pasta> --json`: runs aggregated final verification.
+- `sema finalizar-mudanca --intencao "<acao>" --doc-lida <arquivo> --json`: proves documentation reading before closure.
+
+Honest closure: treat drift JSON as the source of truth. `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or broken impls mean the change is not complete yet. Do not report "clean drift" without green JSON.
+
+## Sema Code
+
+- `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart|lua|javascript|html|css> --saida <diretorio>`: generates starter/support artifacts from the contract.
+- `sema testar <arquivo.sema> --alvo <alvo> --saida <diretorio-temporario>`: generates and runs local tests when the target supports it.
+- `sema importar <fonte> <diretorio> --saida <diretorio> --json`: imports a legacy project into initial contracts.
+- `sema renomear-semantico <arquivo-ou-pasta> --de <nome> --para <nome> --json`: helps rename symbols semantically.
+
+Rule for `--saida`: the folder passed to `sema compilar --saida` is generated output. It is not the final delivery by itself. The final delivery is the target files/links declared by the contract. If the contract asks for `index.html`, `css/styles.css`, and `js/app.js`, creating only `saida/expense_control.ts` does not complete the task.
+
+Sema Code traceability rule: generated artifacts must point back to the source module/contract and preserve that the same final file may be governed by several `.sema` contracts through `vinculos`. Do not force a 1:1 contract-file relationship and do not treat `saida/` as the final project.
+
+Ready UI rule: if the task generates an app, site, dashboard, form, or static HTML, run desktop/mobile visual validation when the surface allows it. On narrow mobile (for example 390px), `scrollWidth <= clientWidth` must pass; a layout that stacks but overflows horizontally is not responsive.
+
+## Canonical Syntax Lists
+
+- Origins for `use` and `impl`: `ts/typescript`, `js/javascript`, `py/python`, `dart`, `lua`, `cs/dotnet`, `java`, `go`, `rust`, `cpp`.
+- Frequent `effects` categories: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.
+- Accepted `audit.motivo` values: `obrigatorio`, `opcional`, `dispensado`.
+
+`sema compilar --alvo javascript` is a generation target. `impl { js: ... }` is the live-code origin. Do not swap one for the other.
+
+## AI and Context
+
+- `sema ajuda-ia`: short guidance for agents.
+- `sema starter-ia`: operational starter.
+- `sema contexto-ia <arquivo.sema> --saida <dir> --json`: AI context package.
+- `sema prompt-curto <arquivo-ou-pasta> --json`: compact prompt.
+- `sema sync-ai-entrypoints --json`: synchronizes AGENTS, boot, pack, and local docs.
+- `sema instalar-exemplos --json`: installs official examples in the workspace.
+- `sema exemplos-prompt-ia`: shows prompt examples, not `.sema` examples.
+
+## Profiles e Author
+
+- `sema author iniciar|validar|briefing|revisar-cliches|validar-narrativa|validar-proibicoes`: governs authorial writing.
+- `sema profile validar <software|workflow|ops|game|legal|research|redacao|propostas|conversas> <arquivo> --json`: validates an artifact by profile.
+- `sema profile capabilities --json`: lists profiles/capabilities.
+- `sema rule-packs --profile <profile> --json`: lists rule packs.
+
+## Operational
+
+- `sema doctor`: diagnoses local installation.
+
+## Forbidden
+
+- Do not use an external workspace source to inspect a local workspace when `sema --version` works.
+- Do not search the entire disk for `.sema` syntax; use `exemplos/`, `docs/syntax.md`, and this catalog.
+- Do not stop after `sema compilar` if the contract target files still do not exist.
+- Do not replace `sema compilar` with `sema testar` when Guard asks for Sema Code.
+- Do not create a Markdown report to pretend a gate ran.
+- Do not say drift passed when `sema drift --json` returned `sucesso:false`, broken link, divergent route, or broken impl.
+- Do not declare a UI responsive without mobile/desktop proof; horizontal scroll at 390px blocks closure.
+
+Governed code policy: Arquivos de codigo gerados ou governados pela Sema devem manter cabecalho curto com modulo de origem, contrato .sema aplicavel e descricao humana. Validacao inline prova apenas o payload enviado; o arquivo fisico ainda precisa de SEMA-GOVERNED para orientar a proxima IA. Codigo governado avisa acima de 1000 linhas e bloqueia acima de 2000. Contrato .sema avisa acima de 300 linhas e bloqueia criacao, edicao, drift, finalizacao, geracao e snapshot acima de 500. O split de .sema deve ser por dominio/capacidade, nunca parte_1/parte_2; varios contratos podem governar o mesmo arquivo de codigo via vinculos. Sema Codigo deve preservar essa rastreabilidade em cabecalhos e saidas geradas. Documentacao Markdown nao entra nesse limite de codigo; continua governada por docs-impacto, limite de bytes e verificacao de segredos. Payload inline acima de 262144 caracteres nao e caso de aumentar timeout: divida por responsabilidade ou use anexo/caminho de servidor autorizado.
+<!-- sema:agent-entrypoint:end -->

package/docs/database.md

@@ -0,0 +1,15 @@
+# Database Boundary
+
+The public Sema CLI does not require a database.
+
+Sema reads contracts and source files from the local workspace. Any database used
+by an application governed by Sema belongs to that application, not to the public
+Sema CLI distribution.
+
+## Public Rule
+
+Do not ship private database material, real credentials, operational schemas, or
+project-specific data in the public Sema package.
+
+Application-specific database docs should live in the application repository
+that owns the database.

package/docs/deploy.md

@@ -1,45 +1,13 @@
-# Deploy Privado
+# Deployment Boundary
 
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final.
+The public Sema repository only documents public local CLI release checks.
 
-## 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. For public/production MCP, `/healthz.hardening.authorized` must be `true`; otherwise fix env before exposing `/mcp`.
-
-## 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. Para MCP publico/production, `/healthz.hardening.authorized` deve ser `true`; se nao for, corrija o ambiente antes de expor `/mcp`.
-
-## 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:
+Public release work should focus on the local CLI package:
 
 ```bash
-npm run repo:verificar-privado
 npm run build
+npm run cli:empacotar-publica
+node scripts/testar-pacote-cli-publico.mjs
 ```
 
-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. Para MCP publico/production, `/healthz.hardening.authorized` debe ser `true`; si no, corrige el ambiente antes de exponer `/mcp`.
+Do not publish private or sensitive operational material in this repository.

package/docs/documentation.md

@@ -0,0 +1,39 @@
+# Documentation Governance
+
+Documentation is part of every governed change. An agent must use
+`sema docs-impacto` before editing contracts, code, operational docs, workflows,
+profiles, generated artifacts, or release material.
+
+Public Sema documentation is English and local-only.
+
+## Required Flow
+
+```bash
+sema docs-impacto --intencao "describe the change" --json
+```
+
+The result lists:
+
+- `leituraObrigatoria`: files that must be read before the change;
+- `docsAusentes`: missing docs that block the change;
+- `docsCriadas`: generated draft docs that must be completed by the agent;
+- `bloqueios`: blocking diagnostics.
+
+Before closing the change, prove the required docs were read:
+
+```bash
+sema finalizar-mudanca \
+  --intencao "describe the change" \
+  --doc-lida README.md \
+  --doc-lida docs/documentation.md \
+  --json
+```
+
+## Public Docs Rules
+
+- Write public docs in English.
+- Keep commands, file paths, package names, environment variable names, and DSL
+  keywords literal.
+- Do not include private or sensitive operational material.
+- Prefer local CLI examples.
+- Point support requests to suporte@otimitare.online.