@semacode/cli 2.3.1 → 3.0.0

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.

package/docs/documentation.md

@@ -1,39 +1,49 @@
-# Documentation Governance
-
-Documentation is part of every governed change. Codex must use
-`sema docs-impacto` before editing contracts, code, operational docs, workflows,
-profiles, generated artifacts, or release material.
-
-Public Sema documentation is English and local-only.
-
-## Required Flow
-
-```bash
-sema docs-impacto --intencao "describe the change" --json
-```
-
-The result lists:
-
-- `leituraObrigatoria`: files that must be read before the change;
-- `docsAusentes`: missing docs that block the change;
-- `docsCriadas`: generated draft docs that must be completed by Codex;
-- `bloqueios`: blocking diagnostics.
-
-Before closing the change, prove the required docs were read:
-
-```bash
-sema finalizar-mudanca \
-  --intencao "describe the change" \
-  --doc-lida README.md \
-  --doc-lida docs/documentation.md \
-  --json
-```
-
-## Public Docs Rules
-
-- Write public docs in English.
-- Keep commands, file paths, package names, environment variable names, and DSL
-  keywords literal.
-- Do not include private or sensitive operational material.
-- Prefer local CLI examples.
-- Point support requests to suporte@otimitare.online.
+# Documentation Governance
+
+Documentation is part of every governed change. Codex must use
+`sema docs-impacto` before editing contracts, code, operational docs, workflows,
+profiles, generated artifacts, or release material.
+
+Public Sema documentation is English and local-only.
+
+## Required Flow
+
+```bash
+sema docs-impacto --intencao "describe the change" --json
+```
+
+The result lists:
+
+- `leituraObrigatoria`: files that must be read before the change;
+- `docsAusentes`: missing docs that block the change;
+- `docsCriadas`: generated draft docs that must be completed by Codex;
+- `bloqueios`: blocking diagnostics.
+
+Before closing the change, prove the required docs were read:
+
+```bash
+sema finalizar-mudanca \
+  --intencao "describe the change" \
+  --doc-lida README.md \
+  --doc-lida docs/documentation.md \
+  --json
+```
+
+## Public Docs Rules
+
+- Write public docs in English.
+- Keep commands, file paths, package names, environment variable names, and DSL
+  keywords literal.
+- Do not include private or sensitive operational material.
+- Prefer local CLI examples.
+- Point support requests to suporte@otimitare.online.
+
+## Contract Structure
+
+Documentation governance is split by capability: required-document resolution
+stays in `governanca_ia_documentacao.sema`, while localization and
+change-finalization evidence live in explicitly named child contracts. The
+same rule applies to drift and semantic-budget governance: keep a cohesive
+primary capability in the root contract and move secondary responsibilities to
+named children. Preserve task names, guarantees, implementations, and
+`vinculos`; never create numbered part files.

package/docs/drift-cache.md

