oxe-cc 0.3.5 → 0.3.6

package/.cursor/commands/oxe-help.md

@@ -1,13 +1,7 @@
 ---
-description: "Comando OXE"
+description: "OXE — Ajuda (fluxo .oxe/, várias IDEs e CLIs, artefatos)"
 ---
 
----
-name: oxe-help
-agent: agent
-description: OXE — Ajuda (Cursor, Copilot, artefatos)
----
-
-Executa o workflow **OXE help**. Lê e segue **integralmente**:
-
+Executa o workflow **OXE help**. Lê e segue **integralmente**:
+
 `oxe/workflows/help.md` (na raiz do repositório em contexto)

package/.cursor/commands/oxe-next.md

@@ -1,13 +1,7 @@
 ---
-description: "Comando OXE"
+description: "OXE — Próximo passo (lê STATE.md)"
 ---
 
----
-name: oxe-next
-agent: agent
-description: OXE — Próximo passo (lê STATE.md)
----
-
-Executa o workflow **OXE next**. Lê e aplica **integralmente**:
-
+Executa o workflow **OXE next**. Lê e aplica **integralmente**:
+
 `oxe/workflows/next.md` (na raiz do repositório em contexto)

package/.cursor/commands/oxe-plan.md

@@ -1,16 +1,9 @@
 ---
-description: "Comando OXE"
+description: "OXE — Gera .oxe/PLAN.md com verificação por tarefa"
 ---
 
----
-name: oxe-plan
-agent: agent
-description: OXE — Gera .oxe/PLAN.md com verificação por tarefa
-argument-hint: "[opcional: --replan]"
----
-
-Executa o workflow **OXE plan**. Lê e aplica **integralmente**:
-
-`oxe/workflows/plan.md` (na raiz do repositório em contexto)
-
+Executa o workflow **OXE plan**. Lê e aplica **integralmente**:
+
+`oxe/workflows/plan.md` (na raiz do repositório em contexto)
+
 Se o utilizador pedir replanejamento, trata como `--replan` conforme o workflow.

package/.cursor/commands/oxe-review-pr.md

@@ -1,16 +1,9 @@
 ---
-description: "Comando OXE"
+description: "OXE — Revisão de PR (link GitHub, branches ou SHAs)"
 ---
 
----
-name: oxe-review-pr
-agent: agent
-description: OXE — Revisão de PR (link GitHub, branches ou SHAs)
-argument-hint: "URL ou refs: https://github.com/org/repo/pull/10 | main feature/foo"
----
-
-Executa o workflow **OXE review-pr**. Lê e aplica **integralmente**:
-
-`oxe/workflows/review-pr.md` (na raiz do repositório em contexto)
-
+Executa o workflow **OXE review-pr**. Lê e aplica **integralmente**:
+
+`oxe/workflows/review-pr.md` (na raiz do repositório em contexto)
+
 **Exemplos de entrada:** cola o URL da PR (`https://github.com/org/repo/pull/10`, com ou sem `/files`); ou `org/repo#10`; ou **base** e **head** (branches/tags/SHAs). Sem refs, o agente infere (ex.: `main` vs branch atual).

package/.cursor/commands/oxe-scan.md

@@ -1,16 +1,9 @@
 ---
-description: "Comando OXE"
+description: "OXE — Scan do repositório (.oxe/codebase/)"
 ---
 
----
-name: oxe-scan
-agent: agent
-description: OXE — Scan do repositório (.oxe/codebase/)
-argument-hint: "[área opcional, ex. api]"
----
-
-Executa o workflow **OXE scan** no repositório atual. Lê e aplica **integralmente** o ficheiro:
-
-`oxe/workflows/scan.md` (na raiz do repositório em contexto)
-
+Executa o workflow **OXE scan** no repositório atual. Lê e aplica **integralmente** o ficheiro:
+
+`oxe/workflows/scan.md` (na raiz do repositório em contexto)
+
 Usa o texto adicional desta mensagem como foco opcional de área (pastas/módulos).

package/.cursor/commands/oxe-spec.md

@@ -1,16 +1,9 @@
 ---
-description: "Comando OXE"
+description: "OXE — Cria ou atualiza .oxe/SPEC.md"
 ---
 
----
-name: oxe-spec
-agent: agent
-description: OXE — Cria ou atualiza .oxe/SPEC.md
-argument-hint: "[pedido ou contexto da feature]"
----
-
-Executa o workflow **OXE spec**. Lê e aplica **integralmente**:
-
-`oxe/workflows/spec.md` (na raiz do repositório em contexto)
-
+Executa o workflow **OXE spec**. Lê e aplica **integralmente**:
+
+`oxe/workflows/spec.md` (na raiz do repositório em contexto)
+
 Usa o resto desta mensagem e ficheiros anexados como entrada do utilizador.

package/.cursor/commands/oxe-update.md

@@ -0,0 +1,9 @@
+---
+description: "Atualizar oxe-cc no projeto — verificar versão no npm, alinhar ficheiros OXE e validar com doctor"
+---
+
+Executa o workflow **OXE update**. Lê e segue **integralmente**:
+
+`oxe/workflows/update.md` (na raiz do repositório em contexto; ou `.oxe/workflows/update.md` se a instalação aninhou os workflows)
+
+Na prática: na raiz do projeto, correr **`npx oxe-cc update --check`**, depois (se aplicável) **`npx oxe-cc update`** ou **`npx oxe-cc update --if-newer`**, e por fim **`npx oxe-cc doctor`**.

package/.cursor/commands/oxe-verify.md

@@ -1,16 +1,9 @@
 ---
-description: "Comando OXE"
+description: "OXE — Valida implementação (.oxe/VERIFY.md)"
 ---
 
