oxe-cc 1.4.0 → 1.5.0

package/QUICKSTART.md

@@ -0,0 +1,99 @@
+# OXE — Primeiros 15 Minutos
+
+> Leitura: ~5 min. Você sai daqui com o projeto configurado e o primeiro ciclo rodando.
+
+---
+
+## 1. Instalar
+
+```bash
+npx oxe-cc@latest
+```
+
+Responda as perguntas do wizard (IDE, perfil, workstream). O OXE cria `.oxe/` no projeto com STATE.md, config.json e os workflows.
+
+Verifique:
+
+```bash
+npx oxe-cc doctor
+```
+
+Deve mostrar `✓ Pronto` para Node, workflows e estrutura base. Se aparecer algum `⚠`, siga o conselho na linha.
+
+---
+
+## 2. Primeiro ciclo (modo padrão)
+
+Execute na sua IDE (Cursor, Copilot, Claude Code, etc.):
+
+```
+/oxe
+```
+
+O router lê STATE.md e sugere exatamente um próximo passo. Siga a recomendação.
+
+**Sequência mínima completa:**
+
+```
+/oxe        → descobre onde você está
+/oxe-scan   → mapeia o codebase em .oxe/codebase/
+/oxe-spec   → gera SPEC.md com critérios de aceite
+/oxe-plan   → gera PLAN.md com ondas e tarefas
+/oxe-execute → implementa a onda atual
+/oxe-verify  → valida os critérios do SPEC
+```
+
+Para uma tarefa pequena (S/M), use o modo rápido:
+
+```
+/oxe-quick  → spec + plan + execute + verify em uma sessão
+```
+
+---
+
+## 3. Quando usar runtime-first
+
+Se o projeto tem o runtime compilado (`lib/runtime/index.js`), os comandos enterprise ficam disponíveis:
+
+```bash
+# Verificação formal com manifesto de evidências
+npx oxe-cc runtime verify --dir .
+
+# Listar gates pendentes
+npx oxe-cc runtime gates list --dir .
+
+# Promover run verificada para PR draft
+npx oxe-cc runtime promote --dir . --target pr_draft
+
+# Recuperar run pausada ou interrompida
+npx oxe-cc runtime recover --dir . --run-id <id>
+```
+
+Se o runtime não estiver compilado, os comandos OXE continuam funcionando no modo legado — sem perda de UX.
+
+---
+
+## 4. Validação dos 5 minutos
+
+Após o primeiro ciclo completo, estas 5 coisas devem estar verdes:
+
+| # | O que checar | Como |
+|---|-------------|------|
+| 1 | STATE.md mostra `verify_complete` ou `plan_complete` | `cat .oxe/STATE.md` |
+| 2 | Nenhum `ERROR` em `oxe-cc doctor` | `npx oxe-cc doctor` |
+| 3 | `oxe-cc status` retorna próximo passo claro | `npx oxe-cc status` |
+| 4 | SPEC.md tem critérios de aceite preenchidos | `cat .oxe/SPEC.md` |
+| 5 | VERIFY.md existe (se ciclo completo) | `cat .oxe/VERIFY.md` |
+
+Se algum falhar, rode `/oxe` — o router vai diagnosticar e sugerir a ação correta.
+
+---
+
+## 5. Próximos passos
+
+- **Para times** → [`docs/TEAM-ADOPTION.md`](docs/TEAM-ADOPTION.md)
+- **Por papel (executor/reviewer/operador)** → [`docs/ROLES.md`](docs/ROLES.md)
+- **Exemplo completo reproduzível** → [`docs/WALKTHROUGH.md`](docs/WALKTHROUGH.md)
+- **Incidentes e gates** → [`docs/INCIDENT-PLAYBOOK.md`](docs/INCIDENT-PLAYBOOK.md)
+- **Suporte por runtime** → [`docs/RUNTIME-SMOKE-MATRIX.md`](docs/RUNTIME-SMOKE-MATRIX.md)
+- **Referência completa** → [`README.md`](README.md)

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-**Versão:** `1.4.0` · [package.json](package.json)
+**Versão:** `1.5.0` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 
@@ -25,10 +25,10 @@ npx oxe-cc@latest
 
 OXE é o **Framework OXE — Orchestrated eXperience Engineering**: um framework de desenvolvimento assistido por IA orientado por artefatos, contexto em disco e execução verificável. Funciona identicamente em Cursor, GitHub Copilot, Claude Code, Gemini CLI, Windsurf e qualquer outro agente — o estado fica em `.oxe/` no seu projeto, não preso a nenhuma IDE.
 
