@semacode/cli 1.5.47 → 1.5.52

package/docs/agentes-por-capacidade.md

@@ -1,126 +0,0 @@
-# Agentes por capacidade
-
-Sema deve funcionar em agentes fortes, médios e fracos. A diferença não é só tamanho de contexto; é disciplina operacional.
-
-## Políticas da Plataforma
-
-O Sema governa contrato, escopo, drift, evidência e qualidade do projeto. Ele não pede, não autoriza e não contorna políticas da plataforma, termos de uso, permissões, segurança ou leis.
-
-- Escopo: Contrato primeiro, documentação obrigatória, rastreabilidade, auditoria de drift, orçamento semântico, idioma humano, design quando houver UI e evidência de fechamento.
-- Se houver alerta externo: Se um cliente, modelo ou classificador bloquear a mensagem, trate como bloqueio externo ou falso positivo possível: explique de forma neutra, preserve a intenção legítima de governança e não tente burlar filtros.
-- Fraca: Se aparecer alerta de política, pare. Diga que Sema é governança de projeto, não bypass; peça reformulação segura ou contexto permitido.
-- Média: Separe bloqueio da plataforma de erro do Sema. Reformule em linguagem neutra quando permitido e mantenha os gates; não tente contornar filtro.
-- Forte: Registre evidência, reduza ambiguidade e continue apenas no escopo permitido pela plataforma. Governança Sema nunca substitui política externa.
-- Proibido: contornar_politica_da_plataforma, apresentar_sema_como_bypass_de_seguranca, insistir_em_conteudo_bloqueado, confundir_governanca_com_permissao_para_acao_proibida.
-
-## Código Governado
-
-Arquivos gerados ou governados pela Sema devem manter o marcador `SEMA-GOVERNED`.
-Orçamento semântico é regra: código ou contrato governado com 1000+ linhas exige plano de divisão; 2000+ linhas não pode concluir, gerar nem sincronizar. Markdown documental não entra nesse limite de código.
-Validação inline 100/100 não remove essa obrigação: ela comprova aquele payload, mas o arquivo físico ainda precisa avisar a próxima IA que existe contrato.
-
-- Fraca: Se abrir código com SEMA-GOVERNED, pare, leia SEMA_SMALL_MODEL.md e chame Sema antes de editar. Não crie código ou contrato governado acima de 2000 linhas nem envie payload inline acima de 262144 caracteres; divida antes por responsabilidade, nunca em partes p1/p2 sem sentido.
-- Média: Se abrir código com SEMA-GOVERNED, rode docs-impacto e drift antes de alterar comportamento. Trate 1000+ linhas em código ou contrato governado como refatoração provável; se o payload inline passar de 262144 caracteres, separe HTML, estilos, estado, renderização, cálculo e dados antes de sincronizar.
-- Forte: Se abrir código com SEMA-GOVERNED, pode inspecionar AST/IR e código completo, mas mantém contrato primeiro, drift, orçamento governado de 2000 linhas e finalizar-mudanca. Contexto grande não autoriza monólito nem payload inline acima de 262144 caracteres.
-
-## Payload e Transporte MCP
-
-Payload inline em `sema_sync`, `arquivos_codigo.conteudo` ou `conteudo` tem limite de 262144 caracteres. Esse limite é de transporte e validação de entrada; não é timeout operacional.
-
-- Fraca: se aparecer `too_big`, payload grande ou arquivo grande, pare e divida por responsabilidade antes de chamar Sema de novo. Não aumente timeout para tentar empurrar o mesmo payload.
-- Média: em HTML/app estático, modularize em `index.html`, `styles/*.css`, `js/state.js`, `js/render/*.js` e `data/*.json`, cada arquivo governado com cabeçalho quando aplicável.
-- Forte: escolha o transporte correto: inline só até o limite; acima disso use anexo, caminho de servidor autorizado, manifesto/índice ou arquivos lógicos separados. Diagnostique reset/timeout como transporte/performance, não como permissão para monólito.
-- Proibido: resolver limite de transporte com `index_p1.html`/`index_p2.html`, aumentar timeout para passar `too_big`, ou remover dados essenciais só para a validação inline caber.
-
-## Divisão por Responsabilidade
-
-Sema não manda quebrar HTML em pedaços artificiais. Ele manda manter arquivos pequenos, coesos e governáveis.
-
-- Fraca: se um arquivo crescer, pare e peça/execute divisão por responsabilidade antes de continuar.
-- Média: em projeto web, prefira `index.html`, `styles/*.css`, `js/state.js`, `js/calc.js`, `js/render/*.js` e `data/*.json`.
-- Forte: preserve arquitetura e experiência de uso, mas não use contexto grande como desculpa para monólito.
-- Proibido: `index_p1.html`, `index_p2.html` ou nomes semelhantes quando eles só escondem um arquivo gigante sem fronteira semântica.
-
-## Sinal vs Ritual
-
-Score composto, `achados[]` e `decisaoAgente` são bons sinais operacionais. Abaixo de 80 bloqueia; alvo evolui 0.5 ponto até 100; vira teatro se a IA só coloca palavra-chave para passar.
-
-- Fraca: achado atendido precisa de evidência simples e visível.
-- Média: conecte cada regra a contrato, arquivo e comportamento esperado.
-- Forte: trate regex/palavra-chave como triagem, não como prova final de substância.
-- Caminho Linux do MCP remoto é espelho governado; não é o checkout local do usuário.
-
-## Design Visual
-
-Quando a tarefa envolve interface, app, site, dashboard, painel, formulário, landing, jogo ou artefato visual, o Sema governa também qualidade visual. Modernidade, identidade, responsividade, estados e evidência visual não são extras opcionais.
-
-- Fraca: Use um padrão moderno seguro: hierarquia clara, espaçamento consistente, paleta com contraste, estados básicos, responsivo mobile/desktop e nada de formulário cinza genérico. Se não conseguir validar visualmente, pare e peça revisão.
-  Evidência: descrever padrão visual escolhido, confirmar responsividade básica, listar estados essenciais.
-- Média: Defina intenção visual antes de codar: público, domínio, densidade, tokens, componentes, estados, responsividade e anti-2010. Rode ou peça screenshot/browser check quando houver UI.
-  Evidência: registrar tokens e componentes usados, validar desktop e mobile, corrigir texto sobreposto.
-- Forte: Crie direção visual específica do domínio, use assets reais/gerados quando fizer sentido, refine microinterações e faça verificação visual em desktop/mobile com screenshot e correção de overlap.
-  Evidência: screenshot desktop/mobile, verificação de assets e renderização, auditoria de contraste, hierarquia e estado vazio.
-- Proibido: interface_generica_2010, formularios_sem_hierarquia_visual, cards_cinzas_sem_identidade, layout_sem_responsividade_real, texto_estourando_ou_sobreposto, sem_estados_de_hover_focus_loading_erro_vazio, sem_assets_quando_o_dominio_pede_visual, copiar_estetica_do_contrato_para_ui.
-- Critérios mínimos: não parecer template de 2010, hierarquia visual clara, paleta com contraste e identidade do domínio, responsividade mobile e desktop, estados de hover, focus, loading, erro e vazio quando aplicáveis, texto sem overlap ou estouro, componentes coerentes com o workflow real.
-
-## Fraca
-
-Use para Copilot em modo simples, Cline/Roo com pouco contexto, modelos locais pequenos e agentes que ignoram instrução longa.
-
-- Entrada: `SEMA_BOOT.md` -> `SEMA_SMALL_MODEL.md` -> `SEMA_BRIEF.micro.txt`.
-- Não abrir AST/IR completos no começo.
-- Não editar se Sema não respondeu.
-- Não pedir para MCP remoto ler pasta local.
-- Não criar código ou contrato governado grande; divida antes de passar de 2000 linhas.
-- Não fatiar código ou contrato grande em partes artificiais; divida por responsabilidade real.
-- Não aceitar score ou achado como prova sem evidência concreta.
-
-## Média
-
-Use para agentes com bom contexto, mas sem garantia de seguir todos os gates.
-
-- Entrada: `SEMA_BOOT.md` -> `AGENT_CONTEXT_PACK.json` -> `SEMA_BRIEF.curto.txt` -> `SEMA_INDEX.json`.
-- Rodar docs-impacto antes de agir.
-- Validar drift e contrato no fechamento.
-- Tratar 1000+ linhas em código ou contrato governado como sinal de refatoração e 2000+ como bloqueio.
-- Em UI ou HTML estático, separar estrutura, estilos, estado, cálculo, renderização e dados antes de sincronizar.
-- Verificar se score, achados e decisão correspondem a regra real, não só termo copiado.
-
-## Forte
-
-Use para Codex, Claude e agentes com tool use confiável.
-
-- Entrada: `SEMA_BOOT.md` -> `AGENT_CONTEXT_PACK.json` -> `SEMA_BRIEF.md` -> `SEMA_INDEX.json`.
-- Pode consumir AST/IR/drift completos.
-- Ainda deve respeitar contrato primeiro e falha fechada.
-- Não usar contexto grande como desculpa para monólito: o mesmo orçamento vale para IA forte.
-- Se validar inline, ainda preparar o arquivo físico para a próxima IA com cabeçalho governado e descrição humana.
-- Se o MCP usar caminho Linux, tratar como espelho remoto autorizado, não como leitura local do usuário.
-
-## Timeout e Retry
-
-Timeout definido pelo agente não é falha do Sema. Se `sema resumo`, `inspecionar`, `drift` ou `sync-ai-entrypoints` estourar por timeout local, aumente o timeout e tente de novo com escopo menor quando possível.
-
-- Timeout inicial para resumo de projeto inteiro: 120s.
-- Escalonamento recomendado: 120s -> 300s -> 600s.
-- Fraca: Se `resumo . --micro` estourar, tente `resumo <arquivo.sema> --micro`, depois repita com timeout maior. Timeout não autoriza editar.
-- Média: Prefira resumo escopado; se um gate Sema estourar, aumente timeout e repita antes de concluir falha.
-- Forte: Pode rodar projeto inteiro com timeout alto, mas deve distinguir lentidão de falha real e registrar evidência.
-- Tente de novo com timeouts maiores enquanto houver execução disponível; se o ambiente impedir continuar, pare bloqueado e não avance com código sem Sema.
-
-## Idioma
-
-A linguagem humana da resposta deve seguir o idioma do usuário e preservar acentos, cedilha, pontuação e símbolos esperados. Em PT-BR, use vocabulário Sema canônico: pontuação, desvio semântico, trava, pré-checagem, ambiente de execução e perfil. A DSL .sema pode ter palavras-chave ASCII; isso não autoriza PT-BR sem acentos.
-
-A gramática Sema pode ter palavras-chave ASCII. Isso não autoriza resposta humana sem acentos.
-
-## Clientes
-
-- copilot: .github/copilot-instructions.md, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: media. VS Code/Copilot deve receber uma instrução curta e repetida no arquivo próprio, sem depender só do AGENTS.md.
-- cline: .clinerules/00-sema.md, .clinerules, SEMA_BOOT.md. Capacidade padrão: fraca. Cline costuma obedecer melhor quando o gate Sema vem em arquivo curto; se .clinerules for arquivo legado, o Sema atualiza esse fallback.
-- roo: .roo/rules/00-sema.md, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: fraca. Roo Code deve começar por uma regra dedicada em .roo/rules antes de abrir arquivos longos.
-- opencode: .opencode/instructions.md, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: media. OpenCode deve receber a mesma regra curta em instructions.md quando a pasta .opencode já existir.
-- cursor: .cursor/rules/sema.mdc, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: media. Cursor deve receber uma regra curta própria para não depender de leitura completa do AGENTS.md.
-- claude: .claude/CLAUDE.md, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: forte. Claude costuma seguir gates longos, mas ainda precisa de entrypoint explícito e repetido no workspace.
-- windsurf: .windsurf/rules.md, AGENTS.md, SEMA_BOOT.md. Capacidade padrão: media. Windsurf deve receber regra curta dedicada para evitar cair direto no código sem Sema.
-- generico: SEMA_BOOT.md, SEMA_SMALL_MODEL.md, AGENT_CONTEXT_PACK.json. Capacidade padrão: fraca. Qualquer agente sem integração específica começa pelo boot card e só sobe contexto se passar pelos gates.

