@semacode/cli 2.3.1 → 3.5.0

package/dist/skillCommand.d.ts

@@ -0,0 +1,5 @@
+import { type ResultadoDistribuicaoGlobal } from "./distribuicao/index.js";
+type OperacaoSkill = "status" | "sync";
+export declare function renderizarResultadoSkill(operacao: OperacaoSkill, resultado: ResultadoDistribuicaoGlobal): string;
+export declare function comandoSkill(posicionais: string[], args: string[], emJson: boolean): Promise<number>;
+export {};

package/dist/skillCommand.js

@@ -0,0 +1,88 @@
+// SEMA-GOVERNED: sema.produto.distribuicao_global, sema.produto.distribuicao_global.skill
+// Descrição: expõe diagnóstico read-only e reparo explícito da distribuição global gerenciada.
+import { sincronizarDistribuicaoGlobal, statusDistribuicaoGlobal, } from "./distribuicao/index.js";
+export function renderizarResultadoSkill(operacao, resultado) {
+    const linhas = [
+        `Distribuição global Sema (${operacao}): ${resultado.estado}`,
+        `  Alterada: ${resultado.alterado ? "sim" : "não"}`,
+        `  Launcher: ${resultado.launcher.estado} (${resultado.launcher.destino_simbolico})`,
+        ...(resultado.launcher.fallback_simbolico
+            ? [`  Fallback PowerShell: ${resultado.launcher.fallback_simbolico}`]
+            : []),
+        `  Diagnóstico launcher: ${resultado.launcher.codigo}`,
+        `  Skill: ${resultado.skill.estado} (${resultado.skill.origem_simbolica})`,
+        `  Destino .agents: ${resultado.skill.destino_agents}`,
+        `  Destino Claude: ${resultado.skill.destino_claude}`,
+        `  Diagnósticos skill: ${resultado.skill.destinos
+            .map((destino) => `${destino.id}=${destino.codigo}`)
+            .join(", ") || "nenhum"}`,
+    ];
+    return linhas.join("\n");
+}
+function imprimirSubcomandoInvalido(emJson) {
+    const mensagem = "Use `sema skill status` ou `sema skill sync`.";
+    if (emJson) {
+        console.log(JSON.stringify({
+            schema: "sema.skill-distribution/v1",
+            comando: "skill",
+            sucesso: false,
+            erro: {
+                codigo: "SUBCOMANDO_SKILL_INVALIDO",
+                mensagem,
+            },
+        }, null, 2));
+        return;
+    }
+    console.error(mensagem);
+}
+export async function comandoSkill(posicionais, args, emJson) {
+    const operacao = (posicionais[0] ?? "status").toLocaleLowerCase("en-US");
+    const possuiArgumentoExtra = posicionais.length > 1;
+    const possuiFlagDesconhecida = args.some((arg) => arg.startsWith("-") && arg !== "--json");
+    if ((operacao !== "status" && operacao !== "sync")
+        || possuiArgumentoExtra
+        || possuiFlagDesconhecida) {
+        imprimirSubcomandoInvalido(emJson);
+        return 1;
+    }
+    try {
+        const resultado = operacao === "sync"
+            ? await sincronizarDistribuicaoGlobal()
+            : await statusDistribuicaoGlobal();
+        const sucesso = resultado.estado === "READY";
+        if (emJson) {
+            const payload = {
+                schema: "sema.skill-distribution/v1",
+                comando: "skill",
+                operacao,
+                sucesso,
+                resultado,
+            };
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(renderizarResultadoSkill(operacao, resultado));
+        }
+        return sucesso ? 0 : 1;
+    }
+    catch {
+        const mensagem = "Falha ao consultar ou sincronizar a distribuição global Sema.";
+        if (emJson) {
+            console.log(JSON.stringify({
+                schema: "sema.skill-distribution/v1",
+                comando: "skill",
+                operacao,
+                sucesso: false,
+                erro: {
+                    codigo: "FALHA_DISTRIBUICAO_GLOBAL",
+                    mensagem,
+                },
+            }, null, 2));
+        }
+        else {
+            console.error(mensagem);
+        }
+        return 1;
+    }
+}
+//# sourceMappingURL=skillCommand.js.map

package/dist/tipos.d.ts

@@ -1,3 +1,3 @@
 export type EstruturaSaida = "flat" | "modulos" | "backend";