-No momento atual, o OXE opera em duas camadas complementares já prontas para publicação:
+No momento atual, o OXE opera em duas camadas complementares já prontas para publicação:
 
 - **framework de método** — `spec -> plan -> execute -> verify`, sessões, workstreams, lessons loop e contratos de raciocínio multi-runtime
-- **runtime enterprise** — `ExecutionGraph`, `canonical_state`, context packs, evidence store, verification manifest, gates, policy, promotion, recovery e auditoria operacional
+- **runtime enterprise** — `ExecutionGraph`, `canonical_state`, context packs, evidence store, verification manifest, gates, policy, promotion, recovery e auditoria operacional
 
 Ele se apoia em três princípios:
 
@@ -58,7 +58,7 @@ Essas regras vivem no núcleo canónico em `oxe/workflows/references/reasoning-*
 
 ## Momento atual do produto
 
-O OXE já não é só um conjunto de prompts e markdowns. Hoje ele combina:
+O OXE já não é só um conjunto de prompts e markdowns. Hoje ele combina:
 
 - **artefatos canónicos em `.oxe/`** para continuidade entre sessões, IDEs e agentes
 - **Context Engine V2** para seleção e compressão determinística de contexto
@@ -72,16 +72,32 @@ Em termos práticos, o estado operacional real agora passa por:
 - `.oxe/runs/<run_id>.json`
 - `.oxe/runs/<run_id>/verification-manifest.json`
 - `.oxe/runs/<run_id>/residual-risk-ledger.json`
-- `.oxe/runs/<run_id>/evidence-coverage.json`
-- `.oxe/execution/GATES.json`
-- `OXE-EVENTS.ndjson`
-
-Contrato estável desta release:
-
-- `execute` e `verify` são `runtime-first` quando `oxe-cc runtime` está disponível
-- `status`, `doctor`, dashboard e CLI de runtime leem o mesmo estado canónico
-- `multi-agent` é GA apenas com isolamento real (`git_worktree`); `inplace` não é backend válido para coordenação paralela
-- `pr_draft` é o alvo remoto estável de promotion nesta publicação
+- `.oxe/runs/<run_id>/evidence-coverage.json`
+- `.oxe/execution/GATES.json`
+- `OXE-EVENTS.ndjson`
+
+Contrato estável desta release:
+
+- `execute` e `verify` são `runtime-first` quando `oxe-cc runtime` está disponível
+- `status`, `doctor`, dashboard e CLI de runtime leem o mesmo estado canónico
+- `multi-agent` é GA apenas com isolamento real (`git_worktree`); `inplace` não é backend válido para coordenação paralela
+- `pr_draft` é o alvo remoto estável de promotion nesta publicação
+
+→ [Guia por papel](docs/ROLES.md) — executor, reviewer, operador de gate, mantenedor do pacote
+
+---
+
+## Para times
+
+| Recurso | Link |
+|---------|------|
+| Primeiros 15 minutos | [QUICKSTART.md](QUICKSTART.md) |
+| Guia por papel (executor / reviewer / operador) | [docs/ROLES.md](docs/ROLES.md) |
+| Fluxo recomendado para times | [docs/TEAM-ADOPTION.md](docs/TEAM-ADOPTION.md) |
+| Exemplo completo reproduzível | [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) |
+| Incidentes e gates | [docs/INCIDENT-PLAYBOOK.md](docs/INCIDENT-PLAYBOOK.md) |
+| Suporte por runtime (Cursor, Copilot, Claude Code…) | [docs/RUNTIME-SMOKE-MATRIX.md](docs/RUNTIME-SMOKE-MATRIX.md) |
+| Release readiness e publicação | [docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md) |
 
 ---
 
@@ -387,25 +403,25 @@ Implementar: o mínimo para passar o Verificar
 Complexidade: S | M | L | XL
 ```
 
