@semacode/cli 2.2.0 → 2.3.1

package/docs/descoberta-capacidades.md

@@ -0,0 +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.

package/docs/documentation.md

@@ -1,39 +1,39 @@
-# 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.

package/docs/env.md

@@ -1,16 +1,16 @@
-# Environment
-
-The public Sema CLI works without private service credentials. No environment
-variable unlocks local execution: there is no login, activation, product
-authorization, license-key, billing, credit, token, or panel gate.
-
-Allowed public examples may use placeholders:
-
-```bash
-EXAMPLE_API_KEY=replace-me
-```
-
-Do not publish private or sensitive operational material in public Sema docs.
-
-If an application governed by Sema needs environment variables, document them in
-that application repository.
+# Environment
+
+The public Sema CLI works without private service credentials. No environment
+variable unlocks local execution: there is no login, activation, product
+authorization, license-key, billing, credit, token, or panel gate.
+
+Allowed public examples may use placeholders:
+
+```bash
+EXAMPLE_API_KEY=replace-me
+```
+
+Do not publish private or sensitive operational material in public Sema docs.
+
+If an application governed by Sema needs environment variables, document them in
+that application repository.

package/docs/frontend.md

@@ -1,41 +1,41 @@
-# User Experience Quality
-
-When Sema governs a UI, dashboard, app, site, game, or terminal tool, the
-experience must be modern, contextual, and verified. This is a quality gate, not
-decoration.
-
-## Before Building
-
-Define:
-
-- audience and domain
-- primary workflow
-- density and information hierarchy
-- interaction states
-- responsive behavior
-- accessibility basics
-- evidence needed before closing
-
-## Browser Evidence
-
-For web UI, check desktop and mobile. On a narrow viewport such as 390px, this
-must be true:
-
-```js
-document.documentElement.scrollWidth <= document.documentElement.clientWidth
-```
-
-Fix overlapping text, broken wrapping, hidden controls, and incoherent layout
-before closing the change.
-
-## Terminal Evidence
-
-For CLI/TUI work, smoke-check:
-
-- `--help`
-- success output
-- error output
-- JSON output when supported
-
-The public Sema CLI itself must stay local-only and must not depend on private
-or sensitive operational material for these checks.
+# User Experience Quality
+
+When Sema governs a UI, dashboard, app, site, game, or terminal tool, the
+experience must be modern, contextual, and verified. This is a quality gate, not
+decoration.
+
+## Before Building
+
+Define:
+
+- audience and domain
+- primary workflow
+- density and information hierarchy
+- interaction states
+- responsive behavior
+- accessibility basics
+- evidence needed before closing
+
+## Browser Evidence
+
+For web UI, check desktop and mobile. On a narrow viewport such as 390px, this
+must be true:
+
+```js
+document.documentElement.scrollWidth <= document.documentElement.clientWidth
+```
+
+Fix overlapping text, broken wrapping, hidden controls, and incoherent layout
+before closing the change.
+
+## Terminal Evidence
+
+For CLI/TUI work, smoke-check:
+
+- `--help`
+- success output
+- error output
+- JSON output when supported
+
+The public Sema CLI itself must stay local-only and must not depend on private
+or sensitive operational material for these checks.

package/docs/getting-started.md

@@ -1,57 +1,57 @@
-# Installation And First Use
-
-Sema is installed and used as a local CLI.
-
-```bash
-npm install -g @semacode/cli
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
-```
-
-Open a new Codex task in the target repository so the newly installed `$sema`
-skill is loaded, then ask it to initialize Sema. Existing tasks do not refresh
-their skill catalog. After bootstrap, `AGENTS.md` becomes the automatic protocol
-for subsequent tasks.
-
-Then verify the local engine:
-
-```bash
-sema --version
-sema resumo
-```
-
-The CLI is ready when `sema --version` succeeds. No Sema login, user
-authorization, activation key, product-license check, token, credits, billing
-service, or control panel is involved.
-
-The Codex skill is required for first contact with a project that does not yet
-have Sema. It only bootstraps the local CLI and generates the repository's
-`AGENTS.md`; that file becomes the automatic workspace protocol afterward.
-Plugin installation is explicit and does not happen from npm lifecycle scripts.
-
-## First Project
-
-```bash
-sema iniciar --template base
-sema validar contratos/*.sema --json
-sema resumo
-```
-
-`sema iniciar` preserves existing project files and refuses symlink or junction
-escapes. The bootstrap skill never uses `--force`; explicit overwrite remains a
-human decision.
-
-## Existing Project
-
-```bash
-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
-```
-
-The public CLI does not require private service credentials or an external
-request before local commands run.
-
-Support: suporte@otimitare.online
+# Installation And First Use
+
+Sema is installed and used as a local CLI.
+
+```bash
+npm install -g @semacode/cli
+codex plugin marketplace add gerlanss/Sema
+codex plugin add sema@sema
+```
+
+Open a new Codex task in the target repository so the newly installed `$sema`
+skill is loaded, then ask it to initialize Sema. Existing tasks do not refresh
+their skill catalog. After bootstrap, `AGENTS.md` becomes the automatic protocol
+for subsequent tasks.
+
+Then verify the local engine:
+
+```bash
+sema --version
+sema resumo
+```
+
+The CLI is ready when `sema --version` succeeds. No Sema login, user
+authorization, activation key, product-license check, token, credits, billing
+service, or control panel is involved.
+
+The Codex skill is required for first contact with a project that does not yet
+have Sema. It only bootstraps the local CLI and generates the repository's
+`AGENTS.md`; that file becomes the automatic workspace protocol afterward.
+Plugin installation is explicit and does not happen from npm lifecycle scripts.
+
+## First Project
+
+```bash
+sema iniciar --template base
+sema validar contratos/*.sema --json
+sema resumo
+```
+
+`sema iniciar` preserves existing project files and refuses symlink or junction
+escapes. The bootstrap skill never uses `--force`; explicit overwrite remains a
+human decision.
+
+## Existing Project
+
+```bash
+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
+```
+
+The public CLI does not require private service credentials or an external
+request before local commands run.
+
+Support: suporte@otimitare.online

package/docs/i18n.md

@@ -1,15 +1,15 @@
-# Language And Identifiers
-
-Public Sema documentation is English.
-
-Do not translate commands, file paths, package names, endpoint paths, environment
-variable names, code symbols, DSL keywords, or brand names.
-
-Examples:
-
-- Keep `sema validar`, not an English paraphrase.
-- Keep `.sema`, `task`, `input`, `output`, `rules`, `effects`, and `guarantees`.
-- Keep package names such as `@semacode/cli`.
-
-Human-facing prose should be clear English. Contract DSL can keep its own
-keywords and domain identifiers.
+# Language And Identifiers
+
+Public Sema documentation is English.
+
+Do not translate commands, file paths, package names, endpoint paths, environment
+variable names, code symbols, DSL keywords, or brand names.
+
+Examples:
+
+- Keep `sema validar`, not an English paraphrase.
+- Keep `.sema`, `task`, `input`, `output`, `rules`, `effects`, and `guarantees`.
+- Keep package names such as `@semacode/cli`.
+
+Human-facing prose should be clear English. Contract DSL can keep its own
+keywords and domain identifiers.