----
-name: oxe-verify
-agent: agent
-description: OXE — Valida implementação (.oxe/VERIFY.md)
-argument-hint: "[opcional: Tn]"
----
-
-Executa o workflow **OXE verify**. Lê e aplica **integralmente**:
-
-`oxe/workflows/verify.md` (na raiz do repositório em contexto)
-
+Executa o workflow **OXE verify**. Lê e aplica **integralmente**:
+
+`oxe/workflows/verify.md` (na raiz do repositório em contexto)
+
 Se o utilizador indicar uma tarefa `Tn`, restringe a verificação a essa tarefa.

package/.github/copilot-instructions.md

@@ -1,6 +1,6 @@
-# OXE — fluxo spec-driven (Cursor + Copilot)
+# OXE — fluxo spec-driven (multi-IDE / multi-CLI)
 
-Este repositório (ou o pacote **oxe-cc** instalado) define o **OXE**: artefatos em **`.oxe/`** na raiz do projeto alvo e workflows em **`oxe/workflows/*.md`** (no pacote) ou **`.oxe/workflows/*.md`** / **`oxe/workflows/*.md`** no projeto, conforme a instalação (layout mínimo vs clássico).
+Este repositório (ou o pacote **oxe-cc** instalado) define o **OXE**: artefatos em **`.oxe/`** na raiz do projeto alvo e workflows em **`oxe/workflows/*.md`** (no pacote) ou **`.oxe/workflows/*.md`** / **`oxe/workflows/*.md`** no projeto, conforme a instalação (layout mínimo vs clássico). O fluxo é **agnóstico de ferramenta**; **Cursor** e **GitHub Copilot** são o caminho padrão mais conhecido, mas o mesmo OXE pode ser instalado em **Claude Code, OpenCode, Gemini CLI, Codex, Windsurf, Antigravity** e outras integrações via `oxe-cc --all-agents` (ou flags por runtime).
 
 ## Quando aplicar
 
@@ -20,11 +20,12 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 | Next | `oxe/workflows/next.md` | “oxe next”, “próximo passo OXE” |
 | Review PR | `oxe/workflows/review-pr.md` | “revisar PR”, link `…/pull/10`, “diff entre branches” *(prompt Copilot: `/oxe-review-pr`)* |
 | Help | `oxe/workflows/help.md` | “oxe help”, “como usar OXE” |
+| Update | `oxe/workflows/update.md` | “oxe update”, “atualizar oxe-cc”, “há versão nova no npm” *(prompt: `/oxe-update`)* |
 | Autoria de workflow | `oxe/workflows/workflow-authoring.md` | “rever workflow OXE”, “revisar `oxe/workflows/foo.md` contra o guia”, alinhar passo ao `WORKFLOW_AUTHORING.md` |
 
 **Regra:** leia o Markdown indicado e execute **todos** os passos e critérios de sucesso descritos nesse arquivo. Não atalhe: crie ou atualize os arquivos em `.oxe/` conforme o workflow.
 
-**Cursor:** há slash `/oxe-*` para scan…help em `~/.cursor/commands/`; **não** há comando slash dedicado a review-pr no Cursor — use linguagem natural + `oxe/workflows/review-pr.md` em contexto.
+**Cursor:** há slash `/oxe-*` para scan…help e **`/oxe-update`** em `~/.cursor/commands/`; **não** há comando slash dedicado a review-pr no Cursor — use linguagem natural + `oxe/workflows/review-pr.md` em contexto.
 
 ## Onde ficam as integrações (após `npx oxe-cc`)
 
@@ -36,6 +37,7 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 ## Configuração do projeto
 
 - **`.oxe/config.json`**: fluxo (`discuss_before_plan`, `scan_max_age_days`, `spec_required_sections`, …) e opcionalmente **`install`** (perfil e layout quando o utilizador corre o instalador **sem** flags IDE explícitas). Referência: `oxe/templates/CONFIG.md`. Para ignorar o bloco `install` numa corrida: **`--no-install-config`**.
+- **Legado / brownfield** (COBOL, JCL, copybooks, VB6, SQL procedures): seguir também `oxe/workflows/references/legacy-brownfield.md` quando o repo ou o pedido indicar mainframe ou desktop legado — scan preenche os sete ficheiros sem assumir Node; plan/verify aceitam evidência por Grep/leitura/checklist.
 - Sem TTY (CI): **`OXE_NO_PROMPT=1`** — padrões de layout/integração; o ficheiro `install` em `config.json` aplica-se se existir e as flags não sobrepuserem.
 
 ## Artefatos
@@ -47,7 +49,7 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 
 - **`npx oxe-cc`** ou **`npx oxe-cc install`** — instalação (equivalentes).
 - **`npx oxe-cc doctor`** — validação completa (Node, workflows do pacote vs projeto, JSON, coerência STATE, regras SPEC/PLAN, **avisos** não bloqueantes sobre estrutura dos `.md` de workflow quando aplicável).
-- **`npx oxe-cc status`** — mais leve: coerência `.oxe/` + **um** próximo passo (não exige o mesmo rigor de workflows que o `doctor`).
+- **`npx oxe-cc status`** — mais leve: coerência `.oxe/` + **um** próximo passo (não exige o mesmo rigor de workflows que o `doctor`). **`status --json`**: saída máquina-legível para CI (`nextStep`, `diagnostics`, …).
 - **`npx oxe-cc init-oxe`**, **`uninstall`**, **`update`** — ver `oxe-cc --help` ou README do pacote.
 - **SDK (Node):** `require('oxe-cc')` expõe `runDoctorChecks`, `health`, `workflows`, `install`, `manifest`, `agents` — útil para CI (`lib/sdk/README.md`, `lib/sdk/index.d.ts`).
 
@@ -55,6 +57,6 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 
 ## Manutenção do pacote oxe-build
 