-Tarefas `XL` bloqueiam o gate sem sub-tarefas ou justificativa. `/oxe-obs` propaga automaticamente constraints para os R-IDs e Tns afetados.
-
-#### Iteração correta do plano
-
-Se o usuário quiser chamar `/oxe-plan` várias vezes até ficar satisfeito, o fluxo esperado é este:
-
-- **Mesmo escopo e mesma `SPEC.md`, mas quer refinar tarefas, ondas, dependências, riscos ou validação**: usar `/oxe-plan --replan`
-- **Mudou a estratégia técnica**: voltar para `/oxe-discuss` e depois `/oxe-plan --replan`
-- **Mudou requisitos, critérios, prioridades ou aceite**: voltar para `/oxe-spec` e depois `/oxe-plan`
-
-Regra prática:
-
-- `spec` muda o **que** será entregue
-- `discuss` muda o **como** ou o **porquê** da estratégia
-- `plan --replan` muda **como quebrar e executar** a mesma entrega
-
-Se já existir `PLAN.md` no escopo atual e o usuário chamar `/oxe-plan` de novo sem alterar a spec, o OXE deve tratar isso como **replan implícito**, preservando a seção **Replanejamento** e o histórico útil do plano anterior.
-
-### Runtime operacional e checkpoints
+Tarefas `XL` bloqueiam o gate sem sub-tarefas ou justificativa. `/oxe-obs` propaga automaticamente constraints para os R-IDs e Tns afetados.
+
+#### Iteração correta do plano
+
+Se o usuário quiser chamar `/oxe-plan` várias vezes até ficar satisfeito, o fluxo esperado é este:
+
+- **Mesmo escopo e mesma `SPEC.md`, mas quer refinar tarefas, ondas, dependências, riscos ou validação**: usar `/oxe-plan --replan`
+- **Mudou a estratégia técnica**: voltar para `/oxe-discuss` e depois `/oxe-plan --replan`
+- **Mudou requisitos, critérios, prioridades ou aceite**: voltar para `/oxe-spec` e depois `/oxe-plan`
+
+Regra prática:
+
+- `spec` muda o **que** será entregue
+- `discuss` muda o **como** ou o **porquê** da estratégia
+- `plan --replan` muda **como quebrar e executar** a mesma entrega
+
+Se já existir `PLAN.md` no escopo atual e o usuário chamar `/oxe-plan` de novo sem alterar a spec, o OXE deve tratar isso como **replan implícito**, preservando a seção **Replanejamento** e o histórico útil do plano anterior.
+
+### Runtime operacional e checkpoints
 
 - `PLAN.md` continua estratégico.
 - `EXECUTION-RUNTIME.md` continua como superfície humana de operação, mas o estado canónico vive no runtime.
@@ -420,36 +436,43 @@ Se já existir `PLAN.md` no escopo atual e o usuário chamar `/oxe-plan` de novo
 
 O caminho padrão de inspeção é CLI-first:
 
-```bash
-oxe-cc status --full    # health + coverage matrix + readiness gate no terminal
-oxe-cc runtime status   # run ativo, cursor, onda atual
-oxe-cc runtime verify   # verify enterprise: suite + evidence + manifest + risk ledger
-oxe-cc runtime gates list
-oxe-cc runtime agents --json
-oxe-cc runtime promote --target pr_draft
-```
-
-O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano, health lógico, contexto, gates pendentes, verify enterprise, quotas, audit trail, recovery state, multi-agent e promotion state.
+```bash
+oxe-cc status --full    # health + coverage matrix + readiness gate no terminal
+oxe-cc runtime status   # run ativo, cursor, onda atual
+oxe-cc runtime verify   # verify enterprise: suite + evidence + manifest + risk ledger
+oxe-cc runtime gates list
+oxe-cc runtime agents --json
+oxe-cc runtime promote --target pr_draft
+```
+
+O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano, health lógico, contexto, gates pendentes, verify enterprise, quotas, audit trail, recovery state, multi-agent e promotion state.
 
 ### Dashboard web — opt-in para revisões de equipe
 