-export type FonteLegado = "nestjs" | "fastapi" | "flask" | "nextjs" | "nextjs-consumer" | "react-vite-consumer" | "angular-consumer" | "flutter-consumer" | "firebase" | "typescript" | "javascript" | "python" | "dart" | "lua" | "dotnet" | "java" | "go" | "rust" | "cpp" | "php";
+export type FonteLegado = "nestjs" | "express" | "fastify" | "fastapi" | "flask" | "nextjs" | "nextjs-consumer" | "react-vite-consumer" | "angular-consumer" | "flutter-consumer" | "firebase" | "typescript" | "javascript" | "python" | "dart" | "lua" | "dotnet" | "java" | "go" | "rust" | "cpp" | "php";
 export type ModoAdocao = "incremental";

package/dist/typescript-http-modelos.d.ts

@@ -4,7 +4,7 @@ export interface ParametroRotaTypeScript {
     tipoSema: "Texto" | "Inteiro" | "Decimal" | "Id";
 }
 export interface RotaTypeScriptExtraida {
-    origem: "nextjs" | "firebase";
+    origem: "nextjs" | "firebase" | "express" | "fastify";
     metodo: string;
     caminho: string;
     simbolo: string;

package/dist/typescript-http-rotas.d.ts

@@ -6,4 +6,5 @@ export declare function inferirCaminhoNext(relacaoArquivo: string): {
 } | undefined;
 export declare function identificarRotasNodeHttp(sourceFile: ts.SourceFile, nomeSimbolo: string, corpo: ts.Block): RotaTypeScriptExtraida[];
 export declare function extrairRotasNodeWorker(sourceFile: ts.SourceFile, relacaoArquivo: string): RotaTypeScriptExtraida[];
+export declare function extrairRotasExpressFastify(sourceFile: ts.SourceFile): RotaTypeScriptExtraida[];
 export declare function extrairRotasTypeScriptHttp(sourceFile: ts.SourceFile, relacaoArquivo: string): RotaTypeScriptExtraida[];

package/dist/typescript-http-rotas.js

@@ -109,6 +109,98 @@ export function extrairRotasNodeWorker(sourceFile, relacaoArquivo) {
     }
     return deduplicarRotas(rotas);
 }