-Ao alterar comportamento OXE, edite primeiro **`oxe/workflows/*.md`**; mantenha comandos Cursor e prompts Copilot alinhados a essa pasta.
+Ao alterar comportamento OXE, edite primeiro **`oxe/workflows/*.md`**; mantenha prompts em **`.github/prompts/`** e comandos Cursor gerados pelo sync alinhados a essa pasta (e as integrações multi-agente coerentes com `oxe-agent-install.cjs`).
 
 **Autoria de workflows:** guia em **`oxe/templates/WORKFLOW_AUTHORING.md`**. Para rever um `.md` de passo contra o guia, use o workflow **`oxe/workflows/workflow-authoring.md`** (ou `.oxe/workflows/` no projeto alvo).

package/.github/prompts/oxe-help.prompt.md

@@ -1,7 +1,7 @@
 ---
 name: oxe-help
 agent: agent
-description: OXE — Ajuda (Cursor, Copilot, artefatos)
+description: OXE — Ajuda (fluxo .oxe/, várias IDEs e CLIs, artefatos)
 ---
 
 Executa o workflow **OXE help**. Lê e segue **integralmente**:

package/.github/prompts/oxe-update.prompt.md

@@ -0,0 +1,11 @@
+---
+name: oxe-update
+agent: agent
+description: Atualizar oxe-cc no projeto — verificar versão no npm, alinhar ficheiros OXE e validar com doctor
+---
+
+Executa o workflow **OXE update**. Lê e segue **integralmente**:
+
+`oxe/workflows/update.md` (na raiz do repositório em contexto; ou `.oxe/workflows/update.md` se a instalação aninhou os workflows)
+
+Na prática: na raiz do projeto, correr **`npx oxe-cc update --check`**, depois (se aplicável) **`npx oxe-cc update`** ou **`npx oxe-cc update --if-newer`**, e por fim **`npx oxe-cc doctor`**.

package/.github/workflows/ci.yml

@@ -1,18 +1,20 @@
-name: CI
-
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm test
-      - run: npm run scan:assets
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run scan:assets

package/AGENTS.md

@@ -1,13 +1,13 @@
-# OXE — agentes (GitHub Copilot / compatível)
+# OXE — agentes (multi-IDE / multi-CLI)
 
-Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`).
+Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`). O núcleo é agnóstico; o **`oxe-cc`** integra com **várias IDEs e CLIs** (Cursor e GitHub Copilot como caminho padrão conhecido, mais Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity quando instalado com **`--all-agents`** ou flags granulares).
 
 - **npm:** o nome do pacote é **`oxe-cc`** (`npx oxe-cc@latest` quando estiver publicado; se `npm view oxe-cc` der 404, usar `npm link` a partir deste repo ou `node bin/oxe-cc.js`).
-- **Instruções do repositório:** [.github/copilot-instructions.md](.github/copilot-instructions.md) — aplicadas automaticamente no Copilot Chat quando o repo está em contexto.
-- **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; Cursor e Copilot apontam para estes ficheiros (inclui `quick.md`, `execute.md`).
+- **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; todas as integrações apontam para estes ficheiros (inclui `quick.md`, `execute.md`). Referência **legado / brownfield:** [oxe/workflows/references/legacy-brownfield.md](oxe/workflows/references/legacy-brownfield.md) (COBOL, JCL, copybooks, VB6, SP).
+- **Instruções do repositório:** [.github/copilot-instructions.md](.github/copilot-instructions.md) — aplicadas automaticamente no **GitHub Copilot Chat** quando o repo está em contexto (outras ferramentas usam os seus próprios homes após `oxe-cc install`).
 - **CLI:** `oxe-cc` instala assets e bootstrap (`.oxe/STATE.md`, `config.json`, `codebase/`); `oxe-cc doctor` valida workflows, JSON de config, coerência STATE vs artefatos e regras opcionais de SPEC/PLAN; `oxe-cc status` mostra coerência `.oxe/` e **um** próximo passo; `oxe-cc init-oxe` só inicializa `.oxe/`.
 - **SDK:** `require('oxe-cc')` expõe `runDoctorChecks`, `health`, `workflows`, `install`, `manifest`, `agents` — ver [lib/sdk/README.md](lib/sdk/README.md).
-- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
+- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-update`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
 - **Copilot CLI:** `oxe-cc --copilot-cli` → skills em **`~/.copilot/skills/`** (`/oxe`, `/oxe-scan`, …); após instalar use **`/skills reload`**. Cópia extra em `~/.claude/commands/` para compatibilidade.
 - **Multi-agente:** `oxe-cc --all-agents` replica comandos/skills nos homes de **OpenCode**, **Gemini**, **Codex**, **Windsurf**, **Antigravity** (além de Cursor, Copilot, Claude); ver `README.md` e `bin/lib/oxe-agent-install.cjs`.
 

package/README.md

@@ -4,20 +4,22 @@
   <img src="assets/readme-banner.svg" alt="OXE" width="920" />
 </p>
 
-**Fluxo spec-driven e context engineering para [Cursor](https://cursor.com) e [GitHub Copilot](https://github.com/features/copilot)** — **poucos comandos slash**, foco em **`.oxe/`** (workflows em **`.oxe/workflows/`** por padrão, ou **`oxe/workflows/`** com `--global`). Textos do CLI e resumos pós-comando estão em **português (Brasil)**.
+**Fluxo spec-driven e context engineering centrado em `.oxe/`** — o núcleo é o mesmo em qualquer ferramenta. O instalador integra com **[Cursor](https://cursor.com)** e **[GitHub Copilot](https://github.com/features/copilot)** por padrão e, com **`--all-agents`** ou escolhas no menu, também com **Claude Code, OpenCode, Gemini CLI, Codex, Windsurf** e **Antigravity**. **Poucos comandos** por runtime, workflows em **`.oxe/workflows/`** (ou **`oxe/workflows/`** com `--global`). Textos do CLI e resumos pós-comando em **português (Brasil)**.
 
 [![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 deste repositório / próximo publish npm:** `0.3.6` (fonte: [`package.json`](package.json)). No registo use `npx oxe-cc@latest` ou, para pinar, `npx oxe-cc@0.3.6`.
+
 ```bash
 npx oxe-cc@latest
 # equivalente explícito:
 # npx oxe-cc@latest install
 ```
 
-**Manter atualizado:** `npx oxe-cc@latest --force` ou `npx oxe-cc update` (na raiz do projeto). Com **`--force`**, alterações locais em arquivos rastreados geram backup em **`~/.oxe-cc/oxe-local-patches/`**.
+**Manter atualizado:** no **Cursor** use **`/oxe-update`**; noutras CLIs siga o mesmo fluxo com o terminal no projeto (`npx oxe-cc update --check`, `npx oxe-cc update` ou `npx oxe-cc@latest --force`). Com **`--force`**, alterações locais em arquivos rastreados geram backup em **`~/.oxe-cc/oxe-local-patches/`**.
 
-[Para quem é](#para-quem-é) · [Começar](#começar) · [Como funciona](#como-funciona) · [Modo rápido](#modo-rápido) · [Porque funciona](#porque-funciona) · [Comandos](#comandos) · [Configuração](#configuração) · [SDK](#sdk-api-programática) · [Problemas](#resolução-de-problemas)
+[Para quem é](#para-quem-é) · [Começar](#começar) · [Como funciona](#como-funciona) · [Modo rápido](#modo-rápido) · [Porque funciona](#porque-funciona) · [Comandos](#comandos) · [CLI (`oxe-cc`)](#cli-do-pacote-oxe-cc) · [Configuração](#configuração) · [SDK](#sdk-api-programática) · [Problemas](#resolução-de-problemas)
 
 </div>
 
@@ -27,7 +29,7 @@ npx oxe-cc@latest
 
 Para quem quer **descrever o que quer e ver isso construído de forma consistente** — **sem** simular uma organização enorme de processos em cima do repositório.
 
-OXE é **enxuto**: não há dezenas de slash commands. Há **um CLI** que deixa o repositório **só com `.oxe/`** (layout **padrão**) ou **`oxe/` + `.oxe/`** com **`--global`**, e instala integrações em **`~/.cursor`**, **`~/.copilot`** e **`~/.claude`** — **workflows em Markdown** e **estado em disco** para a sessão não ficar **sobrecarregada** com tudo o que já foi decidido.
+OXE é **enxuto**: não há dezenas de comandos por ferramenta. Há **um CLI** que deixa o repositório **só com `.oxe/`** (layout **padrão**) ou **`oxe/` + `.oxe/`** com **`--global`**, e copia integrações para os homes que escolheres — tipicamente **`~/.cursor`**, **`~/.copilot`** e **`~/.claude`**, ou **OpenCode, Gemini, Codex, Windsurf, Antigravity** quando ativas — sempre com **workflows em Markdown** e **estado em disco** para a sessão não ficar **sobrecarregada** com tudo o que já foi decidido.
 
 ---
 
@@ -41,11 +43,11 @@ Na **raiz do repositório** do seu projeto:
 npx oxe-cc@latest
 ```
 
-Em **terminal interativo**, o instalador pergunta em **dois passos**: (1) **onde integrar** o OXE (Cursor, Copilot, só núcleo com `.oxe/`, etc.); (2) **layout no repositório** — **clássico** (`oxe/` na raiz + `.oxe/`, com opcional `commands/oxe/`, `AGENTS.md`) ou **mínimo** (**só `.oxe/`**, com **`.oxe/workflows/`** e templates). **Cursor, Copilot e CLI** usam **sempre** as pastas do **usuário** (`~/.cursor`, `~/.copilot`, `~/.claude`); **não** são criados `.cursor` / `.github` / `.claude` dentro do repo. Com layout clássico e **`--vscode`**, **`.vscode/`** fica no projeto.
+Em **terminal interativo**, o instalador pergunta em **vários passos**: (1) **para quais ambientes** (Cursor, Copilot, OpenCode, Gemini, … ou todos); (2) **global vs local** no disco; (3) **layout no repositório** — **clássico** (`oxe/` na raiz + `.oxe/`) ou **mínimo** (**só `.oxe/`**). Em modo **global IDE**, as integrações vão para pastas do **usuário** (`~/.cursor`, `~/.copilot`, …); com **`--ide-local`**, podem ficar no repo (`.cursor`, `.github`, …). Por omissão antiga, **não** se criam pastas IDE dentro do repo. Com layout clássico e **`--vscode`**, **`.vscode/`** fica no projeto.
 
 Ao terminar, o CLI mostra um **resumo do que foi criado ou atualizado** e **próximos passos sugeridos** (por exemplo `npx oxe-cc doctor`, `/oxe-scan`).
 
-Sem TTY (CI), o **layout mínimo** (só `.oxe/`) e integrações no **HOME** são o padrão (Cursor + Copilot, sem multi-agente). Use **`--global`** para também ter **`oxe/`** na raiz. Flags: **`--cursor`**, **`--copilot`**, **`--all`**, **`--oxe-only`**, **`OXE_NO_PROMPT=1`**, etc.
+Sem TTY (CI), o **layout mínimo** (só `.oxe/`) e integrações no **HOME** são o padrão (Cursor + Copilot; sem **`--all-agents`** a menos que configures). Use **`--global`** para também ter **`oxe/`** na raiz. Flags: **`--cursor`**, **`--copilot`**, **`--all-agents`**, **`--all`**, **`--oxe-only`**, **`OXE_NO_PROMPT=1`**, etc.
 
 Se já existir **`.oxe/config.json`** com o bloco **`install`** (perfil, `repo_layout`, …), o `oxe-cc` aplica isso **quando não passas** flags explícitas de integração — útil em CI. Para ignorar o ficheiro nessa corrida: **`--no-install-config`**. Detalhes: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md).
 