-- `oxe-cc dashboard` sobe uma interface web local em `localhost` para revisar o plano antes da execução — indicado para apresentações, operação de gates e revisões em equipe, não para substituir o terminal no dia a dia.
-- A UI lê os artefatos OXE reais; ela não substitui `PLAN.md`, `STATE.md` ou `VERIFY.md`.
-- A visão inclui ciclo principal, mapa de artefatos, active run, trace log, trilha de ondas, handoffs, checkpoints, agentes, evidências, gates, quotas, audit summary, recovery state e promotion state sem criar uma segunda fonte de verdade.
-- `oxe-cc runtime <start|pause|resume|replay|status|compile|verify|project|ci|promote|recover|gates|agents>` controla explicitamente `ACTIVE-RUN.json`, `runs/`, `GATES.json`, manifests de verify, artefatos de recovery, `multi-agent-state.json` e `OXE-EVENTS.ndjson` no mesmo contrato consumido pelo dashboard.
-- A aprovação visual persiste em `plan_review_status` no `STATE.md`, em `PLAN-REVIEW.md` e em `plan-review-comments.json`.
-
-### Critérios de publicação desta release
-
-O pacote está pronto para uma publicação robusta quando estes sinais estiverem verdes no repositório da release:
-
+- `oxe-cc dashboard` sobe uma interface web local em `localhost` para revisar o plano antes da execução — indicado para apresentações, operação de gates e revisões em equipe, não para substituir o terminal no dia a dia.
+- A UI lê os artefatos OXE reais; ela não substitui `PLAN.md`, `STATE.md` ou `VERIFY.md`.
+- A visão inclui ciclo principal, mapa de artefatos, active run, trace log, trilha de ondas, handoffs, checkpoints, agentes, evidências, gates, quotas, audit summary, recovery state e promotion state sem criar uma segunda fonte de verdade.
+- `oxe-cc runtime <start|pause|resume|replay|status|compile|verify|project|ci|promote|recover|gates|agents>` controla explicitamente `ACTIVE-RUN.json`, `runs/`, `GATES.json`, manifests de verify, artefatos de recovery, `multi-agent-state.json` e `OXE-EVENTS.ndjson` no mesmo contrato consumido pelo dashboard.
+- A aprovação visual persiste em `plan_review_status` no `STATE.md`, em `PLAN-REVIEW.md` e em `plan-review-comments.json`.
+
+### Critérios de publicação desta release
+
+O pacote está pronto para uma publicação robusta quando estes sinais estiverem verdes no repositório da release:
+
 - `npm test`
 - `npm run scan:assets`
 - `npm run build:vscode-ext`
-- `node bin/oxe-cc.js doctor`
+- `node bin/oxe-cc.js doctor --release --write-manifest`
 - `node bin/oxe-cc.js status --full`
 
-Não há outro bloqueador funcional do plano runtime core para esta publicação. O que sobra depois dela é evolução de ergonomia e expansão de targets, não correção estrutural do contrato atual.
+Artefatos obrigatórios desta fase:
+
+- `.oxe/release/release-manifest.json`
+- `.oxe/release/runtime-smoke-report.json`
+- `.oxe/release/recovery-fixture-report.json`
+- `.oxe/release/multi-agent-soak-report.json`
+
+Não há outro bloqueador funcional do plano runtime core para esta publicação. O que sobra depois dela é evolução de ergonomia e expansão de targets, não correção estrutural do contrato atual.
 
 ### `/oxe-retro` — loop de aprendizado
 
