@semacode/cli 2.3.0 → 2.3.1

package/docs/ai-workflow.md

@@ -21,6 +21,10 @@ Closing rule: `sema drift --json` must return `sucesso:true`. If it reports `suc
 
 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 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.
+
+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.
+
 ## Codex Context Capacity
 
 - Small context: `SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`.

package/docs/auth.md

@@ -1,26 +1,26 @@
-# Local Runtime Boundary
-
-The public Sema CLI executes directly against the local workspace. It does not
-require a Sema login, user authentication, product authorization, license
-activation, install key, token, credits, billing service, control panel, or an
-external request.
-
-Use local commands:
-
-```bash
-sema --version
-sema resumo
-sema validar contratos/example.sema --json
-```
-
-The repository license governs use and redistribution. It is not checked as a
-runtime activation mechanism.
-
-An `authz` block inside a `.sema` contract describes authorization in the
-application being governed. It does not authenticate a person before the Sema
-CLI can run.
-
-Do not put private or sensitive operational material in this repository.
-
-Application-specific authentication belongs in the application repository that
-owns it.
+# Local Runtime Boundary
+
+The public Sema CLI executes directly against the local workspace. It does not
+require a Sema login, user authentication, product authorization, license
+activation, install key, token, credits, billing service, control panel, or an
+external request.
+
+Use local commands:
+
+```bash
+sema --version
+sema resumo
+sema validar contratos/example.sema --json
+```
+
+The repository license governs use and redistribution. It is not checked as a
+runtime activation mechanism.
+
+An `authz` block inside a `.sema` contract describes authorization in the
+application being governed. It does not authenticate a person before the Sema
+CLI can run.
+
+Do not put private or sensitive operational material in this repository.
+
+Application-specific authentication belongs in the application repository that
+owns it.

package/docs/cli.md

@@ -1,79 +1,79 @@
-# Sema CLI
-
-Sema is a Codex-native local CLI distribution. The public package reads the
-workspace on the user's machine, validates `.sema` contracts, checks drift,
-maps impact, and generates code without login, user authorization, license
-activation, tokens, credits, billing services, a control panel, or external
-service credentials.
-
-Support: suporte@otimitare.online
-
-## Install
-
-```bash
-npm install -g @semacode/cli
-sema --version
-```
-
-For development inside this repository:
-
-```bash
-npm install
-npm run build
-node pacotes/cli/dist/index.js --help
-```
-
-## Codex Setup
-
-`AGENTS.md` is the official Sema entrypoint for Codex. Create or refresh it from
-the local CLI:
-
-```bash
-sema sync-codex --json
-```
-
-Codex automatically loads `AGENTS.md` as repository guidance. Sema is an
-independent product and is not affiliated with or endorsed by OpenAI.
-
-## Required Local Flow
-
-Codex and humans should use the same local sequence before changing governed
-code, contracts, workflows, release scripts, or operational docs:
-
-```bash
-sema --version
-sema resumo
-sema docs-impacto --intencao "describe the change" --json
-sema inspecionar contratos/example.sema --json
-sema drift contratos/example.sema --escopo modulo --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.
-
-## 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 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.
-- `sema compilar`: generate code from contracts.
-- `sema testar`: generate, compile, and execute local contract tests, including `dotnet` and `cpp`.
-- `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.
-
-Generation targets are `typescript`, `python`, `php`, `dart`, `lua`,
-`javascript`, `html`, `css`, `dotnet`, and `cpp`. The aliases `cs` and
-`csharp` select `dotnet`; `c++`, `cxx`, and `cc` select `cpp`.
-Native targets are opt-in in `sema.config.json.alvos` for project-wide
-verification because they require local compiler toolchains.
-
-## Public Boundary
-
-Do not publish private or sensitive operational material in public Sema
-artifacts.
+# Sema CLI
+
+Sema is a Codex-native local CLI distribution. The public package reads the
+workspace on the user's machine, validates `.sema` contracts, checks drift,
+maps impact, and generates code without login, user authorization, license
+activation, tokens, credits, billing services, a control panel, or external
+service credentials.
+
+Support: suporte@otimitare.online
+
+## Install
+
+```bash
+npm install -g @semacode/cli
+sema --version
+```
+
+For development inside this repository:
+
+```bash
+npm install
+npm run build
+node pacotes/cli/dist/index.js --help
+```
+
+## Codex Setup
+
+`AGENTS.md` is the official Sema entrypoint for Codex. Create or refresh it from
+the local CLI:
+
+```bash
+sema sync-codex --json
+```
+
+Codex automatically loads `AGENTS.md` as repository guidance. Sema is an
+independent product and is not affiliated with or endorsed by OpenAI.
+
+## Required Local Flow
+
+Codex and humans should use the same local sequence before changing governed
+code, contracts, workflows, release scripts, or operational docs:
+
+```bash
+sema --version
+sema resumo
+sema docs-impacto --intencao "describe the change" --json
+sema inspecionar contratos/example.sema --json
+sema drift contratos/example.sema --escopo modulo --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.
+
+## 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 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.
+- `sema compilar`: generate code from contracts.
+- `sema testar`: generate, compile, and execute local contract tests, including `dotnet` and `cpp`.
+- `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.
+
+Generation targets are `typescript`, `python`, `php`, `dart`, `lua`,
+`javascript`, `html`, `css`, `dotnet`, and `cpp`. The aliases `cs` and
+`csharp` select `dotnet`; `c++`, `cxx`, and `cc` select `cpp`.
+Native targets are opt-in in `sema.config.json.alvos` for project-wide
+verification because they require local compiler toolchains.
+
+## Public Boundary
+
+Do not publish private or sensitive operational material in public Sema
+artifacts.

package/docs/commands.md

@@ -30,13 +30,17 @@ 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 drift <arquivo-ou-pasta> --escopo modulo --json`: compares contract and implementation.
+- `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 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.
 
+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.
+
 ## Sema Code
 
 - `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio>`: generates starter/support artifacts from the contract.
@@ -84,34 +88,33 @@ 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 its `targetSetDigest`, then 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 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 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.
+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.
+
+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 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.
+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.
 
 ## AI-native Interactive Systems
 
 - `sema interativo capabilities --json`: lists the canonical interactive capability vocabulary.
-- `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 schema --json`: exposes stable definition, extension-command, and data-schema shapes 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 --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`.
+- 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`.
 - 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 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.
+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.
 
 ## Operational
 

package/docs/database.md

@@ -1,15 +1,15 @@
-# Database Boundary
-
-The public Sema CLI does not require a database.
-
-Sema reads contracts and source files from the local workspace. Any database used
-by an application governed by Sema belongs to that application, not to the public
-Sema CLI distribution.
-
-## Public Rule
-
-Do not ship private database material, real credentials, operational schemas, or
-project-specific data in the public Sema package.
-
-Application-specific database docs should live in the application repository
-that owns the database.
+# Database Boundary
+
+The public Sema CLI does not require a database.
+
+Sema reads contracts and source files from the local workspace. Any database used
+by an application governed by Sema belongs to that application, not to the public
+Sema CLI distribution.
+
+## Public Rule
+
+Do not ship private database material, real credentials, operational schemas, or
+project-specific data in the public Sema package.
+
+Application-specific database docs should live in the application repository
+that owns the database.

package/docs/deploy.md

@@ -1,41 +1,41 @@
-# 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.
-
-Run the complete public gate:
-
-```bash
-npm run build
-npm run codex:sync-entrypoint
-npm run status:check
-npm run repo:verificar-publico
-npm run plugin:testar-codex
-npm test
-npm run release:verificar-drift
-npm run release:preparar-publica
-npm run release:publicar-npm-dry-run
-```
-
-`release:preparar-publica` performs the Codex entrypoint sync before checking
-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.
-
-Push the commit containing `.agents/plugins/marketplace.json` and
-`plugins/sema/` before telling users to install from `gerlanss/Sema`. Publish
-the npm package only after the tarball smoke passes. After npm publication, run
-`npm run release:verificar-distribuicao` to verify the registry and live GitHub
-state. That final verifier also requires the remote GitHub HEAD to match the
-local commit, installs `sema@sema` from `gerlanss/Sema` in an isolated
-`CODEX_HOME`, compares the remote skill with the versioned source, and proves
-that the remote plugin registers no Sema MCP. The current contract does not
-permit creating a GitHub Release or release asset.
-
-Do not publish private or sensitive operational material in this repository.
+# 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.
+
+Run the complete public gate:
+
+```bash
+npm run build
+npm run codex:sync-entrypoint
+npm run status:check
+npm run repo:verificar-publico
+npm run plugin:testar-codex
+npm test
+npm run release:verificar-drift
+npm run release:preparar-publica
+npm run release:publicar-npm-dry-run
+```
+
+`release:preparar-publica` performs the Codex entrypoint sync before checking
+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.
+
+Push the commit containing `.agents/plugins/marketplace.json` and
+`plugins/sema/` before telling users to install from `gerlanss/Sema`. Publish
+the npm package only after the tarball smoke passes. After npm publication, run
+`npm run release:verificar-distribuicao` to verify the registry and live GitHub
+state. That final verifier also requires the remote GitHub HEAD to match the
+local commit, installs `sema@sema` from `gerlanss/Sema` in an isolated
+`CODEX_HOME`, compares the remote skill with the versioned source, and proves
+that the remote plugin registers no Sema MCP. The current contract does not
+permit creating a GitHub Release or release asset.
+
+Do not publish private or sensitive operational material in this repository.

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.