@@ -59,10 +61,13 @@ No fim, em modo interativo, pergunta se você quer instalar o **`oxe-cc` globalm
 
 | Onde | O que executar |
 |------|----------------|
-| **Cursor** | `/oxe-help` |
+| **Cursor** | `/oxe-help` ou outro `/oxe-*` |
 | **Copilot** (VS Code) | `/oxe-help` no chat, se [prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files) estiverem ativos (`"chat.promptFiles": true` — exemplo em [`.vscode/settings.json`](.vscode/settings.json)) |
+| **Copilot CLI** | `/oxe` ou `/oxe-scan` após **`/skills reload`** |
+| **Gemini CLI** | `/oxe` ou `/oxe:scan` após **`/commands reload`** (se instalou essa stack) |
+| **OpenCode / Codex / Windsurf / Antigravity** | Ver caminhos no resumo pós-instalação e o README na secção **Multi-agente** |
 
-> **Nota:** Instruções e prompt files do Copilot ficam em **`~/.copilot/`**, não em `.github/` no repo. **`oxe-cc doctor`** aceita workflows em **`.oxe/workflows/`** ou **`oxe/workflows/`**. Sem prompt files, você ainda pode pedir em linguagem natural com o repositório em contexto.
+> **Nota:** Instruções e prompt files do Copilot (VS Code) ficam em **`~/.copilot/`** por padrão, não em `.github/` no repo alvo. **`oxe-cc doctor`** aceita workflows em **`.oxe/workflows/`** ou **`oxe/workflows/`**. Em qualquer IDE, você ainda pode pedir em linguagem natural com o repositório e o workflow em contexto.
 
 **Sem pacote no npm** (`npm view oxe-cc version` → 404): clone este repo, `npm link` na pasta **oxe-build**, `npm link oxe-cc` no seu projeto e execute `oxe-cc`. Alternativa: `node /caminho/oxe-build/bin/oxe-cc.js`.
 
@@ -98,10 +103,10 @@ No fim, em modo interativo, pergunta se você quer instalar o **`oxe-cc` globalm
 |---------|--------|
 | `oxe-cc` ou `oxe-cc install` | Instalação predefinida (mesmo comportamento; `install` é alias explícito) |
 | `oxe-cc doctor` | Valida Node, workflows do pacote, `.oxe/`, coerência STATE vs arquivos, scan antigo (`scan_max_age_days`), seções da SPEC, ondas do PLAN |
-| `oxe-cc status` | Leve: coerência `.oxe/` + **um** próximo passo sugerido (espelha o workflow `next`; não exige o conjunto completo de workflows como o `doctor`) |
+| `oxe-cc status` | Leve: coerência `.oxe/` + **um** próximo passo sugerido (espelha o workflow `next`; não exige o conjunto completo de workflows como o `doctor`). **`--json`**: uma linha JSON com `nextStep`, `diagnostics`, etc., para CI ou scripts |
 | `oxe-cc init-oxe` | Só o bootstrap `.oxe/` (STATE, config, codebase) |
 | `oxe-cc uninstall` | Remove integrações OXE em `~/.cursor`, `~/.copilot`, `~/.claude` e pastas de workflows no repo (`--ide-only` só no HOME) |
-| `oxe-cc update` | Executa `npx oxe-cc@latest --force` na pasta do projeto (útil para atualizar tudo de uma vez) |
+| `oxe-cc update` | Executa `npx oxe-cc@latest --force` na pasta do projeto; **`--check`** só consulta o npm; **`--if-newer`** evita o npx quando já está na última |
 
 </details>
 
@@ -123,6 +128,23 @@ Para testar no seu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alv
 
 ## Como funciona
 
+### Ciclo por trilha
+
+Fluxo sugerido (cada iteração de trabalho segue a trilha e volta ao **scan** quando for hora de realinhar com o repo):
+
+```mermaid
+flowchart LR
+  scan --> spec
+  spec --> plan
+  plan --> execute
+  execute --> verify
+  verify -->|próxima trilha| scan
+```
+
+**verify (T):** as tarefas **T** do plano trazem o bloco **Verificar** (comando ou checklist) por item; o passo **`/oxe-verify`** cruza SPEC + PLAN com o código e grava **`.oxe/VERIFY.md`**.
+
+<p align="center"><img src="assets/oxe-ciclo-por-trilha.png" alt="Diagrama: scan → spec → plan → execute → verify (T), seta de volta a scan" width="720" /></p>
+
 **Já tem código no repositório?** Comece por **`/oxe-scan`**. Isso gera mapas em **`.oxe/codebase/`** (stack, estrutura, testes, convenções, etc.). Assim o **spec** e o **plan** alinham com o repo real antes de planear em grande escala.
 
 ### 1. Mapear — `/oxe-scan`
@@ -189,34 +211,145 @@ Se o trabalho crescer, **promova** para spec + plan completos.
 
 ## Comandos
 