@@ -544,22 +567,23 @@ node bin/oxe-cc.js --help
 | Comando | O que faz |
 |---------|-----------|
 | `oxe-cc` / `oxe-cc install` | Instala workflows e integrações |
-| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano, saúde lógica (`healthy` \| `warning` \| `broken`), drift semântico multi-runtime e workflows sem contrato no registry |
+| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano, saúde lógica (`healthy` \| `warning` \| `broken`), drift semântico multi-runtime e workflows sem contrato no registry |
+| `oxe-cc doctor --release --write-manifest` | Gate de publicação: valida versões, topo do `CHANGELOG`, runtime compilado, wrapper sync e relatórios obrigatórios; persiste `release-manifest.json` |
 | `oxe-cc status` | Próximo passo sugerido + saúde lógica do fluxo |
 | `oxe-cc status --full` | Coverage matrix + readiness gate + active run no terminal (ANSI) |
-| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality`, `semanticsDrift`, `verificationSummary`, `residualRiskSummary`, `evidenceCoverage`, `pendingGates`, `policyDecisionSummary`, `quotaSummary`, `auditSummary`, `promotionSummary`, `runtimeMode`, `fallbackMode`, `gateQueue`, `policyCoverage`, `promotionReadiness`, `recoveryState`, `multiAgent` e `providerCatalog` |
+| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality`, `semanticsDrift`, `verificationSummary`, `residualRiskSummary`, `evidenceCoverage`, `pendingGates`, `policyDecisionSummary`, `quotaSummary`, `auditSummary`, `promotionSummary`, `runtimeMode`, `fallbackMode`, `gateQueue`, `policyCoverage`, `promotionReadiness`, `recoveryState`, `multiAgent` e `providerCatalog` |
 | `oxe-cc context build [--workflow <slug>] [--tier <minimal\|standard\|full>]` | Gera context pack(s) em `.oxe/context/packs/` — seleção determinística de artefatos por contrato de workflow |
 | `oxe-cc context inspect [--workflow <slug>]` | Inspeciona um context pack existente ou resolve sob demanda (sem escrita); útil para diagnóstico antes de iniciar um passo |
 | `oxe-cc update` | Atualiza workflows para a versão mais recente |
 | `oxe-cc init-oxe` | Bootstrap do `.oxe/` (STATE, config, codebase/, context/, install/) |
 | `oxe-cc dashboard` | Interface web local para revisão, comentários e aprovação do plano (inclui aba Context com quality score e drift semântico) |