+export function extrairRotasExpressFastify(sourceFile) {
+    const textoArquivo = sourceFile.getFullText();
+    const importouExpress = /(?:from\s+["']express["']|require\(\s*["']express["']\s*\))/.test(textoArquivo);
+    const importouFastify = /(?:from\s+["']fastify["']|require\(\s*["']fastify["']\s*\))/.test(textoArquivo);
+    if (!importouExpress && !importouFastify) {
+        return [];
+    }
+    const rotas = [];
+    const escolherOrigemChamada = (receptor) => {
+        if (/fastify/i.test(receptor)) {
+            return "fastify";
+        }
+        if (importouExpress) {
+            return "express";
+        }
+        if (importouFastify) {
+            return "fastify";
+        }
+        return undefined;
+    };
+    const visitar = (node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression)) {
+            const receptor = node.expression.expression.text;
+            const nomeMetodo = node.expression.name.text.toLowerCase();
+            if (nomeMetodo === "route" && node.arguments[0] && ts.isObjectLiteralExpression(node.arguments[0]) && importouFastify) {
+                let metodo;
+                let caminho;
+                for (const propriedade of node.arguments[0].properties) {
+                    if (!ts.isPropertyAssignment(propriedade) || !ts.isIdentifier(propriedade.name)) {
+                        continue;
+                    }
+                    const valor = propriedade.initializer && ts.isStringLiteralLike(propriedade.initializer)
+                        ? propriedade.initializer.text
+                        : undefined;
+                    if (propriedade.name.text === "method" && valor) {
+                        metodo = valor.toUpperCase();
+                    }
+                    if (propriedade.name.text === "url" && valor) {
+                        caminho = valor;
+                    }
+                }
+                if (metodo && caminho?.startsWith("/") && METODOS_HTTP.has(metodo)) {
+                    rotas.push({
+                        origem: "fastify",
+                        metodo,
+                        caminho: converterCaminhoParametros(caminho),
+                        simbolo: receptor,
+                        parametros: extrairParametrosCaminhoDoisPontos(caminho),
+                    });
+                }
+            }
+            else if (nomeMetodo === "all" || METODOS_HTTP.has(nomeMetodo.toUpperCase())) {
+                const caminho = node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])
+                    ? node.arguments[0].text
+                    : undefined;
+                const origem = escolherOrigemChamada(receptor);
+                const handler = node.arguments[1] && ts.isIdentifier(node.arguments[1]) ? node.arguments[1].text : undefined;
+                if (caminho?.startsWith("/") && origem) {
+                    const metodos = nomeMetodo === "all"
+                        ? ["GET", "POST", "PUT", "PATCH", "DELETE"]
+                        : [nomeMetodo.toUpperCase()];
+                    for (const metodo of metodos) {
+                        rotas.push({
+                            origem,
+                            metodo,
+                            caminho: converterCaminhoParametros(caminho),
+                            simbolo: handler ?? receptor,
+                            parametros: extrairParametrosCaminhoDoisPontos(caminho),
+                        });
+                    }
+                }
+            }
+        }
+        node.forEachChild(visitar);
+    };
+    visitar(sourceFile);
+    return deduplicarRotas(rotas);
+}
+function converterCaminhoParametros(caminho) {
+    return caminho.replace(/:([A-Za-z_]\w*)/g, "{$1}");
+}
+function extrairParametrosCaminhoDoisPontos(caminho) {
+    const parametros = [];
+    for (const correspondencia of caminho.matchAll(/:([A-Za-z_]\w*)/g)) {
+        const nome = correspondencia[1];
+        parametros.push({
+            nome,
+            tipoSema: /(^|_)id$/i.test(nome) ? "Id" : "Texto",
+        });
+    }
+    return parametros;
+}
 export function extrairRotasTypeScriptHttp(sourceFile, relacaoArquivo) {
     const rotas = [];
     const caminhoNext = inferirCaminhoNext(relacaoArquivo);
@@ -124,6 +216,7 @@ export function extrairRotasTypeScriptHttp(sourceFile, relacaoArquivo) {
         }
     }
     rotas.push(...extrairRotasNodeWorker(sourceFile, relacaoArquivo));
+    rotas.push(...extrairRotasExpressFastify(sourceFile));
     return deduplicarRotas(rotas);
 }
 //# sourceMappingURL=typescript-http-rotas.js.map

package/dist/typescript-http.d.ts

@@ -1,3 +1,3 @@
 export type { CampoInferidoTypeScriptHttp, ExportacaoTypeScriptHttp, ParametroRotaTypeScript, RotaTypeScriptExtraida, SemanticaHandlerTypeScriptHttp, } from "./typescript-http-modelos.js";
-export { extrairRotasTypeScriptHttp } from "./typescript-http-rotas.js";
+export { extrairRotasExpressFastify, extrairRotasTypeScriptHttp } from "./typescript-http-rotas.js";
 export { inferirSemanticaHandlerTypeScriptHttp, localizarExportacaoTypeScriptHttp, } from "./typescript-http-semantica.js";

package/dist/typescript-http.js

@@ -1,5 +1,5 @@
 // SEMA-GOVERNED: sema.governanca_ia_contexto
 // Descricao: fachada de extracao HTTP TypeScript; consulte contratos/sema/governanca_ia_contexto.sema antes de editar.
-export { extrairRotasTypeScriptHttp } from "./typescript-http-rotas.js";
+export { extrairRotasExpressFastify, extrairRotasTypeScriptHttp } from "./typescript-http-rotas.js";
 export { inferirSemanticaHandlerTypeScriptHttp, localizarExportacaoTypeScriptHttp, } from "./typescript-http-semantica.js";
 //# sourceMappingURL=typescript-http.js.map

package/dist/verificacaoCache.d.ts

