@semacode/cli 2.3.1 → 3.0.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/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
 

package/docs/cli.md

@@ -13,16 +13,122 @@ Support: suporte@otimitare.online
 ```bash
 npm install -g @semacode/cli
 sema --version
+sema skill status --json
 ```
 
+The global install bundles the portable Sema skill and creates a launcher under
+`~/.sema/bin` with absolute Node.js and CLI paths. If the npm shim is absent
+from `PATH`, run `~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell
+resolves `sema.ps1` from `PATH`, while `cmd.exe` resolves `sema.cmd`; invoke the
+managed fallback through the absolute system executable:
+
+```powershell
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+```
+
+Use `sema skill sync --json` to repair an installation performed with lifecycle
+scripts disabled.
+
 For development inside this repository:
 
 ```bash
 npm install
 npm run build
-node pacotes/cli/dist/index.js --help
+node pacotes/cli/dist/bin.js --help
 ```
 
+## Side-Effect-Free Help
+
+`--help` and `-h` take precedence wherever they appear in argv, including after
+an unknown command or option. The CLI exits with status `0` before command
+runtime import, command dispatch, or handler resolution. Help does not inspect or mutate the workspace,
+home, user cache, or plugin cache, start a subprocess, or make a network call.
+
+`dist/bin.js` is the executable bootstrap and imports the operational runtime
+only after these control paths finish. `dist/index.js` remains the package API
+entrypoint and is not an executable alias.
+
+```bash
+sema iniciar --help
+sema formatar --help
+sema sync-codex --help
+sema skill sync --help
+sema unknown --option value --help
+```
+
+## Public JSON Output
+
+`sema --version` (and its version aliases) prints one plain exact SemVer string.
+It is intentionally not wrapped in JSON.
+
+### Help and command control
+
+Adding `--json` to help or a command-control failure emits exactly one JSON
+document on stdout and keeps stderr empty:
+
+```json
+{
+  "schemaVersion": "sema.cli.control/v1",
+  "ok": true,
+  "kind": "HELP",
+  "code": "CLI_HELP",
+  "message": "Sema CLI help",
+  "exitCode": 0
+}
+```
+
+The envelope contains exactly `schemaVersion`, `ok`, `kind`, `code`, `message`,
+and `exitCode`. Supported control kinds are `HELP`, `UNKNOWN_COMMAND`,
+`ARGUMENT_ERROR`, and `FATAL_ERROR`. Help uses exit code `0`; failures preserve
+a non-zero process status equal to `exitCode`. Failure messages are public and
+redacted: they do not include stacks, absolute paths, raw argv, or internal
+causes.
+
+Command-control failures are unknown top-level commands or subcommands, missing
+or invalid required CLI arguments/options rejected before valid dispatch, and
+uncaught runtime exceptions. An uncaught exception uses the redacted
+`FATAL_ERROR` control envelope. `sema.cli.control/v1` is never nested inside a
+command result.
+
+### Valid command results
+
+In 3.0.0, every syntactically valid command invoked with `--json` emits exactly
+one `sema.cli.result/v1` document on stdout with empty stderr:
+
+```json
+{
+  "schemaVersion": "sema.cli.result/v1",
+  "ok": true,
+  "kind": "SUCCESS",
+  "command": "resumo",
+  "code": "CLI_SUCCESS",
+  "message": null,
+  "exitCode": 0,
+  "payload": {
+    "comando": "resumo",
+    "sucesso": true
+  }
+}
+```
+
+The result envelope contains exactly `schemaVersion`, `ok`, `kind`, `command`,
+`code`, `message`, `exitCode`, and `payload`; extra or missing fields are
+invalid, and `data` is not an alias for `payload`. `command` is the canonical
+top-level command name. `payload` is always present and may be any JSON value,
+including an object, array, scalar, or `null`.
+
+- `SUCCESS` requires `ok: true`, `code: "CLI_SUCCESS"`, `message: null`, and
+  `exitCode: 0`.
+- `DOMAIN_ERROR` requires `ok: false`, `code: "CLI_DOMAIN_ERROR"`, a non-empty
+  safe public `message`, and a positive `exitCode` equal to the process status.
+
+The envelope describes the CLI result transport and classification. It does
+not replace the command's domain model: consumers must unwrap `payload` and
+evaluate fields such as `payload.sucesso`, `payload.aprovado`,
+`payload.bloqueado`, or another command-specific verdict separately. A
+syntactically valid operation that returns a structured domain failure uses
+`DOMAIN_ERROR`; it does not fall back to `sema.cli.control/v1`.
+
 ## Codex Setup
 
 `AGENTS.md` is the official Sema entrypoint for Codex. Create or refresh it from
@@ -42,22 +148,24 @@ code, contracts, workflows, release scripts, or operational docs:
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 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 sema.example.target --mudanca "describe the change" --json
 ```
 
 Commands run directly against the local workspace. If `sema --version` fails,
-install or repair the npm package; there is no separate authorization gate.
+try the managed absolute launcher before declaring the CLI unavailable. If both
+fail, install or repair the npm package; there is no separate authorization
+gate.
 
 ## Core Commands
 
 - `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 inspecionar`: inspect the applicable contract surface; add `--drift cache|fresh` to request code evidence.
+- `sema drift`: compare contracts and implementation with `--cache none|cache|fresh` (default `fresh`).
 - `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.
@@ -66,6 +174,16 @@ install or repair the npm package; there is no separate authorization gate.
 - `sema verificar`: run the final local verification bundle.
 - `sema contexto-ia`: build local AI context from a contract.
 - `sema sync-codex`: create or refresh the official `AGENTS.md` entrypoint.
+- `sema skill status|sync`: inspect or repair the managed launcher and bundled
+  global skill without touching plugin caches or workspace files.
+
+`resumo` and `inspecionar` default to `--drift none`, so they do not fabricate
+scores or implementation evidence. In this mode those fields inside `payload`
+are `null` or explicitly not evaluated. `sema drift --cache none` still runs
+the analysis but does not touch persistent cache. `cache` reuses only a validated extraction hit;
+`fresh` ignores hits and republishes recalculated extraction data. Cache objects
+live in the operating system's user-cache directory outside the workspace, and
+the final links, diagnostics, score, and success decision are always recomputed.
 
 Generation targets are `typescript`, `python`, `php`, `dart`, `lua`,
 `javascript`, `html`, `css`, `dotnet`, and `cpp`. The aliases `cs` and