-| `oxe-cc runtime <status\|start\|pause\|resume\|replay\|compile\|verify\|project\|ci\|promote\|recover\|gates\|agents>` | Controla o runtime enterprise: run ativo, grafo compilado, verify executável, gates, promoção remota, recovery, multi-agent e tracing operacional |
-| `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write] [--json]` | Timeline operacional estruturada; `--write` gera `REPLAY-SESSION.md` com divergências e deltas |
-| `oxe-cc runtime verify` | Executa `compileVerification + executeSuite + EvidenceStore + manifest + residual risk + projections` para a run ativa |
-| `oxe-cc runtime gates <list\|show\|resolve>` | Lista, inspeciona e resolve gates operacionais persistidos; `list` aceita `--run`, `--status`, `--scope`, `--task` e `--json` |
-| `oxe-cc runtime agents status [--run <id>] [--json]` | Inspeciona ownership, handoffs, heartbeats, timeouts e failover multi-agent |
-| `oxe-cc runtime promote --target pr_draft` | Promoção remota explícita, separada de `ship`, governada por verify, gates, risk e coverage; `pr_draft` é o alvo estável desta release |
-| `oxe-cc runtime recover [--run <id>] [--json]` | Reidrata journal, gates, policy decisions, evidence refs, verification artifacts e estado canónico da run |
+| `oxe-cc runtime <status\|start\|pause\|resume\|replay\|compile\|verify\|project\|ci\|promote\|recover\|gates\|agents>` | Controla o runtime enterprise: run ativo, grafo compilado, verify executável, gates, promoção remota, recovery, multi-agent e tracing operacional |
+| `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write] [--json]` | Timeline operacional estruturada; `--write` gera `REPLAY-SESSION.md` com divergências e deltas |
+| `oxe-cc runtime verify` | Executa `compileVerification + executeSuite + EvidenceStore + manifest + residual risk + projections` para a run ativa |
+| `oxe-cc runtime gates <list\|show\|resolve>` | Lista, inspeciona e resolve gates operacionais persistidos; `list` aceita `--run`, `--status`, `--scope`, `--task` e `--json` |
+| `oxe-cc runtime agents status [--run <id>] [--json]` | Inspeciona ownership, handoffs, heartbeats, timeouts e failover multi-agent |
+| `oxe-cc runtime promote --target pr_draft` | Promoção remota explícita, separada de `ship`, governada por verify, gates, risk e coverage; `pr_draft` é o alvo estável desta release |
+| `oxe-cc runtime recover [--run <id>] [--json]` | Reidrata journal, gates, policy decisions, evidence refs, verification artifacts e estado canónico da run |
 | `oxe-cc capabilities <list\|install\|remove\|update>` | Mantém o catálogo nativo de capabilities em `.oxe/` |
 | `oxe-cc plugins <list\|install\|remove>` | Gerencia plugins de lifecycle; `install npm:<pkg>` instala em `.oxe/plugins/_npm/` |
 | `oxe-cc uninstall` | Remove integrações OXE do HOME e do repo |
