@semacode/cli 2.3.0 → 3.0.0

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,82 @@
-# 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
+sema skill status --json
+```
+
+The global package creates an absolute launcher under `~/.sema/bin`, installs
+the bundled skill in `~/.agents/skills/sema`, and mirrors it to
+`~/.claude/skills/sema` only when Claude is already present. Open a new task so
+the updated skill catalog is loaded. Installing or updating the global CLI does
+not authorize Sema adoption in the current workspace: informational requests
+stay read-only, and implementation requires explicit adoption authorization.
+After an authorized bootstrap, `AGENTS.md` becomes the automatic protocol for
+subsequent tasks.
+
+Then verify the local engine:
+
+```bash
+sema --version
+sema resumo --drift none
+```
+
+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 skill handles 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. The npm lifecycle does
+not install plugins or touch plugin caches.
+
+If the install used `--ignore-scripts`, run `sema skill sync --json`. If the
+shell cannot resolve the npm shim, use `~/.sema/bin/sema` on macOS or Linux. On
+Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe` resolves
+`sema.cmd`, and the robust PowerShell fallback is:
+
+```powershell
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+```
+
+The managed fallback contains absolute Node.js and CLI paths and does not
+depend on `PATH`.
+
+## First Project
+
+```bash
+sema descobrir explicar flow.project-adoption --json
+sema iniciar --template base
+sema sync-codex --json
+sema validar contratos/*.sema --json
+sema resumo --drift none
+```
+
+Run this sequence only after explicit project-adoption authorization. The
+`sema iniciar` command 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 --drift none
+sema docs-impacto --intencao "describe the change" --json
+sema inspecionar contratos/example.sema --drift none --json
+sema drift contratos/example.sema --escopo modulo --cache fresh --json
+sema impacto contratos/example.sema --alvo sema.example.target --mudanca "describe the change" --json
+```
+
+`sema resumo` and `sema inspecionar` default to `--drift none`: they skip drift
+analysis and report drift-derived evidence as `null`, meaning not evaluated.
+Direct `sema drift` defaults to `--cache fresh`; its `--cache none` mode still
+runs the analysis, but without reading or writing persistent cache. See
+[Drift Cache And Query Evidence](./drift-cache.md) for the complete mode table,
+external cache locations, and recovery behavior.
+
+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.

package/docs/repositories.md

@@ -1,43 +1,60 @@
-# Repository Boundary
-
-The public Sema repository should contain only the Codex-native local CLI, the
-first-contact Codex skill, runtime packages, examples, tests that run locally,
-and English documentation.
-
-## Public
-
-- local CLI source
-- contract parser and validators
-- local drift and impact tooling
-- local code generators
-- examples
-- English docs
-- local package scripts
-- `AGENTS.md` as the official Codex entrypoint
-- the official Sema skill as a thin bootstrap before `AGENTS.md` exists
-- the repo marketplace that installs that skill explicitly
-
-## Not Public
-
-- private or sensitive operational material
-- real credentials, environment files, or secret inventories
-- private project data or generated private artifacts
-- runtime authorization, activation, billing, credit, token, or panel gates
-- product-specific entrypoint files for AI clients other than Codex
-- MCP servers, remote workspace bridges, or duplicated governance inside the
-  bootstrap skill
-
-The CLI must run directly against the local workspace without login, user
-authorization, a product-license check, activation key, credits, token, billing
-service, or control panel.
-
-Sema is an independent product and is not affiliated with or endorsed by
-OpenAI. Codex-native is Sema's official product direction, not an official
-OpenAI program or submission.
-
-## Commercial Use
-
-The public Sema source may not be copied, rebranded, bundled, or replicated for
-commercial resale without written permission from OtimiTare.
-
-Support: suporte@otimitare.online
+# Repository Boundary
+
+The public Sema repository should contain only the Codex-native local CLI, the
+first-contact Codex skill, runtime packages, examples, tests that run locally,
+and English documentation.
+
+## Public
+
+- local CLI source
+- contract parser and validators
+- local drift and impact tooling
+- local code generators
+- examples
+- English docs
+- local package scripts
+- `AGENTS.md` as the official Codex entrypoint
+- the official Sema skill as a thin bootstrap before `AGENTS.md` exists
+- the managed absolute launcher and portable global skill bundled in npm
+- the optional repo marketplace that exposes the same skill namespaced
+
+## Not Public
+
+- private or sensitive operational material
+- real credentials, environment files, or secret inventories
+- private project data or generated private artifacts
+- runtime authorization, activation, billing, credit, token, or panel gates
+- product-specific repository entrypoint files for AI clients other than Codex
+- MCP servers, remote workspace bridges, or duplicated governance inside the
+  bootstrap skill
+
+The portable skill may be synchronized to the canonical user-level
+`.agents/skills` directory and a detected Claude mirror. That does not change
+the workspace boundary: Sema still generates only `AGENTS.md` as the official
+repository protocol and never writes into plugin caches.
+
+The repository has one npm package factory: `npm run cli:empacotar-publica`.
+It assembles a private stage per execution and never materializes examples,
+runtime dependencies, or skills inside `pacotes/cli`. Direct workspace packing
+is intentionally blocked so a second, mutable packaging path cannot drift from
+the public artifact.
+
+The Windows distribution uses `sema.ps1` for PowerShell `PATH` resolution,
+`sema.cmd` for `cmd.exe`, and `sema-managed.ps1` for the PATH-independent
+fallback invoked through the absolute system `powershell.exe`; all remain
+inside the managed `~/.sema/bin` boundary.
+
+The CLI must run directly against the local workspace without login, user
+authorization, a product-license check, activation key, credits, token, billing
+service, or control panel.
+
+Sema is an independent product and is not affiliated with or endorsed by
+OpenAI. Codex-native is Sema's official product direction, not an official
+OpenAI program or submission.
+
+## Commercial Use
+
+The public Sema source may not be copied, rebranded, bundled, or replicated for
+commercial resale without written permission from OtimiTare.
+
+Support: suporte@otimitare.online

package/docs/rollback.md

@@ -1,31 +1,38 @@
-# Rollback Boundary
-
-Public rollback covers both the npm CLI and the separately installed Codex
-bootstrap skill.
-
-For a failed pre-publication candidate:
-
-1. Keep the previous tarball until the new one passes smoke tests.
-2. Revert the plugin source, marketplace manifest, CLI source, and versions to
-   the last known-good commit.
-3. Re-run `npm run release:preparar-publica`.
-
-If a bad commit was already pushed, revert it with a normal Git revert and push
-the corrective commit. Refresh the marketplace and reinstall the skill:
-
-```bash
-codex plugin marketplace upgrade sema
-codex plugin remove sema@sema
-codex plugin add sema@sema
-```
-
-Open a new Codex task before validating the reinstalled skill. Already-open
-tasks keep the plugin/skill catalog they started with.
-
-If a bad npm version was published, do not overwrite it. Publish a corrected
-version and direct users to that version. Verify the final registry/GitHub state
-with `npm run release:verificar-distribuicao`. Do not create a GitHub Release or
-asset as a rollback shortcut while the release contract blocks that surface.
-
-Do not publish private or sensitive operational rollback material in this
-repository.
+# Rollback Boundary
+
+Public rollback covers the npm CLI, managed launcher, bundled global skill, and
+the optional Codex plugin channel.
+
+For a failed pre-publication candidate:
+
+1. Keep the previous tarball until the new one passes smoke tests.
+2. Revert the plugin source, marketplace manifest, CLI source, and versions to
+   the last known-good commit.
+3. Re-run `npm run release:preparar-publica`.
+
+If a bad commit was already pushed, revert it with a normal Git revert and push
+the corrective commit. Install the corrected npm version and resynchronize its
+managed distribution:
+
+```bash
+npm install -g @semacode/cli@<corrected-version>
+sema skill sync --json
+```
+
+The same sequence may install an explicitly selected previous version. The
+installed npm version is authoritative: `sema skill sync --json` aligns the
+runtime, managed launcher, and bundled skill to the version that is actually
+installed. This is synchronization, not a promise to block an intentional
+downgrade.
+
+If the optional plugin channel was also affected, upgrade or reinstall it after
+the corrected commit is public. Open a new task before validating the repaired
+skill; already-open tasks keep the catalog they started with.
+
+If a bad npm version was published, do not overwrite it. Publish a corrected
+version and direct users to that version. Verify the final registry/GitHub state
+with `npm run release:verificar-distribuicao`. Do not create a GitHub Release or
+asset as a rollback shortcut while the release contract blocks that surface.
+
+Do not publish private or sensitive operational rollback material in this
+repository.

package/docs/security.md

@@ -1,32 +1,54 @@
-# Security
-
-The public Sema repository must not contain private or sensitive operational
-material.
-
-Local Sema execution does not need a credential, login, activation key, license
-token, billing token, or control-panel session. Do not introduce one as a
-condition for reading or governing a local workspace.
-
-The official Codex bootstrap skill contains instructions only. It must not
-bundle an MCP server, app connector, remote workspace bridge, credential flow,
-or a second copy of the repository governance that belongs in `AGENTS.md`.
-
-Do not publish:
-
-- real credentials or secret material;
-- private data or internal operational artifacts.
-
-Placeholder examples are allowed:
-
-```bash
-EXAMPLE_KEY=replace-me
-```
-
-If a real credential is exposed in code, docs, logs, screenshots, packages, or
-Git history:
-
-1. Rotate it immediately.
-2. Remove it from the affected artifact.
-3. Rebuild and rescan before publishing.
-
-Official support: suporte@otimitare.online
+# Security
+
+The public Sema repository must not contain private or sensitive operational
+material.
+
+Local Sema execution does not need a credential, login, activation key, license
+token, billing token, or control-panel session. Do not introduce one as a
+condition for reading or governing a local workspace.
+
+The official bootstrap skill contains instructions only. The global npm
+postinstall may atomically update the managed launcher under `~/.sema/bin`, the
+canonical copy under `~/.agents/skills/sema`, and a Claude mirror under
+`~/.claude/skills/sema` when Claude is already detected. It must not scan the
+home recursively, overwrite an unowned destination, follow symlinks or
+junctions, write into a plugin cache, bundle an MCP server, add a credential
+flow, or duplicate the repository governance that belongs in `AGENTS.md`.
+
+Status output exposes symbolic paths such as `$HOME/.sema/bin/sema`,
+`$HOME/.sema/bin/sema.ps1`, `$HOME/.sema/bin/sema.cmd`, and
+`$HOME/.sema/bin/sema-managed.ps1`, never the real home, Node.js executable, or
+package path. On Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe`
+resolves `sema.cmd`, and the fallback runs `sema-managed.ps1` through
+`%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`. A managed receipt
+detects isolated corruption of the launchers and companion; it is integrity
+recovery, not authentication against a hostile process running as the same
+user. Private absolute paths are not published in JSON or logs.
+
+The public-package factory rejects pre-existing symlinks, junctions, and
+reparse points in source, stage, and output chains and revalidates filesystem
+identity around each path-based operation. This is fail-closed hardening, not a
+native sandbox: Node.js does not expose cross-platform `openat`/`linkat`-style
+operations anchored to directory handles, so a hostile process running as the
+same operating-system user can still race a parent-path swap. Do not present
+the private package stage as a security boundary against that attacker.
+
+Do not publish:
+
+- real credentials or secret material;
+- private data or internal operational artifacts.
+
+Placeholder examples are allowed:
+
+```bash
+EXAMPLE_KEY=replace-me
+```
+
+If a real credential is exposed in code, docs, logs, screenshots, packages, or
+Git history:
+
+1. Rotate it immediately.
+2. Remove it from the affected artifact.
+3. Rebuild and rescan before publishing.
+
+Official support: suporte@otimitare.online

