@semacode/cli 3.8.1 → 3.8.2

package/docs/drift-cache.md

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

package/docs/getting-started.md

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

package/docs/repositories.md

@@ -1,60 +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 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
+# Repository Boundary
+
+The public Sema repository should contain only the local-first multi-agent 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. Proven compatibility with Claude, Codex, zCode (GLM) and Kimi is Sema's 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.com

package/docs/rollback.md

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