@@ -0,0 +1,108 @@
+# Drift Cache And Query Evidence
+
+Sema exposes three drift modes, but the `none` mode intentionally means
+different things for direct drift execution and for query commands. The
+defaults preserve honest, low-cost queries while keeping an explicit drift run
+fresh by default.
+
+| Mode | `sema drift --cache <mode>` | `sema resumo --drift <mode>` / `sema inspecionar --drift <mode>` |
+| --- | --- | --- |
+| `none` | Runs drift without reading or writing persistent cache. | Skips drift analysis. This is the query default. |
+| `cache` | Reuses a valid cache entry; otherwise recalculates and publishes a new entry. | Runs drift with the same reuse-or-recalculate behavior. |
+| `fresh` | Does not reuse a prior hit, recalculates, and publishes a fresh entry. This is the direct drift default. | Runs drift from fresh inputs without reusing prior extraction data, then publishes the resulting entry. |
+
+Use `--cache none` when a direct analysis must leave no persistent cache access.
+Use `--drift none` when a summary or inspection should not perform drift at all.
+The two forms are not interchangeable.
+
+## Honest Query Evidence
+
+`sema resumo` and `sema inspecionar` default to `--drift none`. Their JSON
+payload includes an `analiseDrift` envelope that makes the omitted evaluation
+explicit:
+
+```json
+{
+  "analiseDrift": {
+    "modo": "none",
+    "executada": false,
+    "sucesso": null,
+    "cache": null
+  },
+  "scoreDrift": null,
+  "confiancaGeral": null
+}
+```
+
+The surrounding payload varies by command. A human-readable `aviso` or
+`avisos` entry explains why drift was not evaluated. Drift-derived framework,
+route, surface, bridge, and module implementation evidence is also `null` when
+applicable. In this context, `null` means **not evaluated**; it must never be
+interpreted as zero, empty, passing, or absent drift.
+
+Request `--drift cache` or `--drift fresh` when a query needs evaluated drift
+evidence. In that case, `payload.analiseDrift.sucesso` is `true` or `false`, and a
+failed requested analysis makes the command exit nonzero instead of hiding the
+failure behind a successful query response.
+
+## External Cache Location
+
+Persistent drift cache is stored outside the governed workspace:
+
+| Platform | Cache root |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\Sema\Cache`, falling back to `%USERPROFILE%\AppData\Local\Sema\Cache` |
+| macOS | `~/Library/Caches/Sema` |
+| Linux and other Unix systems | `$XDG_CACHE_HOME/sema`, falling back to `~/.cache/sema` |
+
+Drift entries live below `drift/v3/workspaces/<opaque-id>/objects/` inside that
+root. Public output represents such paths as `$SEMA_CACHE/drift/v3/...`.
+`$SEMA_CACHE` is a safe display placeholder, not a promise that an environment
+variable with that name exists, and Sema does not expose the real user cache
+path.
+
+Sema never writes persistent drift cache inside the repository, `.sema`,
+`.tmp`, generated project folders, or any other workspace location.
+
+## Authority And Recovery
+
+The cache is an acceleration layer, not governance evidence and not a source of
+truth. Contracts, source files, the active analysis plan, and the validated
+result remain authoritative.
+
+- A corrupt or incompatible entry is treated as a recoverable miss: Sema
+  recalculates instead of trusting it.
+- If external cache storage is unavailable, analysis continues by
+  recalculating; cache persistence does not become a governance blocker.
+- `cache` may reuse only a valid entry for the current workspace and inputs.
+- `fresh` never reuses cached extraction data before analysis. Publication may
+  read and validate an existing content-addressed winner to preserve CAS
+  integrity without changing the freshly calculated result.
+- Direct `none` performs no persistent cache reads or writes.
+
+These rules keep cache failures from hiding drift and keep the governed
+workspace free of machine-local state.
+
+## Semantic Integrity And Trust Limit
+
+The reusable payload stores canonical per-extractor indices. It does not store
+`todosSimbolos`, route aggregates, resource aggregates, or known-file
+aggregates as independent sources. Sema derives those values again after a
+cache entry is restored, so a redundant aggregate cannot silently override its
+source indices.
+
+Before accepting a hit, Sema checks exact field allowlists, relative catalog
+paths, extractor-specific file extensions and symbol origins, consumer-surface
+to route relationships, and derived integrity digests across symbols, routes,
+resources, surfaces, and persistence details. Detectable structural or
+semantic inconsistency becomes a corrupt miss, followed by a fresh in-memory
+calculation and repair. A valid hit is therefore limited to a compatible
+payload produced for the same CLI, schema, extractor, workspace identity, Git
+HEAD, plan, configuration, contracts, and content-digested members.
+
+These SHA-256 digests detect corruption and incoherent rewriting; they do not
+authenticate a hostile process running as the same operating-system user. Such
+a process can read the implementation and rewrite both data and checksums. The
+external cache is not a security boundary, a signature, or final evidence.
+Use `--cache fresh` for closure and retain stronger evidence outside the local
+user cache when the threat model includes local-user compromise.