-### Fluxo principal
+Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Copilot: `~/.copilot/prompts/` com `chat.promptFiles`). A **fonte única** dos passos está em [`oxe/workflows/*.md`](oxe/workflows/) no pacote ou em [`.oxe/workflows/`](.oxe/workflows/) no projeto após `npx oxe-cc`.
+
+### Resumo rápido
+
+| Comando / prompt | Workflow (fonte dos passos) |
+|------------------|-------------------|
+| `/oxe-scan` | [`scan.md`](oxe/workflows/scan.md) |
+| `/oxe-spec` | [`spec.md`](oxe/workflows/spec.md) |
+| `/oxe-discuss` | [`discuss.md`](oxe/workflows/discuss.md) |
+| `/oxe-plan` | [`plan.md`](oxe/workflows/plan.md) |
+| `/oxe-quick` | [`quick.md`](oxe/workflows/quick.md) |
+| `/oxe-execute` | [`execute.md`](oxe/workflows/execute.md) |
+| `/oxe-verify` | [`verify.md`](oxe/workflows/verify.md) |
+| `/oxe-next` | [`next.md`](oxe/workflows/next.md) |
+| `/oxe-help` | [`help.md`](oxe/workflows/help.md) |
+| `/oxe-update` | [`update.md`](oxe/workflows/update.md) |
+| `/oxe-review-pr` *(prompt Copilot; ver nota abaixo)* | [`review-pr.md`](oxe/workflows/review-pr.md) |
+| *(mantenedores)* `workflow-authoring` em linguagem natural | [`workflow-authoring.md`](oxe/workflows/workflow-authoring.md) |
+
+### Referência completa por passo
+
+#### `/oxe-scan`
+
+- **O que faz:** Analisa o repositório e produz **sete** mapas estruturados em `.oxe/codebase/` (overview, stack, estrutura, testes, integrações, convenções, preocupações) e atualiza `.oxe/STATE.md` com data de scan e fase sugerida.
+- **Artefatos:** `.oxe/codebase/*.md`, `.oxe/STATE.md` (não apaga `SPEC.md` / `PLAN.md`).
+- **Quando usar:** Após clonar, quando o repo mudou muito, ou quando quiser foco opcional (pasta/módulo) ou `scan_focus_globs` em `.oxe/config.json`.
+- **Limite:** Não executa testes por si; não substitui leitura do código — condensa para contexto de agente. Repositórios legado: segue também [`references/legacy-brownfield.md`](oxe/workflows/references/legacy-brownfield.md).
+- **Workflow:** [`oxe/workflows/scan.md`](oxe/workflows/scan.md)
+
+#### `/oxe-spec`
+
+- **O que faz:** Regista o contrato do trabalho em `.oxe/SPEC.md`: objetivo, escopo, **critérios de aceite com IDs estáveis (A1, A2, …)** e coluna *Como verificar*, suposições e riscos.
+- **Artefatos:** `.oxe/SPEC.md`, `.oxe/STATE.md` (fase `spec_ready`).
+- **Quando usar:** Antes de planear qualquer entrega média ou grande; entrada pode ser texto livre ou `@ficheiro.md`.
+- **Limite:** Não implementa código; o plano e o verify é que amarram tarefas aos **A*** .
+- **Workflow:** [`oxe/workflows/spec.md`](oxe/workflows/spec.md)
+
+#### `/oxe-discuss`
+
+- **O que faz:** Regista perguntas, respostas e decisões em `.oxe/DISCUSS.md` (máx. 7 perguntas enxutas) antes do plano, alinhado à SPEC.
+- **Artefatos:** `.oxe/DISCUSS.md`, `.oxe/STATE.md` (`discuss_complete`).
+- **Quando usar:** Ambiguidade na SPEC, risco técnico, ou `discuss_before_plan: true` em `.oxe/config.json`.
+- **Limite:** Opcional; não substitui a SPEC nem o PLAN.
+- **Workflow:** [`oxe/workflows/discuss.md`](oxe/workflows/discuss.md)
+
+#### `/oxe-plan`
+
+- **O que faz:** Gera ou atualiza `.oxe/PLAN.md` com tarefas **Tn**, **ondas**, dependências, bloco **Verificar** por tarefa e **Aceite vinculado** aos critérios **A*** da SPEC; suporta `--replan` após `verify_failed` usando `VERIFY.md` / `SUMMARY.md`.
+- **Artefatos:** `.oxe/PLAN.md`, `.oxe/STATE.md` (`plan_ready`).
+- **Quando usar:** SPEC pronta (e discuss, se a config obrigar); base em `.oxe/codebase/*` e código real.
+- **Limite:** Não executa as tarefas — isso é **execute** + o teu Git.
+- **Workflow:** [`oxe/workflows/plan.md`](oxe/workflows/plan.md)
 
-| Comando | O que faz |
-|---------|-----------|
-| `/oxe-scan` | Mapeia o codebase → `.oxe/codebase/` |
-| `/oxe-spec` | Escreve/atualiza `.oxe/SPEC.md` |
-| `/oxe-discuss` | Decisões antes do plano → `.oxe/DISCUSS.md` |
-| `/oxe-plan` | Pesquisa no repo + plano com ondas e Verificar |
-| `/oxe-execute` | Execução guiada do plano (ou QUICK) |
-| `/oxe-verify` | Validação; `.oxe/VERIFY.md` |
-| `/oxe-next` | Sugere o próximo passo |
-| `/oxe-help` | Ajuda e visão geral |
+#### `/oxe-quick`
 
-### Modo rápido
+- **O que faz:** Fluxo curto com `.oxe/QUICK.md` (passos numerados + verificar) para trabalho pontual sem SPEC/PLAN longos.
+- **Artefatos:** `.oxe/QUICK.md`, `.oxe/STATE.md` conforme fluxo.
+- **Quando usar:** Fix ou spike muito pequeno; promover a spec/plan se o trabalho crescer.
+- **Limite:** Menos trilha de auditoria que SPEC+PLAN completos.
+- **Workflow:** [`oxe/workflows/quick.md`](oxe/workflows/quick.md)
 
-| Comando | O que faz |
-|---------|-----------|
-| `/oxe-quick` | `.oxe/QUICK.md` — tarefa pontual |
+#### `/oxe-execute`
 