package/docs/sistemas-interativos.md

@@ -330,33 +330,33 @@ only that local structural coverage is complete; it deliberately keeps
 editor was inspected, a plug-in existed, a worker accepted a job, a package
 launched, or an external observer attested the result.
 
-## Semantic budget split plan
-
-The current operational facade remains compatible, but three governed artifacts
-have crossed the planning threshold: `operations.ts` has 1,112 lines,
-`sistemas_interativos_operacao.sema` has 304 lines, and the installed-package
-smoke `scripts/testar-pacote-cli-publico.mjs` has 1,009 lines. Before any of
-them reaches its blocking limit, split by responsibility as follows:
-
-- move engine snapshots, semantic diffs, asset provenance, and editor-state
-  observation into `engineObservation.ts`;
-- move queues, locks, budgets, leases, checkpoints, and recovery planning into
-  `jobOrchestration.ts`;
-- move acceptance locks, invalidation, and multimodal claim evidence into
-  `acceptanceEvidence.ts`;
-- keep `operations.ts` as the stable re-export facade while callers migrate;
-- split the contract into `sistemas_interativos_observacao_engine.sema`,
-  `sistemas_interativos_orquestracao_jobs.sema`, and
-  `sistemas_interativos_acceptance_evidencias.sema`, with all three contracts
-  linked to the shared facade and their actual implementation files;
-- split the installed-package smoke into helpers for public-boundary security,
-  Codex bootstrap, content-pipeline compatibility, interactive systems, and
-  generated toolchains, while retaining the current script as the stable
-  orchestrator and preserving one end-to-end isolated installation.
-
-This is a responsibility split, not a numbered-file workaround. Existing
-exports, schema versions, fixtures, digests, and fail-closed behavior must remain
-backward compatible through the migration.
+## Semantic responsibility split
+
+The operational surface is divided by responsibility while preserving
+`operations.ts` as the stable explicit export facade:
+
+- `operationPrimitives.ts` contains shared validation, canonicalization, digest,
+  and evidence primitives;
+- `engineObservation.ts` owns engine snapshots, semantic diffs, asset
+  provenance, and editor-state observation;
+- `jobOrchestration.ts` owns queues, locks, budgets, leases, checkpoints, and
+  recovery planning;
+- `acceptanceEvidence.ts` owns acceptance locks, invalidation, and multimodal
+  claim evidence.
+
+The contracts follow the same boundaries through
+`sistemas_interativos_operacao.sema`,
+`sistemas_interativos_observacao_engine.sema`,
+`sistemas_interativos_orquestracao_jobs.sema`, and
+`sistemas_interativos_acceptance_evidencias.sema`. The installed-package smoke
+also keeps one stable orchestrator and one isolated installation, delegating
+public-boundary security, Codex bootstrap, content-pipeline compatibility,
+interactive systems, and generated toolchains to named helpers under
+`scripts/cli-publico/`.
+
+This is a responsibility split, not a numbered-file workaround. Existing
+exports, schema versions, fixtures, digests, and fail-closed behavior remain
+backward compatible across the facades.
 
 ## Fidelity rules
 

package/docs/support.md

@@ -1,8 +1,8 @@
-# Support
-
-Official Sema support email: suporte@otimitare.online
-
-OtimiTare website: https://otimitare.online
-
-Do not publish private or sensitive support routing material in the public Sema
-repository.
+# Support
+
+Official Sema support email: suporte@otimitare.online
+
+OtimiTare website: https://otimitare.online
+
+Do not publish private or sensitive support routing material in the public Sema
+repository.