@@ -644,4 +668,4 @@ TypeScript: [`lib/sdk/index.d.ts`](lib/sdk/index.d.ts) · Docs: [`lib/sdk/README
 
 ## Licença
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/bin/lib/oxe-agent-install.cjs

@@ -13,8 +13,13 @@ const path = require('path');
 const os = require('os');
 const runtimeSemantics = require('./oxe-runtime-semantics.cjs');
 
-const OXE_MANAGED_HTML = '<!-- oxe-cc managed -->';
-const OXE_MANAGED_TOML = '# oxe-cc managed';
+const OXE_MANAGED_HTML = '<!-- oxe-cc managed -->';
+const OXE_MANAGED_TOML = '# oxe-cc managed';
+
+/** @param {string} name */
+function isOxeCommandMarkdownName(name) {
+  return (name === 'oxe.md' || name.startsWith('oxe-')) && name.endsWith('.md');
+}
 
 function expandTilde(p) {
   if (typeof p !== 'string') return p;
@@ -223,13 +228,13 @@ function installSkillTreeFromCursorCommands(cCmdSrc, skillsRoot, opts, pathRewri
  * Copia .md dos comandos Cursor para pastas OpenCode (markdown nativo).
  * @param {AgentInstallPaths} paths
  */
-function installOpenCodeCommands(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
-  if (!fs.existsSync(cCmdSrc)) return;
-  for (const destDir of paths.opencodeCommandDirs) {
-    for (const name of fs.readdirSync(cCmdSrc)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const src = path.join(cCmdSrc, name);
-      const dest = path.join(destDir, name);
+function installOpenCodeCommands(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
+  if (!fs.existsSync(cCmdSrc)) return;
+  for (const destDir of paths.opencodeCommandDirs) {
+    for (const name of fs.readdirSync(cCmdSrc)) {
+      if (!isOxeCommandMarkdownName(name)) continue;
+      const src = path.join(cCmdSrc, name);
+      const dest = path.join(destDir, name);
       if (opts.dryRun) {
         if (logWrite) logWrite(`opencode ${src} → ${dest}`);
         continue;
@@ -345,13 +350,13 @@ function installWindsurfGlobalWorkflows(cCmdSrc, paths, opts, pathRewriteNested,
  * Codex: prompts em ~/.codex/prompts ou ./.codex/prompts (local).
  * @param {AgentInstallPaths} paths
  */
-function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
-  if (!fs.existsSync(cCmdSrc)) return;
-  const destDir = paths.codexPromptsDir;
-  for (const name of fs.readdirSync(cCmdSrc)) {
-    if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-    const src = path.join(cCmdSrc, name);
-    const dest = path.join(destDir, name);
+function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
+  if (!fs.existsSync(cCmdSrc)) return;
+  const destDir = paths.codexPromptsDir;
+  for (const name of fs.readdirSync(cCmdSrc)) {
+    if (!isOxeCommandMarkdownName(name)) continue;
+    const src = path.join(cCmdSrc, name);
+    const dest = path.join(destDir, name);
     if (opts.dryRun) {
       if (logWrite) logWrite(`codex prompts ${src} → ${dest}`);
       continue;
@@ -385,8 +390,10 @@ function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido
  * @param {{ dryRun: boolean }} u
  * @param {AgentInstallPaths} [paths] omissão = instalação global (HOME)
  */
-function cleanupMarkedUnifiedArtifacts(u, paths) {
-  const p = paths || buildAgentInstallPaths(true, process.cwd());
+function cleanupMarkedUnifiedArtifacts(u, paths) {
+  const p = paths || buildAgentInstallPaths(true, process.cwd());
+  const targets = u && typeof u === 'object' && u.targets && typeof u.targets === 'object' ? u.targets : null;
+  const shouldClean = (name) => !targets || targets[name] !== false;
 
   const unlinkQuiet = (filePath) => {
     if (!fs.existsSync(filePath)) return;
@@ -416,92 +423,104 @@ function cleanupMarkedUnifiedArtifacts(u, paths) {
     }
   };
 
-  for (const dir of p.opencodeCommandDirs) {
-    if (!fs.existsSync(dir)) continue;
-    for (const name of fs.readdirSync(dir)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const filePath = path.join(dir, name);
-      let txt = '';
-      try {
-        txt = fs.readFileSync(filePath, 'utf8');
-      } catch {
-        continue;
-      }
-      if (txt.includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-    }
-  }
-
-  const gBase = p.geminiCommandsBase;
-  const oxeToml = path.join(gBase, 'oxe.toml');
-  if (fs.existsSync(oxeToml)) {
-    try {
-      if (fs.readFileSync(oxeToml, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(oxeToml);
-    } catch {
-      /* ignore */
-    }
-  }
-  const oxeSub = path.join(gBase, 'oxe');
-  if (fs.existsSync(oxeSub)) {
-    for (const name of fs.readdirSync(oxeSub)) {
-      if (!name.endsWith('.toml')) continue;
-      const filePath = path.join(oxeSub, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-    try {
-      if (!u.dryRun && fs.existsSync(oxeSub) && fs.readdirSync(oxeSub).length === 0) fs.rmdirSync(oxeSub);
-    } catch {
-      /* ignore */
-    }
-  }
-
-  const wfDir = p.windsurfWorkflowsDir;
-  if (fs.existsSync(wfDir)) {
-    for (const name of fs.readdirSync(wfDir)) {
-      if (name !== 'oxe.md' && !(name.startsWith('oxe-') && name.endsWith('.md'))) continue;
-      const filePath = path.join(wfDir, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
-  const cpDir = p.codexPromptsDir;
-  if (fs.existsSync(cpDir)) {
-    for (const name of fs.readdirSync(cpDir)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const filePath = path.join(cpDir, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
-  const agRoot = p.antigravitySkillsRoot;
-  if (fs.existsSync(agRoot)) {
-    for (const name of fs.readdirSync(agRoot, { withFileTypes: true })) {
-      if (!name.isDirectory()) continue;
-      if (!/^oxe($|-)/.test(name.name)) continue;
-      rmDirIfOxeSkill(path.join(agRoot, name.name));
-    }
-  }
-
-  const cxRoot = p.codexAgentsSkillsRoot;
-  if (fs.existsSync(cxRoot)) {
-    for (const name of fs.readdirSync(cxRoot, { withFileTypes: true })) {
-      if (!name.isDirectory()) continue;
-      if (!/^oxe($|-)/.test(name.name)) continue;
-      rmDirIfOxeSkill(path.join(cxRoot, name.name));
-    }
-  }
-}
+  if (shouldClean('opencode')) {
+    for (const dir of p.opencodeCommandDirs) {
+      if (!fs.existsSync(dir)) continue;
+      for (const name of fs.readdirSync(dir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(dir, name);
+        let txt = '';
+        try {
+          txt = fs.readFileSync(filePath, 'utf8');
+        } catch {
+          continue;
+        }
+        if (txt.includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+      }
+    }
+  }
+
+  if (shouldClean('gemini')) {
+    const gBase = p.geminiCommandsBase;
+    const oxeToml = path.join(gBase, 'oxe.toml');
+    if (fs.existsSync(oxeToml)) {
+      try {
+        if (fs.readFileSync(oxeToml, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(oxeToml);
+      } catch {
+        /* ignore */
+      }
+    }
+    const oxeSub = path.join(gBase, 'oxe');
+    if (fs.existsSync(oxeSub)) {
+      for (const name of fs.readdirSync(oxeSub)) {
+        if (!name.endsWith('.toml')) continue;
+        const filePath = path.join(oxeSub, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+      try {
+        if (!u.dryRun && fs.existsSync(oxeSub) && fs.readdirSync(oxeSub).length === 0) fs.rmdirSync(oxeSub);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  if (shouldClean('windsurf')) {
+    const wfDir = p.windsurfWorkflowsDir;
+    if (fs.existsSync(wfDir)) {
+      for (const name of fs.readdirSync(wfDir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(wfDir, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+
+  if (shouldClean('codex')) {
+    const cpDir = p.codexPromptsDir;
+    if (fs.existsSync(cpDir)) {
+      for (const name of fs.readdirSync(cpDir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(cpDir, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+
+  if (shouldClean('antigravity')) {
+    const agRoot = p.antigravitySkillsRoot;
+    if (fs.existsSync(agRoot)) {
+      for (const name of fs.readdirSync(agRoot, { withFileTypes: true })) {
+        if (!name.isDirectory()) continue;
+        if (!/^oxe($|-)/.test(name.name)) continue;
+        rmDirIfOxeSkill(path.join(agRoot, name.name));
+      }
+    }
+  }
+
+  if (shouldClean('codex')) {
+    const cxRoot = p.codexAgentsSkillsRoot;
+    if (fs.existsSync(cxRoot)) {
+      for (const name of fs.readdirSync(cxRoot, { withFileTypes: true })) {
+        if (!name.isDirectory()) continue;
+        if (!/^oxe($|-)/.test(name.name)) continue;
+        rmDirIfOxeSkill(path.join(cxRoot, name.name));
+      }
+    }
+  }
+}
 
 module.exports = {
   OXE_MANAGED_HTML,
@@ -520,6 +539,7 @@ module.exports = {
   geminiUserDir,
   codexAgentsSkillsRoot,
   codexPromptsDir,
-  antigravitySkillsRoot,
-  cleanupMarkedUnifiedArtifacts,
-};
+  antigravitySkillsRoot,
+  isOxeCommandMarkdownName,
+  cleanupMarkedUnifiedArtifacts,
+};

package/bin/lib/oxe-install-resolve.cjs

@@ -36,6 +36,16 @@ function resolveInstallOptionsFromConfig(projectRoot, optsIn) {
     opts.explicitScope = true;
   }
 
+  if (!opts.explicitIdeScope && !opts.oxeOnly && typeof inst.ide_scope === 'string') {
+    if (inst.ide_scope === 'local') {
+      opts.ideLocal = true;
+      opts.explicitIdeScope = true;
+    } else if (inst.ide_scope === 'global') {
+      opts.ideLocal = false;
+      opts.explicitIdeScope = true;
+    }
+  }
+
   if (!opts.oxeOnly && inst.vscode === true) {
     opts.vscode = true;
   }