-### Revisão de PR / diff entre branches *(só Copilot)*
+- **O que faz:** Guia a implementação **onda a onda** com base em `PLAN.md` (ou passos de `QUICK.md`), com checklist explícito e atualização de `.oxe/STATE.md` (progresso Tn / ondas).
+- **Artefatos:** Código/docs que implementas; `.oxe/STATE.md` (checklist de onda).
+- **Quando usar:** Durante a execução do plano ou do QUICK, para não saltar pré-requisitos nem verificações da onda.
+- **Limite:** Não faz commits nem impõe subagentes — fica a teu critério de equipa.
+- **Workflow:** [`oxe/workflows/execute.md`](oxe/workflows/execute.md)
 
-| Prompt | O que faz |
-|--------|-----------|
-| `/oxe-review-pr` | Segue `oxe/workflows/review-pr.md`: diff estilo PR (`git diff base...head`, `gh pr diff <n>`, ou fetch `pull/<n>/head`), riscos, testes e checklist. Você pode colar o **link da PR** (ex.: `https://github.com/org/repo/pull/10`) ou indicar `main` e `feature/x`. **Não** há slash command em `.cursor/commands/`; no Cursor você pode pedir o mesmo em linguagem natural com o workflow em contexto. |
+#### `/oxe-verify`
 
-### Outros clientes
+- **O que faz:** Corre ou orienta verificação: comandos do PLAN, confronto de **cada** critério **A*** da SPEC com evidência, registo em `.oxe/VERIFY.md`; opcionalmente rascunho de commit e checklist de PR conforme `.oxe/config.json`.
+- **Artefatos:** `.oxe/VERIFY.md`, `.oxe/STATE.md` (`verify_complete` / `verify_failed`), `.oxe/SUMMARY.md` quando há gaps relevantes.
+- **Quando usar:** Após implementar uma onda ou fechar o plano; pode focar uma tarefa **Tn** se indicares.
+- **Limite:** Sandbox pode impedir comandos — regista “não executado aqui” e deixa o comando para correres localmente.
+- **Workflow:** [`oxe/workflows/verify.md`](oxe/workflows/verify.md)
 
-Em **Claude Code** (ou ferramentas que leem `commands/oxe/`), os mesmos passos expõem nomes **`oxe:scan`**, **`oxe:plan`**, etc. (frontmatter `name:`).
+#### `/oxe-next`
+
+- **O que faz:** Sugere o **único** próximo passo lógico com base nos artefactos `.oxe/` (equivalente conceptual ao que o terminal faz com `npx oxe-cc status`, sem validar o pacote de workflows completo).
+- **Artefatos:** Pode sugerir atualizar `STATE.md` após confirmares a ação.
+- **Quando usar:** Retomar trabalho ou desbloquear “o que faço agora?”.
+- **Limite:** Heurística sobre arquivos existentes; não substitui leitura humana do PLAN.
+- **Workflow:** [`oxe/workflows/next.md`](oxe/workflows/next.md)
+
+#### `/oxe-help`
+
+- **O que faz:** Apresenta o fluxo OXE (scan → spec → plan → execute → verify), modo quick, invocação em várias IDEs/CLIs e referência ao `oxe-cc` (install, doctor, status, …).
+- **Artefatos:** Nenhum obrigatório (só saída no chat).
+- **Quando usar:** Onboarding ou quando mudas de IDE.
+- **Limite:** Resumo; detalhe máximo continua nos workflows linkados.
+- **Workflow:** [`oxe/workflows/help.md`](oxe/workflows/help.md)
+
+#### `/oxe-update`
+
+- **O que faz:** Segue o workflow de atualização: verificar versão no npm, correr `npx oxe-cc@latest` com flags adequadas, `doctor`, e próximos passos (ex. `/oxe-scan` se workflows mudaram).
+- **Artefatos:** Arquivos do pacote OXE no projeto e integrações conforme a tua instalação.
+- **Quando usar:** Após anúncio de release ou quando queres alinhar workflows/templates à última versão publicada.
+- **Limite:** Não altera o teu código de aplicação fora do que o instalador OXE gere.
+- **Workflow:** [`oxe/workflows/update.md`](oxe/workflows/update.md)
+
+#### Revisão de PR / diff (`review-pr`)
+
+- **O que faz:** Análise estilo code review sobre diff entre branches, link de PR, ou `gh pr diff`: riscos, testes sugeridos, checklist.
+- **Artefatos:** Saída no chat (não obriga arquivos em `.oxe/`).
+- **Quando usar:** Antes de merge ou para revisão rápida de alterações alheias.
+- **Copilot (VS Code):** prompt file **`/oxe-review-pr`** quando `chat.promptFiles` está ativo.
+- **Cursor:** não há slash dedicado em `.cursor/commands/` — abre [`oxe/workflows/review-pr.md`](oxe/workflows/review-pr.md) no contexto ou pede em linguagem natural o mesmo fluxo.
+- **Workflow:** [`oxe/workflows/review-pr.md`](oxe/workflows/review-pr.md)
+
+#### Autoria de workflows (`workflow-authoring`)
+
+- **O que faz:** Alinha edições de `oxe/workflows/*.md` ao guia de estrutura (objective/context/process/success_criteria), progressive disclosure, e coerência com Cursor/Copilot.
+- **Artefatos:** Alterações nos próprios workflows do pacote ou fork.
+- **Quando usar:** Manutenção do OXE ou contribuição de novos passos.
+- **Limite:** Para utilizadores finais do fluxo spec/plan, não é necessário no dia a dia.
+- **Workflow:** [`oxe/workflows/workflow-authoring.md`](oxe/workflows/workflow-authoring.md)
+
+### Outros clientes (nomes `oxe:*`)
+
+Em **Claude Code**, **Copilot CLI** (skills), **Gemini CLI**, **OpenCode**, **Codex**, **Windsurf**, **Antigravity**, os mesmos passos aparecem com nomes como **`oxe:scan`**, **`oxe:plan`**, **`/oxe-scan`**, etc., conforme o destino instalado com `oxe-cc --all-agents` ou flags granulares. O núcleo continua a ser `.oxe/` no **projeto alvo**.
+
+---
+
+## CLI do pacote (`oxe-cc`)
+
+Comandos no terminal na **raiz do projeto** (ou `--dir`). Útil em CI, scripts e quando não estás num chat com slash commands.
+
+| Subcomando | Poder principal |
+|------------|-----------------|
+| `oxe-cc` / `oxe-cc install` | Copia **workflows** e **templates** para `.oxe/` (layout mínimo) ou `oxe/` + `.oxe/` (`--global`), e instala integrações IDE/CLI conforme flags (`--cursor`, `--copilot`, `--all-agents`, …). |
+| `oxe-cc doctor` | Validação **completa**: versão Node, diff workflows **pacote npm ↔ projeto**, parse de `.oxe/config.json`, coerência de **STATE** com arquivos esperados, scan antigo (`scan_max_age_days`), seções obrigatórias da SPEC, ondas do PLAN, avisos de estrutura dos `.md` de workflow, e **planWarn** (inclui tarefas **Tn** sem `**Aceite vinculado:**`). |
+| `oxe-cc status` | Diagnóstico **mais leve**: mesma leitura de saúde `.oxe/` + config + **um único** próximo passo sugerido (`suggestNextStep`) — não exige o mesmo conjunto de checks pesados do `doctor` sobre o pacote. |
+| `oxe-cc status --json` | Igual ao `status`, mas imprime **uma linha JSON** (`oxeStatusSchema`, `nextStep`, `cursorCmd`, `reason`, `artifacts`, `phase`, `diagnostics.*`) para pipelines e agentes automáticos. Sem banner quando `--json`. |
+| `oxe-cc init-oxe` | Apenas **bootstrap** de `.oxe/STATE.md`, `.oxe/config.json` e pasta `.oxe/codebase/` — sem reinstalar integrações nas tuas pastas home. |
+| `oxe-cc update` | Corre `npx oxe-cc@latest --force` no projeto (ou equivalente) para alinhar workflows/templates; **`--check`** só compara versão no npm; **`--if-newer`** evita o npx se já estiveres na última. |
+| `oxe-cc uninstall` | Por omissão remove integrações em `~/.cursor`, `~/.copilot`, … **e** pastas de workflows no projeto (`.oxe/workflows`, `oxe/`, `commands/oxe`, …). **`--ide-only`** não remove workflows no repo (só integrações no HOME). **`--ide-local`** também remove integrações OXE **dentro** do repositório (`.cursor`, `.github`, `.claude`, `.copilot`, …). |
+
+**SDK:** `require('oxe-cc')` expõe `runDoctorChecks`, `health.buildHealthReport`, `health.suggestNextStep`, etc. — ver secção [SDK](#sdk-api-programática) abaixo e [`lib/sdk/README.md`](lib/sdk/README.md).
 
 ---
 
@@ -224,6 +357,8 @@ Em **Claude Code** (ou ferramentas que leem `commands/oxe/`), os mesmos passos e
 
 Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Inclui opções de fluxo (`discuss_before_plan`, `scan_max_age_days`, `spec_required_sections`, …) e, opcionalmente, o bloco **`install`** (perfil de integração e layout do repo quando corres o instalador sem flags IDE). Referência completa: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md).
 