package/docs/api.md

@@ -1,82 +0,0 @@
-# API and Operational Surfaces
-
-## English
-
-Sema is private end to end. The only public installation channel is the npm installer/client `@semacode/cli`; the product repository, hosted MCP control plane, account APIs, OAuth internals, dashboards, audit storage, and commercial runtime governance APIs stay private.
-
-### Public Surfaces
-
-- CLI installer/client commands documented in `README.md`, `docs/README.md`, and `docs/profiles.md`.
-- Official `.sema` examples exposed through the CLI package or authorized MCP tools.
-- Editor support installed from private/local VSIX artifacts.
-- Local validation flows executed by authorized users or agents.
-
-### 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 distributable artifacts;
-- run Sema validation and private-boundary checks before publishing the npm installer.
-
-## Português
-
-O Sema é privado de ponta a ponta. O único canal público de instalação é o instalador/cliente npm `@semacode/cli`; repositório de produto, control plane MCP hospedado, APIs de conta, detalhes internos de OAuth, dashboards, armazenamento de auditoria e APIs comerciais de runtime governance ficam privados.
-
-### Superfícies Públicas
-
-- Comandos do instalador/cliente CLI documentados em `README.md`, `docs/README.md` e `docs/profiles.md`.
-- Exemplos oficiais `.sema` expostos pelo pacote CLI ou por ferramentas MCP autorizadas.
-- Suporte de editor instalado a partir de VSIX privada/local.
-- Fluxos locais de validação executados por usuários ou agentes autorizados.
-
-### 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 de artefatos distribuíveis;
-- rodar validação Sema e checagem de fronteira privada antes de publicar o instalador npm.
-
-## Español
-
-Sema es privado de punta a punta. El único canal público de instalación es el instalador/cliente npm `@semacode/cli`; el repositorio de producto, el control plane MCP hospedado, APIs de cuenta, detalles internos de OAuth, dashboards, almacenamiento de auditoría y APIs comerciales de runtime governance permanecen privados.
-
-### Superficies Públicas
-
-- Comandos del instalador/cliente CLI documentados en `README.md`, `docs/README.md` y `docs/profiles.md`.
-- Ejemplos oficiales `.sema` expuestos por el paquete CLI o por herramientas MCP autorizadas.
-- Soporte de editor instalado desde VSIX privada/local.
-- Flujos locales de validación ejecutados por usuarios o agentes autorizados.
-
-### 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 de artefactos distribuibles;
-- ejecutar validación Sema y chequeo de frontera privada antes de publicar el instalador npm.