@@ -0,0 +1,25 @@
+export declare const SCHEMA_CACHE_VERIFICACAO = "sema.verificacao-cache/v1";
+export interface EntradaCacheVerificacao {
+    schemaVersion: typeof SCHEMA_CACHE_VERIFICACAO;
+    chave: string;
+    versaoCli: string;
+    alvo: string;
+    modulo: string;
+    sucesso: boolean;
+    quantidadeTestes: number;
+    testesExecutados: boolean;
+    arquivosGerados: string[];
+    geradoEm: string;
+}
+export declare function calcularChaveVerificacao(entradas: {
+    versaoCli: string;
+    versaoNode: string;
+    modulo: string;
+    alvo: string;
+    framework: string;
+    estrutura: string;
+    conteudoContrato: string;
+}): string;
+export declare function carregarCacheVerificacao(chave: string, pastaAlvo: string, raizCache?: string): Promise<EntradaCacheVerificacao | undefined>;
+export declare function carregarManifestoVerificacao(chave: string, raizCache?: string): Promise<EntradaCacheVerificacao | undefined>;
+export declare function gravarCacheVerificacao(entrada: EntradaCacheVerificacao, raizCache?: string): Promise<void>;

package/dist/verificacaoCache.js

@@ -0,0 +1,80 @@
+// SEMA-GOVERNED: sema.produto.cli_verificacao
+// Descrição: cache incremental de verificação fora do workspace, endereçado por conteúdo do contrato.
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolverRaizCacheSema } from "./driftCacheFilesystem.js";
+export const SCHEMA_CACHE_VERIFICACAO = "sema.verificacao-cache/v1";
+export function calcularChaveVerificacao(entradas) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        schemaVersion: SCHEMA_CACHE_VERIFICACAO,
+        versaoCli: entradas.versaoCli,
+        versaoNode: entradas.versaoNode,
+        modulo: entradas.modulo,
+        alvo: entradas.alvo,
+        framework: entradas.framework,
+        estrutura: entradas.estrutura,
+        conteudoContrato: entradas.conteudoContrato,
+    }))
+        .digest("hex");
+}
+function resolverPastaCacheVerificacao(raizCache) {
+    const resolucao = resolverRaizCacheSema(raizCache ? { raizCache } : {});
+    return resolucao.disponivel ? path.join(resolucao.raiz, "verificacao") : undefined;
+}
+export async function carregarCacheVerificacao(chave, pastaAlvo, raizCache) {
+    const pasta = resolverPastaCacheVerificacao(raizCache);
+    if (!pasta) {
+        return undefined;
+    }
+    let entrada;
+    try {
+        entrada = JSON.parse(await readFile(path.join(pasta, `${chave}.json`), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (entrada.schemaVersion !== SCHEMA_CACHE_VERIFICACAO || entrada.chave !== chave) {
+        return undefined;
+    }
+    for (const relativo of entrada.arquivosGerados) {
+        try {
+            await stat(path.join(pastaAlvo, relativo));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return entrada;
+}
+export async function carregarManifestoVerificacao(chave, raizCache) {
+    const pasta = resolverPastaCacheVerificacao(raizCache);
+    if (!pasta) {
+        return undefined;
+    }
+    try {
+        const entrada = JSON.parse(await readFile(path.join(pasta, `${chave}.json`), "utf8"));
+        if (entrada.schemaVersion !== SCHEMA_CACHE_VERIFICACAO || entrada.chave !== chave) {
+            return undefined;
+        }
+        return entrada;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function gravarCacheVerificacao(entrada, raizCache) {
+    const pasta = resolverPastaCacheVerificacao(raizCache);
+    if (!pasta) {
+        return;
+    }
+    try {
+        await mkdir(pasta, { recursive: true });
+        await writeFile(path.join(pasta, `${entrada.chave}.json`), `${JSON.stringify(entrada, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // Cache é aceleração: falha de gravação nunca derruba a verificação.
+    }
+}
+//# sourceMappingURL=verificacaoCache.js.map

package/docs/README.md

@@ -1,34 +1,38 @@
-# Sema Documentation
-
-These docs describe the public Codex-native local CLI distribution of Sema.
-
+# Sema Documentation
+
+These docs describe the public Codex-native local CLI distribution of Sema.
+
 Sema is local-first: Codex runs the CLI inside a project folder, reads `.sema`
 contracts, checks drift, maps impact, and closes changes with documentation
-evidence. `AGENTS.md` is the official Codex entrypoint. Public docs are written
+evidence. In 3.0.0, valid commands using `--json` return the exact
+`sema.cli.result/v1` envelope with command data nested under `payload`, while
+help and command-control failures keep the separate `sema.cli.control/v1`
+envelope. `AGENTS.md` is the official Codex entrypoint. Public docs are written
 in English.
-
-Sema is an independent product and is not affiliated with or endorsed by
-OpenAI. Codex-native describes Sema's product direction, not an official OpenAI
-program or submission.
-
-Start here:
-
-- [CLI](./cli.md)
-- [Commands](./commands.md)
+
+Sema is an independent product and is not affiliated with or endorsed by
+OpenAI. Codex-native describes Sema's product direction, not an official OpenAI
+program or submission.
+
+Start here:
+
+- [CLI](./cli.md) — installation and the public JSON output contract
+- [Commands](./commands.md) — command catalog and envelope-consumption rules
+- [Drift Cache And Query Evidence](./drift-cache.md)
 - [Syntax](./syntax.md)
-- [Profiles](./profiles.md)
-- [Capability Discovery](./descoberta-capacidades.md) — one explainable catalog
-  for governance flows, profiles, specialized workflows, pipelines, generators,
-  capability tokens, and adapters.
-- [AI-native Interactive Systems](./sistemas-interativos.md) — declarative
-  control plane for games, simulations, and hybrids across 3D, 2D, retro,
-  text, XR, and headless execution.
-- [AI-native Content Pipeline](./pipeline-conteudo.md) — signed-policy,
-  multi-channel and multi-format orchestration for external AI runners, with
-  canonical ledger replay and no native human-review path.
-- [Documentation Governance](./documentation.md)
-- [Repository Boundary](./repositories.md)
-- [Security](./security.md)
-- [Codex Integration](./ai-integration.md)
-
-Official support: [suporte@otimitare.online](mailto:suporte@otimitare.online)
+- [Profiles](./profiles.md)
+- [Capability Discovery](./descoberta-capacidades.md) — one explainable catalog
+  for governance flows, profiles, specialized workflows, pipelines, generators,
+  capability tokens, and adapters.
+- [AI-native Interactive Systems](./sistemas-interativos.md) — declarative
+  control plane for games, simulations, and hybrids across 3D, 2D, retro,
+  text, XR, and headless execution.
+- [AI-native Content Pipeline](./pipeline-conteudo.md) — signed-policy,
+  multi-channel and multi-format orchestration for external AI runners, with
+  canonical ledger replay and no native human-review path.
+- [Documentation Governance](./documentation.md)
+- [Repository Boundary](./repositories.md)
+- [Security](./security.md)
+- [Codex Integration](./ai-integration.md)
+
+Official support: [suporte@otimitare.online](mailto:suporte@otimitare.online)

package/docs/ai-integration.md

@@ -11,18 +11,22 @@ https://learn.chatgpt.com/docs/agent-configuration/agents-md.
 
 ## Before AGENTS.md Exists
 
-The official Sema skill is the required first-contact bootstrap for Codex in a
-project that does not have Sema yet. Install it explicitly:
+The official Sema skill is the first-contact bootstrap for a project that does
+not have Sema yet. A global CLI install bundles and synchronizes it:
 
 ```bash
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
+npm install -g @semacode/cli
+sema skill status --json
 ```
 
-The skill locates the local CLI, runs `sema iniciar`, generates `AGENTS.md`, and
-then delegates all ongoing workspace governance to that file. It contains no
+The package creates an absolute launcher under `~/.sema/bin`, synchronizes the
+canonical skill under `~/.agents/skills/sema`, and mirrors Claude only when
+detected. Informational requests stay read-only; before implementation the skill asks
+for explicit project-adoption authorization, then generates `AGENTS.md` and delegates
+ongoing governance. Installing or updating the global CLI authorizes distribution only.
+Already-open tasks may need a reload. The distribution contains no
 MCP server, remote workspace bridge, login, license, billing, token, credit,
-panel, or authorization gate.
+panel, or runtime authorization gate.
 
 Supported capacity labels: fraca, pequena, media, forte, grande.
 
@@ -32,10 +36,11 @@ For a local workspace, use the local CLI:
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 ```
 
-A successful `sema --version` is enough to use the local CLI directly. Local
+If the shell cannot resolve `sema`, use `~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell uses `sema.ps1` from PATH and cmd.exe uses `sema.cmd`; use `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version` as the absolute fallback
+before declaring the CLI unavailable. A successful version check is enough. Local
 commands require no login, activation key, license check, token, credits, billing
 service, control panel, or external authorization request.
 
@@ -43,13 +48,15 @@ service, control panel, or external authorization request.
 
 ```bash
 sema docs-impacto --intencao "describe the change" --json
-sema inspecionar contratos/example.sema --json
-sema drift contratos/example.sema --escopo modulo --json
+sema inspecionar contratos/example.sema --drift none --json
+sema drift contratos/example.sema --escopo modulo --cache fresh --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.
+A cache hit is acceleration, not evidence: closing requires `--cache fresh`,
+while contract-only queries keep unobserved implementation fields null inside the command payload.
 
 ## Codex Context Tiers
 
@@ -73,6 +80,12 @@ 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.
 
+Generated Lua tests preserve the contract's failure shape. A case whose only
+expectation is `sucesso: falso` may terminate without an output, while a case
+that also declares observable output fields must return a structured failure
+result. The generator keeps these paths distinct instead of forcing every
+failure into one representation.
+
 Governed code above 1000 lines requires a
 split plan. Governed code above 2000
 lines blocks closure. Markdown documentation is not counted as governed code
@@ -106,4 +119,4 @@ user-facing experience, closure requires evidence:
 ## Platform Policy
 
 Sema governs contract, scope, drift, evidence, and quality. It does not bypass
-platform policies, terms of use, permissions, security controls, or laws.
+platform policies, terms of use, permissions, security controls, or laws.

package/docs/ai-onboarding.md

@@ -1,18 +1,24 @@
 # Codex Onboarding
 
-The official Sema skill is required for Codex to recognize and initialize Sema
-before a project has its own protocol:
+The official Sema skill lets Codex and compatible agents recognize and
+initialize Sema before a project has its own protocol:
 
 ```bash
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
+npm install -g @semacode/cli
+sema skill status --json
 ```
 
-Open a new Codex task in the target repository after installation. Codex loads
-the plugin/skill catalog at task start, so `$sema` is not added retroactively to
-an already-open task. Invoke `$sema` in the new task; it bootstraps the project,
-reads the generated `AGENTS.md`, and later tasks load that protocol
-automatically.
+The install maintains the canonical copy in `~/.agents/skills/sema` and a Claude
+mirror in `~/.claude/skills/sema` only when Claude is detected. Open a new task
+after installation or update because an already-open task does not reload its
+skill catalog. Invoking `$sema` for information does not initialize the
+workspace. Before implementation, the skill asks for explicit adoption
+authorization; installing or updating the global CLI authorizes distribution
+changes only. After authorized adoption, it reads the generated `AGENTS.md`,
+and later tasks load that protocol automatically.
+
+The optional Codex plugin remains available as a separate namespaced channel;
+the npm lifecycle never writes into its cache.
 
 `AGENTS.md` is the official Sema entrypoint for Codex. It gives Codex the durable
 repository rule that contracts come first and the local CLI is the source of
@@ -32,18 +38,31 @@ This workspace is governed by Sema. Before editing code, contracts, docs,
 workflows, profiles, or release scripts, run:
 
 1. sema --version
-2. sema resumo
+2. sema resumo --drift none
 3. sema docs-impacto --intencao "<change>" --json
-4. sema inspecionar on the applicable .sema contract
-5. sema drift before editing existing code
+4. sema inspecionar <contract.sema> --drift none --json
+5. sema drift <contract.sema> --escopo modulo --cache fresh --json before
+   editing existing code
 6. sema impacto before changing behavior
 7. sema finalizar-mudanca before closing
 
-If the CLI is unavailable, stop and install or repair @semacode/cli. There is
-no separate Sema login, license activation, or authorization gate. Do not
-replace Sema with manual search or guessed contracts.
+If `sema --version` is unavailable, try the managed absolute launcher at
+`~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell uses `sema.ps1` from
+`PATH`, `cmd.exe` uses `sema.cmd`, and the absolute PowerShell fallback is:
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+If that also fails, stop and install or repair @semacode/cli. There is no
+separate Sema login or license-activation gate. Distribution installation does
+not authorize workspace adoption. Do not replace Sema with manual search or
+guessed contracts.
 ```
 
+Query commands default to `--drift none`, so their `analiseDrift` envelope marks
+the analysis as not executed and keeps drift-derived evidence `null`. Direct
+`sema drift` defaults to `--cache fresh`; `--cache none` still executes drift
+without persistent cache access. The cache is non-authoritative, lives outside
+the workspace, and safely falls back to recalculation when unavailable or
+corrupt. See [Drift Cache And Query Evidence](./drift-cache.md).
+
 ## What Codex Should Not Do
 
 - Do not invent `.sema` contracts.
@@ -52,9 +71,9 @@ replace Sema with manual search or guessed contracts.
 - Do not publish private or sensitive operational material.
 - Do not replace the local CLI when the local workspace is available.
 
-Other AI clients can invoke the public CLI manually, but Sema does not ship or
-manage an official repository entrypoint for them. The supported product path
-is Codex plus `AGENTS.md`.
+Compatible AI clients can discover the same portable skill through the
+canonical global `.agents/skills` root. Sema does not create client-specific
+repository rules: `AGENTS.md` remains the only official workspace entrypoint.
 
 Sema is an independent product and is not affiliated with or endorsed by
 OpenAI.

package/docs/ai-workflow.md

@@ -4,26 +4,28 @@
 This is the minimum workflow for Codex in a local workspace.
 
 1. Read `SEMA_BOOT.md`.
-2. Run `sema --version`. Success enables direct local execution; there is no login, license, token, billing, panel, or authorization gate.
-3. Run `sema resumo`.
+2. Run `sema --version`. If the shell cannot find it, use `$HOME/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell resolves `sema.ps1` from PATH and cmd.exe resolves `sema.cmd`; use `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version` as the absolute fallback. Only then declare the CLI unavailable.
+3. Run `sema resumo --drift none` for contract-only orientation; request `--drift cache` or `--drift fresh` only when code evidence is needed.
 4. Run `sema docs-impacto --intencao "<change>" --json`.
 5. Read every required document returned by the command.
 6. Read `docs/commands.md` before selecting a command or interpreting `--saida`.
 7. If the right capability is unclear, run `sema descobrir recomendar --intencao "<goal>" --json`; do not auto-run ambiguous recommendations.
 8. Use `exemplos/` and `docs/syntax.md` before creating or editing a contract.
-9. Run `sema drift` and `sema impacto` before editing existing code.
+9. Run `sema drift --cache fresh` and `sema impacto` before editing existing code.
 10. Run `sema formatar` and `sema validar` after changing a `.sema` contract.
 11. Run `sema finalizar-mudanca` with the documents read before closure.
 
 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.
+Closing rule: the `payload` of `sema drift --cache fresh --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. In 3.0.0, `ok` describes the CLI result path and never replaces a command-specific domain verdict.
 
-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.
+Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit `--escopo projeto`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. `inspecionar`, `impacto`, and `renomear-semantico` preserve the same directed boundary. Missing local dependencies make coverage partial and block success.
+
+Cache rule: a closure gate should use `sema drift <contrato> --escopo modulo --cache fresh --json`. `--cache none` executes the same analysis without persistent-cache I/O, while `--cache cache` may reuse only extraction data whose schema, workspace identity, Git HEAD, plan, configuration, contracts, member paths, and strong content digests all match. Cache objects are stored in the operating system's user-cache directory, never below the workspace. A hit is acceleration, not evidence: final links, diagnostics, score, and success are always recalculated. Corruption or an unavailable cache degrades to an in-memory calculation.
 
-Focused inspection rule: `sema inspecionar <contrato.sema>` and `sema resumo <contrato.sema> --micro` default to `--drift none`. They load the target plus its transitive `use` closure and must state that live code was not verified. Use `--drift cache`, `--drift fresh`, or `--com-drift` only when implementation evidence is required.
+Query honesty rule: `resumo` and `inspecionar` default to `--drift none`. When analysis is skipped, score, confidence, implementation, routes, and other unobserved code claims inside the command payload must be `null` or explicitly marked not evaluated; zero is not a substitute for absent evidence.
 
-Drift scope rule: a file/module run plans its physical file set before cataloging and never falls back to a whole-project walk when no safe anchor exists. `--cache auto` reuses validated catalog, file, and semantic-group entries; `--cache refresh` recalculates them; `--cache off` disables persistent cache I/O. Inspect `escopo_aplicado.catalogo`, `escopo_aplicado.cache.incremental`, and `escopo_aplicado.cache.fasesMs` for the work actually performed.
+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.
 
 ## Codex Context Capacity