@semacode/cli 2.3.1 → 3.5.0

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

package/docs/commands.md

@@ -7,19 +7,30 @@ Use this file when Codex does not know which command to run. A Sema command is a
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 sema docs-impacto --intencao "<acao>" --json
 ```
 
+If `sema` is absent from `PATH`, use `$HOME/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell resolves `sema.ps1` from PATH, cmd.exe resolves `sema.cmd`, and the absolute fallback is `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version`. `sema skill sync --json` repairs launcher and skill without touching the workspace or plugin caches.
+
 Then read every required doc returned by `docs-impacto`.
 
+## Public JSON output
+
+`sema --version` stays plain exact SemVer text. With `--json`, help and command-control failures use exactly one six-field `sema.cli.control/v1` document on stdout with empty stderr. Every syntactically valid command uses exactly one eight-field `sema.cli.result/v1` document containing only `schemaVersion`, `ok`, `kind`, `command`, `code`, `message`, `exitCode`, and `payload`. The command-specific result is nested under `payload`, never `data`; envelope `ok` does not replace domain fields inside that payload. Valid structured domain failures use `DOMAIN_ERROR`, while uncaught runtime exceptions remain redacted `FATAL_ERROR` control failures.
+
+## Global Distribution
+
+- `sema skill status --json`: diagnoses the managed launcher and bundled skill without writing.
+- `sema skill sync --json`: repairs only Sema-managed launcher and skill destinations; it never writes into the workspace or plugin caches.
+
 ## Contract and Discovery
 
 - `sema iniciar --template <template> [--force]`: creates a new Sema project and preserves existing files by default; `--force` is the only explicit overwrite path.
 - `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 inspecionar <arquivo-ou-pasta> [--drift <none|cache|fresh>] --json`: shows the contract surface; drift is skipped by default.
 - `sema ast <arquivo.sema> --json`: shows AST for syntax debugging.
 - `sema ir <arquivo.sema> --json`: shows the IR used by gates and generators.
 - `sema descobrir catalogo --json`: lists governance flows, profiles, specialized workflows, pipelines, generators, capability tokens, and adapters from their canonical registries.
@@ -30,16 +41,24 @@ Then read every required doc returned by `docs-impacto`.
 ## Change and Closure
 
 - `sema docs-impacto --intencao "<acao>" --json`: discovers required docs and documentary blockers.