+Repositórios **legado** (COBOL, JCL, copybooks, VB6, stored procedures): os workflows **scan**, **spec**, **plan**, **execute** e **verify** delegam padrões de análise e verificação em [`.oxe/workflows/references/legacy-brownfield.md`](oxe/workflows/references/legacy-brownfield.md) após `npx oxe-cc` (no pacote fonte: [`oxe/workflows/references/legacy-brownfield.md`](oxe/workflows/references/legacy-brownfield.md)).
+
 ---
 
 ## SDK (API programática)
@@ -247,7 +382,7 @@ Também estão disponíveis `oxe.health`, `oxe.workflows`, `oxe.install.resolveO
 | Comandos não aparecem no Cursor | Confirme que `~/.cursor/commands/` (ou a pasta configurada) existe; reinicie o Cursor |
 | Prompts `/oxe-*` não aparecem no Copilot | Ative `"chat.promptFiles": true`; confirme prompts em **`~/.copilot/prompts/`** (o OXE não coloca `.github/` no repo para o Copilot) |
 | **`/oxe` ou `/oxe-*` não aparecem no Copilot CLI** | O CLI usa **skills** em **`~/.copilot/skills/`**, não a pasta `commands`. Rode `npx oxe-cc --copilot-cli` (ou perfil com CLI), depois **`/skills reload`**. Use **`/oxe`** (ajuda) ou **`/oxe-scan`**, etc. |
-| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixe a versão: `npx oxe-cc@0.3.0`. Verifique `npm config get registry` |
+| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixe a versão: `npx oxe-cc@0.3.6`. Verifique `npm config get registry` |
 | **404** no `npm view oxe-cc` | Pacote com outro nome (scope) ou ainda não publicado — use `npm link` ou `node …/bin/oxe-cc.js` |
 | Arquivos não atualizam | Reinstale com **`--force`** (com backup local se você tiver editado arquivos rastreados) |
 | Erro no **WSL** sobre Node do Windows | Use **Node instalado dentro do WSL** (o `oxe-cc` recusa `node.exe` do Windows em ambiente WSL para evitar caminhos quebrados) |

package/bin/banner.txt

@@ -11,7 +11,7 @@
         "Do jeito nordestino de fazer software"
 
         ⚙️  Context Engineering
-        🤖  Cursor · Copilot · AI Agents
+        🤖  Multi-IDE · Cursor · Copilot · +CLIs
 
 ══════════════════════════════════════════════════════