-- `sema inspecionar <arquivo-ou-pasta> [--drift none|cache|fresh] [--com-drift] --json`: inspects contracts; the default is contract-only `none` and leaves code scores absent.
-- `sema resumo <arquivo-ou-pasta> --micro [--drift none|cache|fresh] --json`: produces a small contract summary; the default is contract-only `none` and explicitly says implementation was not verified.
-- `sema drift <arquivo-ou-pasta> --escopo modulo [--cache auto|refresh|off] --json`: compares contract and implementation after planning the physical scope.
+- `sema drift <arquivo-ou-pasta> --escopo modulo [--cache <none|cache|fresh>] --json`: plans a safe physical scope, then compares contract and implementation without a global fallback.
 - `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.
+Honest closure: unwrap drift JSON and treat its command payload as the source of truth. `payload.sucesso:false`, non-empty `payload.vinculos_quebrados`, non-empty `payload.rotas_divergentes`, or non-empty `payload.impls_quebrados` mean the change is not complete yet. Do not report "clean drift" without a green payload.
 
-Focused drift does not fall back to a global scan when it cannot prove a safe file anchor. With `--cache auto`, unchanged catalog snapshots, file metadata/content, dependency extraction, and semantic groups are reused only after schema, digest, identity, runtime-shape, and filesystem validation. The JSON fields `escopo_aplicado.catalogo`, `escopo_aplicado.cache.incremental`, and `escopo_aplicado.cache.fasesMs` expose visits, reads, hits, misses, extractions, writes, and phase timing.
+Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in `escopo_aplicado`. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only `--escopo projeto` may walk every configured code root. Logical roots such as `src` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and `inspecionar`, `impacto`, and `renomear-semantico` reuse the same directed boundary without reopening arbitrary external paths.
+
+Drift analysis and cache modes are explicit:
+
+- `sema drift` defaults to `--cache fresh`. `none` still executes drift but performs zero persistent-cache I/O; `cache` reuses a fully validated extraction hit and publishes misses; `fresh` ignores hits, recalculates, and publishes the new extraction.
+- `sema resumo` and `sema inspecionar` default to `--drift none`. In that mode their payload does not execute drift and returns `null` for score, confidence, implementation, routes, or other code evidence that was not observed. Use `--drift cache` or `--drift fresh` when that evidence is required. `--com-drift` remains a temporary alias for `--drift fresh`.
+- When a query explicitly runs drift, `payload.analiseDrift.sucesso` exposes the result and a failed requested analysis returns a nonzero exit code.
+- The value aliases `off`, `auto`, and `refresh` normalize to `none`, `cache`, and `fresh` for one compatibility release and emit a structured deprecation warning. Wrong flags, repeated flags, conflicts, and invalid values fail instead of falling back silently.
+- Persistent cache objects live outside the workspace under the operating system's user-cache directory. Workspace identity is hashed; public JSON and events expose only an opaque key and `$SEMA_CACHE/...` paths. Corruption or cache unavailability becomes a miss and never changes the drift result. Only validated extraction data is reused; links, diagnostics, scores, and the final success decision are recalculated.
+
+A cache hit is acceleration, not final evidence; closure still requires fresh drift.
 
 ## Sema Code
 
@@ -67,6 +86,7 @@ Ready UI rule: if the task generates an app, site, dashboard, form, or static HT
 - `sema ajuda-ia`: short guidance for Codex.
 - `sema starter-ia`: operational starter.
 - `sema contexto-ia <arquivo.sema> --saida <dir> --json`: AI context package.
+- `sema resumo <arquivo-ou-pasta> [--drift <none|cache|fresh>] --json`: compact context; drift is not executed unless requested.
 - `sema prompt-curto <arquivo-ou-pasta> --json`: compact prompt.
 - `sema sync-codex --json`: synchronizes the official Codex entrypoint and local support docs.
 - `sema instalar-exemplos --json`: installs official examples in the workspace.
@@ -88,33 +108,34 @@ Ready UI rule: if the task generates an app, site, dashboard, form, or static HT
 - `sema conteudo planejar <definition.json> --alvos-arquivo <targets.json> --json`: creates a declarative multi-target plan for an external runner.
 - `sema conteudo validar-envelope --envelope-arquivo <envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --payload-type <type> --json`: verifies Ed25519 identity, authorization, freshness, scope, and the separately pinned trust root and current revocation overlay.
 - `sema conteudo registrar <ledger.ndjson> --envelope-arquivo <envelope.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-id <id> --expected-head <sha256:...> --json`: appends a verified envelope under the signed run policy to the local replay ledger at an externally retained head.
-- `sema conteudo status <definition.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-arquivo <ledger.ndjson> --expected-head <sha256:...> --json`: verifies the signed policy and derives verdicts, operational conditions, completion, and next actions from canonical events.
+- `sema conteudo status <definition.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-arquivo <ledger.ndjson> --expected-head <sha256:...> --json`: verifies the signed policy and its `targetSetDigest`, then derives verdicts, operational conditions, completion, and next actions from canonical events.
 - `sema conteudo projetar <definition.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-arquivo <ledger.ndjson> --expected-head <sha256:...> --saida <manifest.json> --json`: regenerates a non-authoritative manifest bound to the ledger head.
 
-The content command never runs producers, evaluators, creative tools, or publication adapters; those belong to an external runner. It has no native human-review transition. A signed policy binds the run, definition, ledger, trust root, gates, complete target set, and authorization window. Stages select `adapterPolicy` as `NONE`, `CONSTRAINTS`, or `CONFIRMATION`; definition v1 accepts one output per stage. Constraint results must come from independent signed observations, including independently observed media type, not artifact metadata or executor claims.
+The content command is an AI-native, multi-channel, multi-format control plane. It never runs producers, evaluators, creative tools, or publication adapters; those belong to an external runner. It has no native human-review transition. A signed policy binds `runId`, definition, ledger, trust root, gates, complete target set, and the full `issuedAt`/`expiresAt` authorization window; no event may be recorded outside it. Stages select `adapterPolicy` as `NONE`, `CONSTRAINTS`, or `CONFIRMATION`; definition v1 accepts one output per stage. Constraint results must come from independent signed observations, including independently observed media type, not artifact metadata or executor claims. Target metadata is an exact scalar allowlist from `requiredMetadata + optionalMetadata`; `accountScope` is a credential-free `account:<alias>` reference, and artifact metadata is prohibited in v1. Deterministic evidence and AI opinions have separate quorum fields. Evidence requires an exact `content.evidence.attest:<evidenceType>` capability; adapter evidence requires `content.adapter.attest:<adapterId>@<version>:<evidenceType>` plus signed adapter binding.
 
-Target metadata is an exact scalar allowlist from `requiredMetadata + optionalMetadata`; `accountScope` is a credential-free `account:<alias>` reference, and artifact metadata is prohibited in v1. Deterministic evidence and AI opinions have separate quorum fields. Evidence requires an exact attestation capability plus signed adapter binding where applicable.
+Verdicts such as `APROVADO`, `REPROVADO`, and `INCONCLUSIVO` remain separate from operational conditions such as `AGUARDANDO_EVENTO_EXTERNO` and `FERRAMENTA_INDISPONIVEL`. A generated manifest is only a projection and cannot alter canonical state.
 
-Verdicts remain separate from operational conditions, and a generated manifest cannot alter canonical state. Append freshness uses the platform clock rather than caller-provided time, and an authority in the current revocation overlay cannot sign an accepted policy.
-
-Local NDJSON plus a hash chain is portable replay evidence, not a strong append-only trust boundary. Retain the expected head, canonical trust-root digest, and current revocation digest externally, or use protected storage for high assurance. A workspace-local trust file additionally requires `--development-local-trust`; that flag does not disable digest pinning.
+Local NDJSON plus a hash chain is portable evidence for replay, not a strong append-only trust boundary. Retain `expectedHead`, the canonical trust-root digest, and the current revocation digest externally, or use protected storage for high assurance. The trust-root pin identifies the authority snapshot independently from the revocation overlay. A workspace-local trust file additionally requires `--development-local-trust`; the flag does not disable digest pinning. Append freshness uses the platform clock rather than caller-provided `recordedAt`, and an authority in the current revocation overlay cannot sign an accepted policy.
 
 ## AI-native Interactive Systems
 
 - `sema interativo capabilities --json`: lists the canonical interactive capability vocabulary.
-- `sema interativo schema --json`: exposes stable definition, extension-command, and data-schema shapes for AI clients.
+- `sema interativo schema --json`: exposes the stable read-only definition schema, enum matrix, constraints, extension-command and data-schema shapes, plus canonical example paths for AI clients.
 - `sema interativo pipelines --json`: lists reusable game, simulation, and hybrid pipelines.
 - `sema interativo adapters [--spatial-model <NON_SPATIAL|TWO_D|TWO_POINT_FIVE_D|THREE_D>] [--render-mode <HEADLESS|TEXT|VISUAL|XR>] --json`: lists compatible external adapter descriptors.
 - `sema interativo validar <definition.json> --json`: validates independent kind, spatial model, render mode, visual profile, fidelity, control, time, world, budget, pipeline, and acceptance axes.
 - `sema interativo planejar <definition.json> --json`: expands compatible stages and required evidence without running an engine.
 - `sema interativo validar-evidencias|status <definition.json> [--plano-arquivo <plan.json>] --bundle-arquivo <bundle.json> --json`: validates a portable evidence bundle or derives non-authoritative status; `--evidencias-arquivo` is an alias and an omitted plan is recomputed deterministically.
 - `sema interativo validar-protocolo <adapter-run.json> --json`: checks DETECT/PROBE/SNAPSHOT/PLAN/APPLY/VALIDATE/EVIDENCE/ROLLBACK ordering and stable target binding.
-- Experience IR: `validar-ir`, `indexar-ir`, `consultar-ir`, `chunk-ir`, and `descrever-ir`.
-- Operational state: `validar-engine-snapshot`, `diff-engine-snapshots`, `validar-asset-provenance`, `validar-editor-state`, `planejar-jobs`, `validar-acceptance`, `operar-acceptance`, and `validar-multimodal`.
-- Temporal, autonomy, and testing: `validar-temporal`, `validar-evidencia-temporal`, `validar-autonomia`, `validar-playtest-fuzz`, and `validar-multiplayer`.
+- Experience IR: `validar-ir`, `indexar-ir`, `consultar-ir --semantic-id <id>`, `chunk-ir --semantic-id <id> [--raso]`, and `descrever-ir`.
+- Operational state: `validar-engine-snapshot`, `diff-engine-snapshots`, `validar-asset-provenance`, `validar-editor-state`, `planejar-jobs`, `validar-acceptance`, `operar-acceptance --operation <VALIDATE|EVALUATE|INVALIDATE> --context-file <file>`, and `validar-multimodal`.
+- Temporal, autonomy, and testing: `validar-temporal`, `validar-evidencia-temporal --bundle-arquivo <file>`, `validar-autonomia`, `validar-playtest-fuzz`, and `validar-multiplayer`.
 - Portability and workers: `analisar-portabilidade` and `validar-workers`.
+- `sema interativo validar-control-run <control-run.json> --definition-arquivo <definition.json> --plano-arquivo <plan.json> --contrato-arquivo <validation-contract.json> --entrada-arquivo <input.json> [--entrada-auxiliar-arquivo <supporting-input.json>] --evidencia-arquivo <evidence.json> --resultado-arquivo <result.json> --json`: binds one advanced validation to its complete local digest chain instead of trusting a standalone result.
+
+The control-run command recomputes the canonical plan and selected pure validator, then verifies the definition, pipeline descriptor, validation contract, schema-declared inputs, evidence, and result digests. Prefix advanced items with `sema interativo` and pass the documented JSON file as the positional argument; an agent does not have to infer the validator or payload shape from a filename or visual style. The machine-readable schema publishes command maps, input/output schema links, required top-level fields, `outputTargets` path segments from the payload root, at least one real output shape per command, and official fixtures for all 20 advanced commands. Validation-result shapes describe `payload.resultado`; projected IR values use `indice`, `entry`, `chunk`, or `descriptor`; operation projections such as `engineDiff` and `jobOrchestrationPlan` live under `payload.resultado.value`; the job plan's ordered `queue` is the assignment list and exposes kind, priority, adapter, dependencies, locks, budgets, heartbeat, checkpoint, and recovery data.
 
-Spatial model and render mode are orthogonal: `THREE_D + HEADLESS` is valid, while XR requires `THREE_D`. `PIXEL_8_BIT` and `PIXEL_16_BIT` are independent visual profiles available to games and simulations. Every command above is local and read-only; external runners own engine/editor execution, authorization, mutation, rollback, migration, rendering, playtest, and worker scheduling. Full local coverage is `STRUCTURALLY_COMPLETE`, never authoritative completion.
+Spatial model and render mode are orthogonal: `THREE_D + HEADLESS` is valid, while XR requires `THREE_D`. `PIXEL_8_BIT` and `PIXEL_16_BIT` are independent visual profiles available to games and simulations. Every command above rejects unknown, duplicate, missing-value, or invalid-enum arguments, remains local, read-only, and non-authoritative, and leaves engine/editor execution, authorization, mutation, rollback, migration, rendering, playtest, and worker scheduling to external runners. Full local coverage is `STRUCTURALLY_COMPLETE`, never authoritative completion, and a local evidence bundle is never presented as authoritative trust.
 
 ## Operational
 
@@ -122,12 +143,12 @@ Spatial model and render mode are orthogonal: `THREE_D + HEADLESS` is valid, whi
 
 ## Forbidden
 
-- Do not use an external workspace source to inspect a local workspace when `sema --version` works.
+- Do not use an external workspace source to inspect a local workspace when `sema --version` or the managed launcher 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 the contract requires generated 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 say drift passed when the unwrapped `sema drift --cache fresh --json` payload returned `sucesso:false`, a non-empty `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados` list.
 - Do not declare a UI responsive without mobile/desktop proof; horizontal scroll at 390px blocks closure.
 
 Governed code policy: keep the `SEMA-GOVERNED` marker, split large code by real responsibility, preserve contract links, and never treat a generated output directory as the final delivery.

package/docs/deploy.md

@@ -1,8 +1,9 @@
 # Deployment Boundary
 
-The public Sema repository documents two coordinated release surfaces: the
-local npm CLI and the Codex bootstrap skill. The skill remains a separate,
-explicit Codex installation and is never injected by npm lifecycle scripts.
+The public Sema repository documents one coordinated npm artifact containing
+the local CLI, its absolute managed launcher, and the portable bootstrap skill.
+The repository Codex plugin remains an optional namespaced distribution channel
+for the same versioned skill.
 
 Run the complete public gate:
 
@@ -22,11 +23,23 @@ npm run release:publicar-npm-dry-run
 the public boundary, so a clean clone does not depend on ignored generated
 handshake files left by a previous local run.
 
-The plugin smoke installs the repo marketplace into an isolated `CODEX_HOME`,
-installs `sema@sema`, compares the cached skill with the versioned source, and
-proves no Sema MCP server was registered. Plugin and CLI versions must match
-before the commit is pushed. The release command itself runs the full test suite
-and project-wide Sema drift gate; these are not optional manual preliminaries.
+All release and local-install routes delegate to `npm run
+cli:empacotar-publica`. The factory uses a unique private stage, disables npm
+lifecycle scripts while packing that stage, and publishes only a fully
+validated tarball. Do not use `npm pack --workspace @semacode/cli`; the source
+package guard rejects that unsupported path without staging files in the
+workspace.
+
+The public-package smoke performs a global install with isolated home, npm
+prefix, npm cache, and user cache. It proves the launcher works through its
+absolute path with Node.js and npm removed from `PATH`. On Windows it exercises
+`sema.ps1` as the PowerShell `PATH` entrypoint, `sema-managed.ps1` through the
+absolute `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`, and
+`sema.cmd` through `cmd.exe`. The smoke also proves the synchronized
+skill matches the packaged source, the real user home is unchanged, and local
+installs leave global state untouched. The plugin smoke independently compares
+its cached skill with the versioned source and proves no Sema MCP server was
+registered. Plugin and CLI versions must match before the commit is pushed.
 
 Push the commit containing `.agents/plugins/marketplace.json` and
 `plugins/sema/` before telling users to install from `gerlanss/Sema`. Publish

package/docs/descoberta-capacidades.md

@@ -1,106 +1,106 @@
-# Capability Discovery
-
-Sema exposes one explainable catalog so an AI can distinguish a validation
-profile, an orchestration pipeline, a specialized workflow, a generator, a
-governance gate, an adapter descriptor, and an opaque capability token.
-
-Discovery is local, deterministic, and read-only. It recommends or explains a
-capability but never executes the recommended command:
-
-```bash
-sema descobrir catalogo --json
-sema descobrir recomendar --intencao "validar simulador 3D autonomo calibrado" --json
-sema descobrir recomendar --intencao "port a 16-bit game to another engine and declare losses" --json
-sema descobrir explicar interactive.portability --json
-sema pipeline listar --json
-sema pipeline descrever interactive.playtest --json
-sema capabilities --json
-```
-
-The response schema is `sema.discovery/v1` and always reports:
-
-- `executed: false`;
-- `workspaceMutated: false`;
-- `externalCalls: false`;
-- actionable command templates with placeholders;
-- required inputs and execution boundaries;
-- matched signals, reasons, missing inputs, and stable scores.
-
-Advanced interactive intent is routed to the narrowest local validator or
-analyzer (`validar-temporal`, `validar-playtest-fuzz`, `analisar-portabilidade`,
-and peers). A broad profile or engine descriptor does not outrank that specific
-pipeline, and the suggested template retains every required file and flag.
-
-Raw paths and credential-like values supplied in intents or filters are used
-only for the in-memory lookup and are redacted from JSON and human output.
-
-## Catalog coverage
-
-The interactive catalog exposes **35 unique pipelines** and **28 unique
-external adapter descriptors**. The pipeline set covers the original game and
-simulation lifecycle plus P0/P1/P2 operational capabilities:
-
-- P0 representation and observation: Experience IR, engine snapshots, asset
-  provenance, editor state, multimodal evidence, resumable jobs, and acceptance
-  locks;
-- P1 behavior over time: timeline validation, shot/camera checks, physics
-  relations, temporal QA, clean-install/launch/smoke checks, and hardware
-  budgets;
-- P2 autonomy and scale: safe repair cycles, bot playtests, state fuzzing,
-  multiplayer authority, engine migration, portability with declared losses,
-  and distributed job DAGs.
-
-These entries apply across 3D, 2.5D, 2D, 8-bit, 16-bit, text, XR, and headless
-games and simulations. Discovery ranks the requested goal independently from
-the spatial model and visual profile.
-
-The 28 adapters are **descriptors for external capabilities**. Catalog lookup
-does not detect an installed engine, inspect an editor, enumerate plug-ins,
-probe processes, contact a worker, or prove that any integration is available.
-An external runner must establish runtime availability and return bound
-evidence.
-
-## Capability kinds
-
-- `GOVERNANCE_FLOW`: contract, drift, impact, verification, and closure gates.
-- `PROFILE_GATE`: semantic validation such as game, simulation, software, or ops.
-- `SPECIALIZED_WORKFLOW`: dedicated surfaces such as `sema author`.
-- `ORCHESTRATION_PIPELINE`: a staged workflow such as content, interactive
-  playtest, temporal validation, portability, or distributed jobs.
-- `CAPABILITY_TOKEN`: an opaque producer, evaluator, runtime, or evidence token.
-- `GENERATOR`: code generation targets.
-- `ADAPTER`: compatibility descriptors for external engines, editors, runtimes,
-  observers, verifiers, asset tools, build systems, and workers.
-
-`author` is intentionally a specialized workflow, not a fake
-`sema profile validar author` command. Likewise, `profile.game` validates game
-semantics; it is not the same thing as the `interactive.playtest` pipeline.
-
-## Deterministic recommendation
-
-The base router normalizes accents and aliases, applies positive and negative
-signals, scores the entry kind and domain, and sorts by score then stable ID.
-The minimum recommendation score is 60. When the top two candidates are within
-seven points, the response reports ambiguity and does not choose a command.
-
-This rule is deliberate: an AI should request more concrete intent instead of
-silently running the wrong pipeline.
-
-Interactive pipeline entries point to declarative planning with
-`sema interativo planejar <definition.json> --json`. The definition must list
-the recommended pipeline ID; the secondary `descrever` template remains
-available when the AI first needs the pipeline contract. Advanced entries point
-to their dedicated `sema interativo` validator or analyzer. Those commands
-still return local, non-authoritative results and do not execute engines,
-editors, plug-ins, or workers.
-
-Legacy views remain available:
-
-```bash
-sema profile capabilities --json
-sema conteudo capabilities --json
-sema interativo capabilities --json
-```
-
-They are projections of the same authoritative catalog sources, not separate
-manually maintained product maps.
+# Capability Discovery
+
+Sema exposes one explainable catalog so an AI can distinguish a validation
+profile, an orchestration pipeline, a specialized workflow, a generator, a
+governance gate, an adapter descriptor, and an opaque capability token.
+
+Discovery is local, deterministic, and read-only. It recommends or explains a
+capability but never executes the recommended command:
+
+```bash
+sema descobrir catalogo --json
+sema descobrir recomendar --intencao "validar simulador 3D autonomo calibrado" --json
+sema descobrir recomendar --intencao "port a 16-bit game to another engine and declare losses" --json
+sema descobrir explicar interactive.portability --json
+sema pipeline listar --json
+sema pipeline descrever interactive.playtest --json
+sema capabilities --json
+```
+
+The response schema is `sema.discovery/v1` and always reports:
+
+- `executed: false`;
+- `workspaceMutated: false`;
+- `externalCalls: false`;
+- actionable command templates with placeholders;
+- required inputs and execution boundaries;
+- matched signals, reasons, missing inputs, and stable scores.
+
+Advanced interactive intent is routed to the narrowest local validator or
+analyzer (`validar-temporal`, `validar-playtest-fuzz`, `analisar-portabilidade`,
+and peers). A broad profile or engine descriptor does not outrank that specific
+pipeline, and the suggested template retains every required file and flag.
+
+Raw paths and credential-like values supplied in intents or filters are used
+only for the in-memory lookup and are redacted from JSON and human output.
+
+## Catalog coverage
+
+The interactive catalog exposes **35 unique pipelines** and **28 unique
+external adapter descriptors**. The pipeline set covers the original game and
+simulation lifecycle plus P0/P1/P2 operational capabilities:
+
+- P0 representation and observation: Experience IR, engine snapshots, asset
+  provenance, editor state, multimodal evidence, resumable jobs, and acceptance
+  locks;
+- P1 behavior over time: timeline validation, shot/camera checks, physics
+  relations, temporal QA, clean-install/launch/smoke checks, and hardware
+  budgets;
+- P2 autonomy and scale: safe repair cycles, bot playtests, state fuzzing,
+  multiplayer authority, engine migration, portability with declared losses,
+  and distributed job DAGs.
+
+These entries apply across 3D, 2.5D, 2D, 8-bit, 16-bit, text, XR, and headless
+games and simulations. Discovery ranks the requested goal independently from
+the spatial model and visual profile.
+
+The 28 adapters are **descriptors for external capabilities**. Catalog lookup
+does not detect an installed engine, inspect an editor, enumerate plug-ins,
+probe processes, contact a worker, or prove that any integration is available.
+An external runner must establish runtime availability and return bound
+evidence.
+
+## Capability kinds
+
+- `GOVERNANCE_FLOW`: contract, drift, impact, verification, and closure gates.
+- `PROFILE_GATE`: semantic validation such as game, simulation, software, or ops.
+- `SPECIALIZED_WORKFLOW`: dedicated surfaces such as `sema author`.
+- `ORCHESTRATION_PIPELINE`: a staged workflow such as content, interactive
+  playtest, temporal validation, portability, or distributed jobs.
+- `CAPABILITY_TOKEN`: an opaque producer, evaluator, runtime, or evidence token.
+- `GENERATOR`: code generation targets.
+- `ADAPTER`: compatibility descriptors for external engines, editors, runtimes,
+  observers, verifiers, asset tools, build systems, and workers.
+
+`author` is intentionally a specialized workflow, not a fake
+`sema profile validar author` command. Likewise, `profile.game` validates game
+semantics; it is not the same thing as the `interactive.playtest` pipeline.
+
+## Deterministic recommendation
+
+The base router normalizes accents and aliases, applies positive and negative
+signals, scores the entry kind and domain, and sorts by score then stable ID.
+The minimum recommendation score is 60. When the top two candidates are within
+seven points, the response reports ambiguity and does not choose a command.
+
+This rule is deliberate: an AI should request more concrete intent instead of
+silently running the wrong pipeline.
+
+Interactive pipeline entries point to declarative planning with
+`sema interativo planejar <definition.json> --json`. The definition must list
+the recommended pipeline ID; the secondary `descrever` template remains
+available when the AI first needs the pipeline contract. Advanced entries point
+to their dedicated `sema interativo` validator or analyzer. Those commands
+still return local, non-authoritative results and do not execute engines,
+editors, plug-ins, or workers.
+
+Legacy views remain available:
+
+```bash
+sema profile capabilities --json
+sema conteudo capabilities --json
+sema interativo capabilities --json
+```
+
+They are projections of the same authoritative catalog sources, not separate
+manually maintained product maps.