oxe-cc 0.3.1 → 0.3.3

package/.github/copilot-instructions.md

@@ -18,6 +18,7 @@ Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear
 | Execute | `oxe/workflows/execute.md` | “oxe execute”, “executar onda”, “onda 2 OXE” |
 | Verify | `oxe/workflows/verify.md` | “oxe verify”, “validar plano OXE”, “VERIFY.md” |
 | 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”, “code review OXE” *(prompt: `/oxe-review-pr`)* |
 | Help | `oxe/workflows/help.md` | “oxe help”, “como usar OXE” |
 
 **Regra:** lê o Markdown indicado e executa **todos** os passos e critérios de sucesso descritos nesse ficheiro. Não atalhes: cria ou atualiza os ficheiros em `.oxe/` conforme o workflow.
@@ -30,7 +31,8 @@ Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear
 ## Cursor vs Copilot
 
 - **Cursor:** slash commands em `.cursor/commands/oxe-*.md` apontam para os mesmos workflows.
-- **Copilot:** prompt files em `.github/prompts/oxe-*.prompt.md`; cada um indica o workflow em `oxe/workflows/<passo>.md` na raiz do repo.
+- **Copilot (VS Code Chat):** prompt files em `.github/prompts/oxe-*.prompt.md`; cada um indica o workflow em `oxe/workflows/<passo>.md` na raiz do repo. **`oxe-review-pr`** existe só como prompt Copilot (não há slash command Cursor correspondente).
+- **Copilot CLI (terminal, experimental):** com `oxe-cc --copilot-cli`, os mesmos textos são copiados para **`.claude/commands/oxe-*.md`** — versões recentes do CLI podem expor **`/oxe-scan`**, etc. Isto depende da versão do `copilot`; não faz parte do contrato estável do OXE.
 
 ## Manutenção deste pacote (oxe-build)
 

package/.github/prompts/oxe-review-pr.prompt.md

@@ -0,0 +1,12 @@
+---
+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)
+
+**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/AGENTS.md

@@ -6,6 +6,7 @@ Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`).
 - **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`).
 - **CLI:** `oxe-cc` instala assets e bootstrap (`.oxe/STATE.md`, `config.json`, `codebase/`); `oxe-cc doctor` valida workflows, JSON de config e mapa scan; `oxe-cc init-oxe` só inicializa `.oxe/`.
-- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`) 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-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
+- **Copilot CLI (experimental):** `oxe-cc --copilot-cli` → `.claude/commands/oxe-*.md` para testar `/oxe-scan` no terminal.
 
 Quando o utilizador pedir uma etapa OXE por linguagem natural, segue o ficheiro `oxe/workflows/<passo>.md` correspondente sem atalhar passos.

package/README.md

@@ -1,226 +1,244 @@
-# oxe-build
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/oxe-cc.svg)](https://www.npmjs.com/package/oxe-cc)
-[![license](https://img.shields.io/npm/l/oxe-cc.svg)](https://www.npmjs.com/package/oxe-cc)
+<p align="center">
+  <img src="assets/readme-banner.svg" alt="OXE" width="920" />
+</p>
 
-*(O badge de versão só reflete uma release real depois de `npm publish` concluído com sucesso.)*
+**Fluxo spec-driven e context engineering para [Cursor](https://cursor.com) e [GitHub Copilot](https://github.com/features/copilot) — inspirado na ideia do [GSD](https://github.com/gsd-build/get-shit-done), com **menos comandos** e foco em **`.oxe/`** + **`oxe/workflows/`**.**
 
-Fluxo **spec-driven** enxuto (inspirado em context engineering / GSD), com prefixo **OXE** e artefatos em **`.oxe/`**.
+[![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)
 
-Os alvos **iniciais** são **Cursor** e **GitHub Copilot** (VS Code e IDEs compatíveis). Outros clientes podem usar os mesmos workflows em Markdown.
+```bash
+npx oxe-cc@latest
+```
 
-O nome previsto no npm é **`oxe-cc`**. Confirma se já está publicado: `npm view oxe-cc version`. Se responder **404**, o pacote **ainda não existe** no registry — usa uma das opções abaixo até publicares com sucesso.
+**Manter atualizado:** `npx oxe-cc@latest --force` (na raiz do projeto).
 
-## Instalação (escolhe uma)
+[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) · [Problemas](#resolução-de-problemas)
 
-Precisas de **Node.js 18+**. O executável chama-se **`oxe-cc`**.
+</div>
 
-### A) Repositório local (sem npm registry)
+---
 
-```bash
-cd C:\caminho\para\oxe-build
-npm link
-cd C:\caminho\para\teu-projeto
-npm link oxe-cc
-oxe-cc
-```
+## Para quem é
+
+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 nem instalador multi-runtime. Há **um CLI** que copia ficheiros para o projeto, **workflows em Markdown** que o agente segue, e **estado em disco** para a sessão principal não “inchada” com tudo o que já foi decidido.
+
+---
 
-Ou, sem `link`, apontando ao script:
+## Começar
+
+**Requisito:** [Node.js 18+](https://nodejs.org/).
+
+Na **raiz do repositório** do teu projeto:
 
 ```bash
-node C:\caminho\para\oxe-build\bin\oxe-cc.js
+npx oxe-cc@latest
 ```
 
-### B) Depois de publicado no npm
+Isto copia, entre outros: **`oxe/`** (workflows + templates), **`.cursor/`** (slash commands), **`.github/`** (instruções Copilot + prompt files), **`commands/oxe/`** (atalhos estilo `oxe:*` para outros clientes), **`AGENTS.md`**, e cria um **`.oxe/`** mínimo (`STATE.md`, `config.json` a partir de template, pasta `codebase/`) — salvo flags como `--no-init-oxe`.
+
+Em **terminal interativo**, no fim pergunta se queres instalar o **`oxe-cc` globalmente** (`npm install -g`) ou continuar só com **`npx`**. Em CI ou scripts usa **`--no-global-cli`** / **`-l`**, ou define **`OXE_NO_PROMPT=1`**. Para instalar o CLI sem pergunta: **`--global-cli`** / **`-g`**.
+
+**GitHub Copilot CLI (experimental):** para testar slash commands no terminal, instala com **`--copilot-cli`** — copia **`.cursor/commands/*.md`** para **`.claude/commands/`** (ficheiros `oxe-scan.md`, etc., sem `prompt` no nome). Usa na raiz do repo: `npx oxe-cc@latest --force --copilot --copilot-cli`. Depois, na sessão do Copilot CLI, experimenta **`/oxe-scan`**. O suporte depende da versão do CLI; vê [discussão no copilot-cli](https://github.com/github/copilot-cli/issues/1113).
+
+**Confirmar instalação no agente**
+
+| Onde | O que correr |
+|------|----------------|
+| **Cursor** | `/oxe-help` |
+| **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)) |
+
+> **Nota:** O Copilot usa **instruções do repositório** (`.github/copilot-instructions.md`) **e** os ficheiros em `.github/prompts/*.prompt.md`. Sem prompt files, ainda podes pedir em linguagem natural (“executa o workflow OXE scan”) com o repo 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 teu projeto, e corre `oxe-cc`. Alternativa: `node /caminho/oxe-build/bin/oxe-cc.js`.
+
+<details>
+<summary><strong>Instalação: flags úteis (CI, ou só parte do pacote)</strong></summary>
+
+| Flag | Efeito |
+|------|--------|
+| `--force` / `-f` | Sobrescreve ficheiros já existentes (**obrigatório** para atualizar cópias antigas) |
+| `--dry-run` | Lista ações sem escrever |
+| `--cursor` / `--copilot` | Instala só uma das stacks |
+| `--oxe-only` | Só a pasta `oxe/` (workflows) |
+| `--no-init-oxe` | Não cria `.oxe/` no fim |
+| `--global-cli` / `-g` | Após copiar: `npm install -g oxe-cc@versão` (sem pergunta) |
+| `--no-global-cli` / `-l` | Não pergunta nem instala o CLI global (útil em CI) |
+| `--copilot-cli` | Copia comandos OXE para `.claude/commands/` (teste com GitHub Copilot CLI) |
+| `--vscode` | Copia `.vscode/settings.json` de exemplo |
+| `--no-commands` | Omite `commands/oxe/` |
+| `--no-agents` | Omite `AGENTS.md` |
+| `--dir <pasta>` ou argumento posicional | Destino em vez do diretório atual |
+
+**Global:** `npm install -g oxe-cc`.
+
+**Subcomandos:** `oxe-cc doctor` (valida Node, workflows, `.oxe/`), `oxe-cc init-oxe` (só bootstrap `.oxe/`).
+
+</details>
+
+<details>
+<summary><strong>Desenvolvimento (clonar o oxe-build)</strong></summary>
 
 ```bash
-cd /caminho/do/teu-projeto
-npx oxe-cc@latest
+git clone https://github.com/propagno/oxe-build.git
+cd oxe-build
+npm test
+node bin/oxe-cc.js --help
 ```
 
-Já tens OXE nesse repo e saiu release nova? Vê a secção **Atualizar para a versão mais recente** mais abaixo (resumo: `npx oxe-cc@latest --force` na raiz do projeto).
+Para testar no teu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alvo.
 
-Página do pacote (quando existir): [npmjs.com/package/oxe-cc](https://www.npmjs.com/package/oxe-cc). Versões: [aba Versions](https://www.npmjs.com/package/oxe-cc?activeTab=versions).
+</details>
 
-### C) Erro `npm error 404` / `'oxe-cc@latest' is not in this registry`
+---
 
-Significa que **nenhuma versão** de `oxe-cc` foi aceite no `registry.npmjs.org`. Causas frequentes:
+## Como funciona
 
-1. **`npm publish` falhou** (ex. **403** — conta com **2FA obrigatória** para publicar). Ativa 2FA em [npm → Security](https://www.npmjs.com/settings/~/security) e volta a correr `npm publish --access public` dentro da pasta do repo, já autenticado (`npm login`).
-2. **Nome diferente** — publicaste com **scope** (ex. `@propagno/oxe-cc`). Nesse caso usa `npx @propagno/oxe-cc@latest` (ajusta ao `name` real do `package.json`).
-3. **Outro registry** — confirma: `npm config get registry` → deve ser `https://registry.npmjs.org/` para o público.
+**Já tens código?** Começa por **`/oxe-scan`**. Gera mapas em **`.oxe/codebase/`** (stack, estrutura, testes, convenções, etc.). Assim o **spec** e o **plan** alinham com o repo real — à semelhança de correres *map-codebase* antes do roadmap no GSD.
 
-Até o 404 desaparecer, usa a opção **A** (`npm link` ou `node …/bin/oxe-cc.js`).
+### 1. Mapear — `/oxe-scan`
 
-Opções úteis:
+Inventaria o projeto e preenche **`.oxe/codebase/*.md`**, atualiza **`.oxe/STATE.md`**. Podes indicar foco opcional (ex. “só API”).
 
-| Opção | Efeito |
-|--------|--------|
-| *(omissão)* | **Cursor + Copilot** + `oxe/` + `commands/oxe` + `AGENTS.md` |
-| `--all`, `-a` | Garante Cursor e Copilot (mesmo efeito que omitir `--cursor` e `--copilot`) |
-| `--dir <pasta>` | Instala noutro diretório em vez do cwd |
-| `--cursor` | Só `.cursor/commands` e `.cursor/rules` |
-| `--copilot` | Só `.github/copilot-instructions.md` e `.github/prompts` |
-| `--vscode` | Copia também `.vscode/settings.json` (`chat.promptFiles`) |
-| `--no-commands` | Não copia `commands/oxe/` |
-| `--no-agents` | Não copia `AGENTS.md` |
-| `--force` / `-f` | Sobrescreve ficheiros já existentes |
-| `--dry-run` | Mostra o que faria sem escrever |
-| `--no-init-oxe` | Não cria `.oxe/` (STATE, config, codebase) após instalar |
-| `--oxe-only` | Copia só a pasta `oxe/` (sem Cursor, Copilot, `commands/oxe`, `AGENTS.md`) |
-| `-h` / `--help`, `-v` / `--version` | Ajuda e versão |
+### 2. Especificar — `/oxe-spec`
 
-**Subcomandos:**
+Produz ou atualiza **`.oxe/SPEC.md`**: objetivo, escopo, critérios de aceite, riscos. Isto é o contrato antes do plano.
 
-| Comando | Efeito |
-|---------|--------|
-| `oxe-cc doctor [dir]` | Node, workflows vs pacote, JSON válido em `.oxe/config.json`, mapa scan (7 ficheiros em `codebase/`) |
-| `oxe-cc init-oxe [dir]` | Só `.oxe/`: STATE, `config.json` (template), pasta `codebase/` |
+### 3. Discutir *(opcional)* — `/oxe-discuss`
 
-A pasta **`oxe/`** (workflows + templates) é **sempre** copiada na instalação normal. `--cursor` / `--copilot` apenas controlam se entram ficheiros em `.cursor/` e `.github/`.
+Captura decisões de implementação (UI, API, tom, edge cases) em **`.oxe/DISCUSS.md`**, para o plano não “adivinhar” o que preferes. Útil quando `discuss_before_plan` está ativo em `.oxe/config.json`. Saltar = defaults razoáveis; usar = mais próximo da tua visão.
 
-Instalação global (só depois do pacote existir no npm): `npm install -g oxe-cc`.
+### 4. Planear — `/oxe-plan`
 
-### Atualizar para a versão mais recente (depois de um novo `npm publish`)
+Gera **`.oxe/PLAN.md`**: tarefas **atómicas**, **ondas** (paralelo vs sequencial), e bloco **Verificar** (comando de teste ou checklist) **por tarefa**. Ideia: cada tarefa cabe num contexto de agente focado, com verificação explícita — mesmo espírito dos planos XML pequenos do GSD, em Markdown.
 
-O **`oxe-cc` não se auto-atualiza** nos teus projetos: copia ficheiros (`oxe/`, `.cursor/`, …) na altura em que corres o comando. Quando há uma release nova no npm:
+Ondas em resumo: tarefas **independentes** na mesma onda podem correr em paralelo; **dependentes** vão para ondas posteriores (como no diagrama de *waves* do GSD, só que com menos cerimónia).
 
-| Como usas o CLI | O que fazer |
-|-----------------|-------------|
-| **`npx oxe-cc@latest`** no projeto | Volta a correr na **raiz do repo alvo**: `npx oxe-cc@latest` (ou `npx oxe-cc@latest --force` para sobrescrever ficheiros já existentes). O `npx` resolve `@latest` no registry; se parecer “preso” a uma versão antiga, limpa a cache: `npx clear-npx-cache` (npm 7+) e tenta de novo. |
-| **`npm install -g oxe-cc`** | Atualiza o global: `npm install -g oxe-cc@latest` (ou `npm update -g oxe-cc`). Confirma com `oxe-cc --version`. |
-| **`npm link`** ao clone local | Faz `git pull` (ou equivalente) na pasta **`oxe-build`** e volta a correr `oxe-cc` — o link aponta para essa pasta, logo usas o código atual **sem** novo publish. Para alinhar com o que está no npm, publica e usa `npx`/`npm i -g` como acima. |
+### 5. Executar — implementação + `/oxe-execute` *(opcional)*
 
-Ver qual é a última versão publicada:
+Implementas no editor ou deixas o agente seguir **`/oxe-execute`** sobre o plano (ou QUICK). O OXE não impõe subagentes nem commits atómicos por tarefa como o GSD; isso fica ao teu fluxo Git.
 
-```bash
-npm view oxe-cc version
-```
+### 6. Verificar — `/oxe-verify`
 
-Comparar com a tua cópia (ficheiro `oxe/workflows/scan.md` etc.): se faltam workflows novos, corre outra vez o instalador com **`--force`** onde fizer sentido.
+Cruza **SPEC** + **PLAN** com o código; escreve **`.oxe/VERIFY.md`**. Se algo falhar, corrigis ou replanejas (`/oxe-plan` com lógica de replanejamento descrita no workflow).
 
-### Nova versão no npm (mantenedores)
+### 7. Seguir em frente — `/oxe-next` e ciclo
 
-1. Atualiza **`version`** em `package.json` (semver).  
-2. Garante **`repository`**, **`homepage`** e **`bugs`** corretos para o teu GitHub.  
-3. Conta npm com **2FA** ativa: `npm login`, depois **`npm publish --access public`**.  
-4. O script **`prepublishOnly`** corre testes + `scan:assets` + `--version` antes do upload.
+Para a **próxima** feature ou fase: de novo **spec → plan → …** ou **`/oxe-next`** para sugerir o passo lógico a partir de **STATE.md**.
 
-### Fork com outro nome no npm
+---
 
-1. Edita `package.json`: **`name`** (ex. `@tua-org/oxe-cc`) e **`repository.url`**.  
-2. `npm publish --access public` (scopes `@org/...` precisam de `--access public` na primeira publicação).
+## Modo rápido
 
-### CLI com nome personalizado
+Para trabalho **adhoc** sem roadmap completo — equivalente conceptual ao **`/gsd:quick`**:
 
-No `package.json`, o binário é o mapa **`bin`**: a chave é o comando no terminal, o valor é o script.
+**`/oxe-quick`** gera **`.oxe/QUICK.md`** com passos curtos e verificação. Depois podes usar **`/oxe-execute`** em cima disso ou implementar direto e fechar com **`/oxe-verify`**.
 
-```json
-"bin": {
-  "oxe-cc": "bin/oxe-cc.js",
-  "meu-oxe": "bin/oxe-cc.js"
-}
-```
+Se o trabalho crescer, **promove** para spec + plan completos.
 
-Depois de publicar, o comando extra fica disponível **globalmente** com `npm i -g nome-do-pacote` como `meu-oxe`. Com **npx**, o pacote continua a identificar-se pelo **`name`** em `package.json`; para correr um binário que não é o nome do pacote, usa por exemplo `npx -p oxe-cc meu-oxe` (ajusta `oxe-cc` / `meu-oxe` aos teus nomes).
+---
 
-O ficheiro do script (`bin/oxe-cc.js`) pode ser renomeado desde que atualizes o caminho no mapa `bin`.
+## Porque funciona
 
-**Desenvolvimento local sem publicar:** na pasta `oxe-build`, `npm link` e no projeto alvo `npm link oxe-cc`, depois `oxe-cc`; ou `node /caminho/para/oxe-build/bin/oxe-cc.js`. **Testes:** `npm test`. **Scan de assets (padrões tipo segredo em markdown):** `npm run scan:assets`.
+**Context engineering:** o agente não precisa de “lembrar” tudo na janela principal — o que importa está em ficheiros **pequenos e por etapa**.
 
-### Imagem / banner no início do CLI
+| Artefato | Função |
+|----------|--------|
+| `.oxe/STATE.md` | Fase, decisões, próximo passo — memória entre sessões |
+| `.oxe/codebase/*.md` | Mapa do repo após scan |
+| `.oxe/SPEC.md` | O que entregar e como saber que está certo |
+| `.oxe/DISCUSS.md` | Preferências antes do plano *(opcional)* |
+| `.oxe/PLAN.md` | Tarefas atómicas + **Verificar** por item |
+| `.oxe/QUICK.md` | Modo rápido |
+| `.oxe/VERIFY.md` | Resultado das verificações |
+| `oxe/workflows/*.md` | **Fonte única** dos passos (Cursor e Copilot só delegam aqui) |
 
-Ao correr `oxe-cc` (instalar, `doctor`, `init-oxe`, `--help`), aparece um **cabeçalho ASCII** vindo de [`bin/banner.txt`](bin/banner.txt). Podes **personalizar** editando esse ficheiro no teu fork antes de publicar no npm.
+**Formato:** planos em Markdown com secções fixas (incl. verificação), legíveis por humanos e por modelos — sem XML obrigatório, mas com a mesma ideia de *precise instructions + verify*.
 
-- Placeholder **`{version}`** — substituído pela versão do `package.json` (ex. `v0.3.0`).
-- **Cores:** em terminal TTY, o corpo usa ciano + negrito; a linha com a versão fica mais discreta. Define **`NO_COLOR`** (ou `FORCE_COLOR=0`) para saída só texto.
-- **Desligar o banner:** variável de ambiente **`OXE_NO_BANNER=1`** (útil em CI ou testes).
-- **`--version`** não mostra banner — só uma linha `oxe-cc v…` para scripts.
+---
 
-Para um “logo” mais elaborado, substitui o conteúdo de `banner.txt` pelo teu ASCII art (várias linhas, largura ~60 colunas costuma caber bem). Não é suportada imagem bitmap no terminal; para isso seria preciso outra ferramenta (ex. `terminal-image`) e dependências extra.
+## Comandos
 
-## Fonte única
+### Fluxo principal
 
-Os passos detalhados vivem em **`oxe/workflows/`** (`scan.md`, `spec.md`, `discuss.md`, `plan.md`, `quick.md`, `execute.md`, `verify.md`, `next.md`, `help.md`). Comandos Cursor, prompts Copilot e `commands/oxe/*` **delegam** para esses ficheiros.
+| 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 |
 
-Por omissão, após instalar, o CLI cria **`.oxe/`** mínimo: `STATE.md`, **`config.json`** (a partir de `oxe/templates/config.template.json`) e pasta **`codebase/`** — exceto com `--no-init-oxe`. Documentação das chaves: **`oxe/templates/CONFIG.md`**.
+### Modo rápido
 
-## Cursor
+| Comando | O que faz |
+|---------|-----------|
+| `/oxe-quick` | `.oxe/QUICK.md` — tarefa pontual |
 
-| Slash | Workflow |
-|-------|----------|
-| `/oxe-scan` | `oxe/workflows/scan.md` |
-| `/oxe-spec` | `oxe/workflows/spec.md` |
-| `/oxe-discuss` | `oxe/workflows/discuss.md` |
-| `/oxe-plan` | `oxe/workflows/plan.md` |
-| `/oxe-quick` | `oxe/workflows/quick.md` |
-| `/oxe-execute` | `oxe/workflows/execute.md` |
-| `/oxe-verify` | `oxe/workflows/verify.md` |
-| `/oxe-next` | `oxe/workflows/next.md` |
-| `/oxe-help` | `oxe/workflows/help.md` |
+### Revisão de PR / diff entre branches *(só Copilot)*
 
-Ficheiros: `.cursor/commands/oxe-*.md` e regra `.cursor/rules/oxe-workflow.mdc`.
+| 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. Podes 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 podes pedir o mesmo em linguagem natural com o workflow em contexto. |
 
-## GitHub Copilot
+### Outros clientes
 
-1. **Instruções do repositório** — [`.github/copilot-instructions.md`](.github/copilot-instructions.md): ativadas automaticamente no chat quando o repositório está em contexto (ver [documentação](https://docs.github.com/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)).
-2. **Prompt files** — [`.github/prompts/*.prompt.md`](.github/prompts/): no chat, escreve `/` e escolhe por exemplo **`oxe-scan`**, **`oxe-quick`**, **`oxe-execute`**, etc. (o `name` no frontmatter define o comando). Cada prompt referencia `oxe/workflows/<passo>.md` na **raiz do repo em contexto**.
+Em **Claude Code** (ou ferramentas que leem `commands/oxe/`), os mesmos passos expõem nomes **`oxe:scan`**, **`oxe:plan`**, etc. (frontmatter `name:`).
 
-Este repo inclui [`.vscode/settings.json`](.vscode/settings.json) com `"chat.promptFiles": true` para expor a pasta `.github/prompts`. Podes copiar essa definição para o teu `settings.json` global se preferires.
+---
 
-3. **Agentes** — [`AGENTS.md`](AGENTS.md) resume o pacote para modos que leem instruções de agente no repo.
+## Configuração
 
-## Fluxo recomendado
+Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Chaves e comportamento: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md) (ex.: `discuss_before_plan`, texto pós-verify, comando de teste por defeito).
 
-**Completo:** 1. **scan** (7 ficheiros em `codebase/`, incl. CONVENTIONS + CONCERNS) → 2. **spec** → 3. **discuss** (opcional; recomendado se `discuss_before_plan` em `.oxe/config.json`) → 4. **plan** (secção **Replanejamento** em `--replan`) → 5. **execute** (opcional) → 6. implementar → 7. **verify** (rascunho de commit + checklist PR se ativo em config) → 8. **next**.
+---
 
-**Rápido (tarefas pequenas):** **quick** gera `.oxe/QUICK.md` com passos curtos + verificação; depois **execute** (sobre o QUICK) ou implementação direta e **verify**. Promover a spec/plan se o trabalho crescer (muitos ficheiros, API pública, segurança).
+## Resolução de problemas
 
-## Artefatos (`.oxe/` no projeto alvo)
+| Situação | O que tentar |
+|----------|----------------|
+| Comandos não aparecem no Cursor | Confirma que `.cursor/commands/` existe; reinicia o Cursor |
+| Prompts `/oxe-*` não aparecem no Copilot | Ativa `"chat.promptFiles": true`; confirma `.github/prompts/*.prompt.md` |
+| Slash `/oxe-*` no **Copilot CLI** | Instala com **`--copilot-cli`** (pasta `.claude/commands/`); atualiza o CLI; comportamento ainda experimental |
+| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixa versão: `npx oxe-cc@0.3.0`. Verifica `npm config get registry` |
+| **404** no `npm view oxe-cc` | Pacote com outro nome (scope) ou ainda não publicado — usa `npm link` ou `node …/bin/oxe-cc.js` |
+| Ficheiros não atualizam | Reinstala com **`--force`** |
 
-| Caminho | Conteúdo |
-|---------|----------|
-| `.oxe/STATE.md` | Fase, último scan, próximo passo |
-| `.oxe/config.json` | Opcional (criado no bootstrap): `discuss_before_plan`, texto de verify pós-sucesso, comando de teste por defeito — ver `oxe/templates/CONFIG.md` |
-| `.oxe/codebase/*.md` | Mapa: OVERVIEW, STACK, STRUCTURE, TESTING, INTEGRATIONS, **CONVENTIONS**, **CONCERNS** |
-| `.oxe/SPEC.md` | Especificação |
-| `.oxe/DISCUSS.md` | Perguntas e decisões antes do plano (opcional) |
-| `.oxe/PLAN.md` | Plano com **Verificar** por tarefa + secção **Replanejamento** |
-| `.oxe/QUICK.md` | Modo rápido: passos curtos + verificar |
-| `.oxe/VERIFY.md` | Resultado das verificações |
-| `.oxe/SUMMARY.md` | Resumo de sessão / contexto para replan (opcional) |
+**Ajuda no terminal:** `oxe-cc --help`. **Diagnóstico:** `oxe-cc doctor`.
 
-Templates: **`oxe/templates/`** (`STATE.md`, `config.template.json`, `CONFIG.md`, `SPEC.template.md`, `PLAN.template.md`, `SUMMARY.template.md`).
+**Banner no CLI:** [`bin/banner.txt`](bin/banner.txt) (`{version}`). `OXE_NO_BANNER=1` desliga; `NO_COLOR` remove cores.
 
-Neste repositório, **`.oxe/` está no `.gitignore`** para não versionar scans locais do *oxe-build*. No teu produto, remove ou ajusta essa regra se quiseres commitar `.oxe/` com a equipa.
+<details>
+<summary><strong>Publicar no npm (mantenedores)</strong></summary>
 
-## Usar noutro projeto
+Sobe `version` em `package.json`, `npm login` (2FA se exigido), `npm publish --access public`. O `prepublishOnly` corre testes e `scan:assets`.
 
-- Com pacote no npm: **`npx oxe-cc@latest`** na raiz do repo alvo, ou **`npx oxe-cc@<versão>`** (versões na [página do pacote](https://www.npmjs.com/package/oxe-cc?activeTab=versions) quando existir).
-- Sem pacote no npm: **`npm link oxe-cc`** (após `npm link` no clone do `oxe-build`) ou **`node …/oxe-build/bin/oxe-cc.js`**.
+</details>
 
-Alternativa manual: copia os mesmos caminhos que o instalador usa (`oxe/`, `.cursor/`, `.github/`, `commands/oxe`, `AGENTS.md`, opcionalmente `.vscode/settings.json` ou só `"chat.promptFiles": true` nas definições).
+<details>
+<summary><strong>Estrutura do repositório</strong></summary>
 
-`commands/oxe/*.md` mantém frontmatter estilo GSD (`name: oxe:scan`, …) para ferramentas que importam comandos nesse formato.
+| Caminho | Função |
+|---------|--------|
+| `assets/readme-banner.svg` | Banner deste README |
+| `bin/oxe-cc.js`, `bin/banner.txt` | CLI |
+| `oxe/workflows/` | Workflows canónicos |
+| `oxe/templates/` | Modelos e CONFIG |
+| `.cursor/`, `.github/` | Cursor e Copilot |
+| `commands/oxe/` | `oxe:*` para outros runtimes |
+| `tests/`, `scripts/`, `.github/workflows/` | CI e qualidade |
 
-## Estrutura deste repositório
+</details>
 
-| Pasta / ficheiro | Função |
-|------------------|--------|
-| `bin/oxe-cc.js` | CLI: instalar, `doctor`, `init-oxe` |
-| `bin/banner.txt` | Cabeçalho ASCII ao arrancar o CLI (`{version}`) |
-| `package.json` | Metadados npm (`oxe-cc`, `files`, `bin`) |
-| `oxe/workflows/` | Workflows canónicos (fonte única) |
-| `oxe/templates/` | Modelos (STATE, config, SPEC, PLAN, SUMMARY, CONFIG.md) |
-| `scripts/oxe-assets-scan.cjs` | Verificação leve de padrões sensíveis em markdown (CI / `npm run scan:assets`) |
-| `.github/workflows/ci.yml` | `npm test` + `scan:assets` |
-| `.cursor/commands/` | Slash commands Cursor |
-| `.cursor/rules/` | Regras do projeto Cursor |
-| `.github/copilot-instructions.md` | Instruções Copilot no repo |
-| `.github/prompts/` | Ficheiros `*.prompt.md` (`/oxe-scan`, …) |
-| `commands/oxe/` | Comandos com frontmatter estilo GSD |
-| `AGENTS.md` | Resumo para agentes (ex. Copilot) |
+---
 
 ## Licença
 
-[GPL-3.0](LICENSE) — ver [LICENSE](LICENSE).
+[GPL-3.0](LICENSE).

package/assets/readme-banner.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="200" viewBox="0 0 920 200" role="img" aria-label="OXE  spec-driven workflows">
+  <defs>
+    <linearGradient id="oxe-bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0d1117"/>
+      <stop offset="50%" style="stop-color:#161b22"/>
+      <stop offset="100%" style="stop-color:#21262d"/>
+    </linearGradient>
+    <linearGradient id="oxe-accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#58a6ff"/>
+      <stop offset="100%" style="stop-color:#79c0ff"/>
+    </linearGradient>
+  </defs>
+  <rect width="920" height="200" rx="16" fill="url(#oxe-bg)"/>
+  <rect x="2" y="2" width="916" height="196" rx="14" fill="none" stroke="url(#oxe-accent)" stroke-width="2" opacity="0.45"/>
+  <text x="460" y="100" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="72" font-weight="800" fill="url(#oxe-accent)" letter-spacing="0.12em">OXE</text>
+  <text x="460" y="138" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="17" fill="#8b949e">Fluxo spec-driven � Cursor &amp; GitHub Copilot � CLI npm</text>
+  <text x="460" y="168" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="13" fill="#6e7681">npx oxe-cc@latest</text>
+</svg>

package/bin/banner.txt

@@ -15,4 +15,4 @@
 
 ══════════════════════════════════════════════════════
 
-                      v0.3.1
+                      v0.3.3

package/bin/oxe-cc.js

@@ -9,6 +9,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
+const { spawnSync } = require('child_process');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -20,6 +22,9 @@ const red = '\x1b[31m';
 const bold = '\x1b[1m';
 const reset = '\x1b[0m';
 
+/** @type {string} */
+const RULE = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━';
+
 /** Plain banner if banner.txt is missing (keep in sync with bin/banner.txt style). */
 const DEFAULT_BANNER = `   .============================================.
    |     OXE     ·  spec-driven workflow CLI    |
@@ -34,6 +39,18 @@ function useAnsiColors() {
   return process.stdout.isTTY === true;
 }
 
+/** Section header (GSD-inspired). */
+function printSection(title) {
+  const c = useAnsiColors();
+  if (!c) {
+    console.log(`\n${title}\n${'─'.repeat(50)}\n`);
+    return;
+  }
+  console.log(`\n${dim}${RULE}${reset}`);
+  console.log(`  ${cyan}${bold}${title}${reset}`);
+  console.log(`${dim}${RULE}${reset}\n`);
+}
+
 /** Print branded header; skip with OXE_NO_BANNER=1. Not used for --version (scripts). */
 function printBanner() {
   if (process.env.OXE_NO_BANNER === '1' || process.env.OXE_NO_BANNER === 'true') return;
@@ -49,6 +66,7 @@ function printBanner() {
     }
   }
   const text = raw.replace(/\{version\}/g, ver).replace(/\r\n/g, '\n').trimEnd();
+  if (color) console.log(`${dim}${RULE}${reset}\n`);
   if (!color) {
     console.log(text + '\n');
     return;
@@ -58,10 +76,11 @@ function printBanner() {
     if (line.includes(`v${ver}`)) console.log(`${dim}${line}${reset}`);
     else console.log(`${cyan}${bold}${line}${reset}`);
   }
-  console.log('');
+  if (color) console.log(`\n${dim}${RULE}${reset}\n`);
+  else console.log('');
 }
 
-/** @typedef {{ help: boolean, version: boolean, cursor: boolean, copilot: boolean, vscode: boolean, commands: boolean, agents: boolean, force: boolean, dryRun: boolean, dir: string, all: boolean, noInitOxe: boolean, oxeOnly: boolean, parseError: boolean, unknownFlag: string }} InstallOpts */
+/** @typedef {{ help: boolean, version: boolean, cursor: boolean, copilot: boolean, copilotCli: boolean, vscode: boolean, commands: boolean, agents: boolean, force: boolean, dryRun: boolean, dir: string, all: boolean, noInitOxe: boolean, oxeOnly: boolean, globalCli: boolean, noGlobalCli: boolean, parseError: boolean, unknownFlag: string, conflictFlags: string }} InstallOpts */
 
 /**
  * @param {string[]} argv
@@ -74,6 +93,7 @@ function parseInstallArgs(argv) {
     version: false,
     cursor: false,
     copilot: false,
+    copilotCli: false,
     vscode: false,
     commands: true,
     agents: true,
@@ -83,8 +103,11 @@ function parseInstallArgs(argv) {
     all: false,
     noInitOxe: false,
     oxeOnly: false,
+    globalCli: false,
+    noGlobalCli: false,
     parseError: false,
     unknownFlag: '',
+    conflictFlags: '',
     restPositional: [],
   };
   for (let i = 0; i < argv.length; i++) {
@@ -93,6 +116,7 @@ function parseInstallArgs(argv) {
     else if (a === '-v' || a === '--version') out.version = true;
     else if (a === '--cursor') out.cursor = true;
     else if (a === '--copilot') out.copilot = true;
+    else if (a === '--copilot-cli') out.copilotCli = true;
     else if (a === '--vscode') out.vscode = true;
     else if (a === '--no-commands') out.commands = false;
     else if (a === '--no-agents') out.agents = false;
@@ -101,22 +125,28 @@ function parseInstallArgs(argv) {
     else if (a === '--all' || a === '-a') out.all = true;
     else if (a === '--no-init-oxe') out.noInitOxe = true;
     else if (a === '--oxe-only') out.oxeOnly = true;
+    else if (a === '--global-cli' || a === '-g') out.globalCli = true;
+    else if (a === '--no-global-cli' || a === '-l') out.noGlobalCli = true;
     else if (a === '--dir' && argv[i + 1]) {
       out.dir = path.resolve(argv[++i]);
-    } else if (!a.startsWith('-')) out.restPositional.push(a);
+    }     else if (!a.startsWith('-')) out.restPositional.push(a);
     else {
       out.parseError = true;
       out.unknownFlag = a;
       break;
     }
   }
+  if (out.globalCli && out.noGlobalCli) {
+    out.conflictFlags = 'Cannot use both --global-cli (-g) and --no-global-cli (-l)';
+  }
   if (out.oxeOnly) {
     out.cursor = false;
     out.copilot = false;
+    out.copilotCli = false;
     out.vscode = false;
     out.commands = false;
     out.agents = false;
-  } else if (out.all || (!out.cursor && !out.copilot)) {
+  } else if (out.all || (!out.cursor && !out.copilot && !out.copilotCli)) {
     out.cursor = true;
     out.copilot = true;
   }
@@ -134,6 +164,16 @@ function readPkgVersion() {
   }
 }
 
+function readPkgName() {
+  try {
+    const p = path.join(PKG_ROOT, 'package.json');
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return typeof j.name === 'string' ? j.name : 'oxe-cc';
+  } catch {
+    return 'oxe-cc';
+  }
+}
+
 function readMinNode() {
   try {
     const p = path.join(PKG_ROOT, 'package.json');
@@ -228,10 +268,12 @@ function bootstrapOxe(target, opts) {
 
 /** @param {string} target */
 function runDoctor(target) {
+  printSection('OXE ▸ doctor');
   const v = process.versions.node;
   const major = parseInt(v.split('.')[0], 10);
   const minNode = readMinNode();
-  console.log(`${cyan}oxe-cc doctor${reset} — ${target}`);
+  const c = useAnsiColors();
+  console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
   console.log(`Node.js ${v} (require >= ${minNode})`);
   if (major < minNode) {
     console.log(`${red}FAIL${reset} Node.js version below package engines`);
@@ -310,6 +352,87 @@ function runDoctor(target) {
   console.log(`\n${green}Doctor finished.${reset}`);
 }
 
+/**
+ * npm install -g oxe-cc@version (same version as this running CLI).
+ * @returns {boolean}
+ */
+function installGlobalCliPackage() {
+  const name = readPkgName();
+  const ver = readPkgVersion();
+  const spec = `${name}@${ver}`;
+  const c = useAnsiColors();
+  const dimOrEmpty = c ? dim : '';
+  const resetOrEmpty = c ? reset : '';
+  console.log(`\n  ${dimOrEmpty}npm install -g ${spec}${resetOrEmpty}\n`);
+  const r = spawnSync('npm', ['install', '-g', spec], {
+    stdio: 'inherit',
+    shell: true,
+    env: process.env,
+  });
+  if (r.status === 0) {
+    console.log(
+      `\n  ${c ? green : ''}✓${c ? reset : ''} ${c ? cyan : ''}oxe-cc${c ? reset : ''} disponível globalmente (corre ${c ? cyan : ''}oxe-cc --help${c ? reset : ''} em qualquer pasta).\n`
+    );
+    return true;
+  }
+  console.log(
+    `\n  ${c ? yellow : ''}⚠${c ? reset : ''} npm install -g falhou. Tenta manualmente: ${c ? cyan : ''}npm install -g ${spec}${c ? reset : ''}\n`
+  );
+  return false;
+}
+
+/**
+ * After copying OXE into the project: optionally install the CLI globally (like GSD’s “where to install” choice).
+ * @param {InstallOpts} opts
+ */
+function maybePromptGlobalCli(opts) {
+  if (opts.oxeOnly) return;
+  if (opts.dryRun) {
+    if (useAnsiColors()) console.log(`${dim}  (dry-run — pergunta do CLI global ignorada)${reset}`);
+    return;
+  }
+  if (opts.globalCli) {
+    installGlobalCliPackage();
+    return;
+  }
+  if (opts.noGlobalCli) return;
+  if (process.env.OXE_NO_PROMPT === '1' || process.env.OXE_NO_PROMPT === 'true') return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const c = useAnsiColors();
+    if (c) {
+      console.log(
+        `\n  ${yellow}Terminal não interativo${reset} — sem pergunta de CLI global. Usa ${cyan}npx oxe-cc@latest${reset} ou ${cyan}--global-cli${reset}.\n`
+      );
+    } else {
+      console.log('\nNon-interactive terminal — skipping global CLI prompt. Use npx oxe-cc@latest or --global-cli.\n');
+    }
+    return;
+  }
+
+  const c = useAnsiColors();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log(
+    `  ${c ? yellow : ''}Instalar o comando oxe-cc globalmente?${c ? reset : ''}
+  (Os ficheiros OXE já foram copiados para o projeto.)
+
+  ${c ? cyan : ''}1${c ? reset : ''}) ${c ? dim : ''}Não — uso ${c ? reset : ''}${c ? cyan : ''}npx oxe-cc@latest${c ? reset : ''}${c ? dim : ''} para atualizar (recomendado em CI)${c ? reset : ''}
+  ${c ? cyan : ''}2${c ? reset : ''}) ${c ? dim : ''}Sim — ${c ? reset : ''}${c ? cyan : ''}npm install -g ${readPkgName()}@${readPkgVersion()}${c ? reset : ''}${c ? dim : ''} (${c ? reset : ''}${c ? cyan : ''}oxe-cc${c ? reset : ''}${c ? dim : ''} no PATH)${c ? reset : ''}
+`
+  );
+
+  rl.question(`  ${c ? cyan : ''}Escolha${c ? reset : ''} ${c ? dim : ''}[1]${c ? reset : ''}: `, (answer) => {
+    rl.close();
+    const choice = (answer || '1').trim();
+    if (choice === '2') installGlobalCliPackage();
+    else {
+      console.log(
+        `\n  ${c ? green : ''}✓${c ? reset : ''} Para atualizar workflows: ${c ? cyan : ''}npx oxe-cc@latest --force${c ? reset : ''} na raiz do projeto.\n`
+      );
+    }
+  });
+}
+
 function usage() {
   console.log(`
 ${cyan}oxe-cc${reset} — install OXE workflows (Cursor + GitHub Copilot) into a project
@@ -323,12 +446,15 @@ ${green}Usage:${reset}
 ${green}Install options:${reset}
   --cursor       Install .cursor/commands and .cursor/rules (default with --all)
   --copilot      Install .github/copilot-instructions.md and .github/prompts
+  --copilot-cli  Copy .cursor/commands → .claude/commands (Copilot CLI slash /oxe-* — experimental)
   --vscode       Also copy .vscode/settings.json (chat.promptFiles)
   --all, -a      Cursor + Copilot (default when neither --cursor nor --copilot)
   --no-commands  Skip commands/oxe (Claude-style frontmatter)
   --no-agents    Skip AGENTS.md
   --no-init-oxe  Do not create .oxe/STATE.md + .oxe/codebase/ after install
   --oxe-only     Only copy oxe/ (skip Cursor, Copilot, commands, AGENTS.md)
+  --global-cli, -g   After install: npm install -g oxe-cc@<version> (no prompt)
+  --no-global-cli, -l  Skip the interactive “CLI global?” step (default in CI)
   --force, -f    Overwrite existing files
   --dry-run      Print actions without writing
   --dir <path>   Target directory (default: cwd)
@@ -344,6 +470,7 @@ ${green}Examples:${reset}
   npx oxe-cc@latest
   npx oxe-cc@latest ./my-app
   npx oxe-cc@latest --cursor --dry-run
+  npx oxe-cc@latest --copilot --copilot-cli
   npx oxe-cc doctor
   npx oxe-cc init-oxe --dir ./my-app
 `);
@@ -356,8 +483,10 @@ function runInstall(opts) {
     process.exit(1);
   }
 
-  console.log(`${cyan}OXE${reset} install → ${green}${target}${reset}`);
-  if (opts.dryRun) console.log(`${yellow}(dry-run)${reset}`);
+  printSection('OXE ▸ Copiar workflows para o projeto');
+  const c = useAnsiColors();
+  console.log(`  ${c ? green : ''}Destino:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
+  if (opts.dryRun) console.log(`  ${c ? yellow : ''}(dry-run)${c ? reset : ''}`);
 
   const copyOpts = { dryRun: opts.dryRun, force: opts.force };
 
@@ -370,6 +499,20 @@ function runInstall(opts) {
     if (fs.existsSync(cRules)) copyDir(cRules, path.join(target, '.cursor', 'rules'), copyOpts);
   }
 
+  if (opts.copilotCli) {
+    const cCmd = path.join(PKG_ROOT, '.cursor', 'commands');
+    const dest = path.join(target, '.claude', 'commands');
+    const c = useAnsiColors();
+    if (fs.existsSync(cCmd)) {
+      console.log(
+        `  ${c ? green : ''}cli${c ? reset : ''}   ${c ? dim : ''}Copilot CLI:${c ? reset : ''} ${c ? cyan : ''}.claude/commands/${c ? reset : ''}${c ? dim : ''} (experimental — teste /oxe-scan na sessão)${c ? reset : ''}`
+      );
+      copyDir(cCmd, dest, copyOpts);
+    } else {
+      console.warn(`${yellow}warn:${reset} missing ${cCmd} — skip --copilot-cli`);
+    }
+  }
+
   if (opts.copilot) {
     const gh = path.join(PKG_ROOT, '.github');
     const inst = path.join(gh, 'copilot-instructions.md');
@@ -416,7 +559,7 @@ function runInstall(opts) {
   if (!opts.noInitOxe) bootstrapOxe(target, { dryRun: opts.dryRun, force: opts.force });
 
   console.log(
-    `\n${green}Done.${reset} Open the project in Cursor (${cyan}/oxe-scan${reset}) or VS Code + Copilot (prompt ${cyan}/oxe-scan${reset}).`
+    `\n  ${c ? green : ''}✓${c ? reset : ''} Ficheiros OXE instalados. Abre no Cursor (${c ? cyan : ''}/oxe-scan${c ? reset : ''}) ou VS Code + Copilot (prompt ${c ? cyan : ''}/oxe-scan${c ? reset : ''}).`
   );
 }
 
@@ -435,6 +578,13 @@ function main() {
     process.exit(0);
   }
 
+  if (opts.conflictFlags) {
+    printBanner();
+    console.error(`${red}${opts.conflictFlags}${reset}`);
+    usage();
+    process.exit(1);
+  }
+
   if (opts.parseError) {
     printBanner();
     console.error(`${red}Unknown option:${reset} ${opts.unknownFlag}`);
@@ -465,14 +615,17 @@ function main() {
       console.error(`${yellow}Target directory does not exist: ${target}${reset}`);
       process.exit(1);
     }
-    console.log(`${cyan}OXE${reset} init-oxe → ${green}${target}${reset}`);
-    if (opts.dryRun) console.log(`${yellow}(dry-run)${reset}`);
+    printSection('OXE ▸ init-oxe');
+    const c0 = useAnsiColors();
+    console.log(`  ${c0 ? green : ''}Destino:${c0 ? reset : ''} ${c0 ? cyan : ''}${target}${c0 ? reset : ''}`);
+    if (opts.dryRun) console.log(`  ${c0 ? yellow : ''}(dry-run)${c0 ? reset : ''}`);
     bootstrapOxe(target, { dryRun: opts.dryRun, force: opts.force });
-    console.log(`\n${green}Done.${reset}`);
+    console.log(`\n  ${c0 ? green : ''}✓${c0 ? reset : ''} Concluído.\n`);
     return;
   }
 
   runInstall(opts);
+  maybePromptGlobalCli(opts);
 }
 
 main();

package/oxe/workflows/help.md

@@ -16,7 +16,7 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 ## GitHub Copilot (VS Code / IDE)
 
 1. **Instruções do repositório:** `.github/copilot-instructions.md` (ativas no chat quando o repositório está em contexto).
-2. **Prompt files:** no chat, escrever `/` e escolher **`oxe-scan`**, **`oxe-spec`**, **`oxe-discuss`**, **`oxe-plan`**, **`oxe-verify`**, **`oxe-next`**, **`oxe-quick`**, **`oxe-execute`**, **`oxe-help`**. Requer `chat.promptFiles`: true.
+2. **Prompt files:** no chat, escrever `/` e escolher **`oxe-scan`**, **`oxe-spec`**, **`oxe-discuss`**, **`oxe-plan`**, **`oxe-verify`**, **`oxe-next`**, **`oxe-quick`**, **`oxe-execute`**, **`oxe-help`**, **`oxe-review-pr`** (revisão: URL `github.com/.../pull/N`, branches ou SHAs). Requer `chat.promptFiles`: true.
 
 ## Fluxo completo
 
@@ -46,5 +46,9 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 
 ## Gatilhos naturais (Copilot / chat)
 
-Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, “revisar PR”, “diff entre branches”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+
+**Nota:** **`oxe-review-pr`** não tem homólogo em `.cursor/commands/`; no Cursor podes pedir em linguagem natural seguindo `oxe/workflows/review-pr.md` ou abrir o mesmo ficheiro como contexto.
+
+**Copilot CLI (experimental):** `oxe-cc --copilot-cli` copia os mesmos Markdown de `.cursor/commands/` para **`.claude/commands/`** — para testar **`/oxe-scan`**, etc., conforme a versão do GitHub Copilot CLI.
 </output>

package/oxe/workflows/review-pr.md

@@ -0,0 +1,45 @@
+# OXE — Workflow: review-pr (revisão de diff / PR)
+
+<objective>
+Rever alterações como num pull request: **URL do GitHub** (`…/pull/<n>`), **branches** ou **SHAs**. Cobre diff, risco, convenções do projeto e sugestões acionáveis. **Não** substitui CI nem testes manuais; complementa-os.
+</objective>
+
+<context>
+- **Base** e **head** são nomes de branch, tags ou SHAs (ex.: `main` e `feature/foo`).
+- **URL de PR no GitHub** — O utilizador pode colar o link da PR (ex.: `https://github.com/org/repo/pull/10` ou atalho `org/repo#10`). O número da PR é o segmento depois de `/pull/`.
+- Em Git, o diff “estilo PR” (só o que a branch introduz) usa o **merge base**: `git diff base...head` (três pontos).
+- Diff literal entre pontas: `git diff base..head` (dois pontos) — útil quando o utilizador pede explicitamente.
+- Este passo é **opcional** no fluxo OXE; não atualiza `STATE.md` com fases canónicas, salvo o utilizador pedir registo do resultado em disco.
+</context>
+
+<process>
+1. **Resolver entrada**
+   - **URL ou `#` de PR** — Se a mensagem contiver um URL `github.com/.../pull/<n>` (com ou sem `https://`, com sufixo `/files` ou `/commits`) ou texto `owner/repo#n`, extrair `<n>` (e opcionalmente `owner/repo` para confirmar que o clone local é o mesmo repositório).
+   - **Refs explícitas** — Caso contrário, tratar como base/head: se faltar um dos dois, inferir base = `main` ou `master` (o que existir) e head = branch atual (`git rev-parse --abbrev-ref HEAD`), ou pedir clarificação.
+2. **Obter diff (com URL / número de PR)** — Ordem de preferência quando o cwd é o repositório certo:
+   - **GitHub CLI:** `gh pr diff <n>` (ou `gh pr diff <n> --patch`). Se `gh` não estiver disponível ou falhar auth, tentar Git puro.
+   - **Git fetch ref da PR:** `git fetch origin pull/<n>/head:oxe-pr-<n>` (ajustar `origin` se o remoto tiver outro nome). Descobrir branch base com `gh pr view <n> --json baseRefName -q .baseRefName` ou assumir `main`/`master`; depois `git diff origin/<base>...oxe-pr-<n>` ou `git diff <base>...oxe-pr-<n>` após `fetch` da base.
+   - **Sem terminal / outro repo:** Pedir ao utilizador que cole o diff da aba “Files changed” no GitHub ou o output de `gh pr diff <n>` corrido localmente no repo certo.
+3. **Obter diff (só branches / SHAs)** — Preferir terminal quando disponível:
+   - `git fetch` (se fizer sentido e o ambiente permitir rede).
+   - `git merge-base base head` (opcional, para confirmar ancestral comum).
+   - `git diff base...head` (revisão tipo PR).
+   - `git log base..head --oneline -n 30` (contexto de commits).
+   Se o sandbox bloquear Git, pedir ao utilizador que cole o output de `git diff base...head` ou use o diff da UI do GitHub/GitLab.
+   Se o diff já foi obtido no passo 2 (URL da PR), **não** repetir este passo.
+4. **Ler contexto do projeto** — Se existirem, usar trechos relevantes de `.oxe/codebase/CONVENTIONS.md`, `STACK.md`, `OVERVIEW.md` e, se aplicável, `.oxe/SPEC.md` / `.oxe/PLAN.md` para alinhar expectativas (sem assumir que o PR cobre só OXE).
+5. **Analisar** — Estruturar a resposta com:
+   - **Resumo** — O que muda em 3–6 frases.
+   - **Ficheiros / áreas** — Agrupar por domínio (API, UI, config, etc.).
+   - **Riscos** — Regressões, breaking changes, segurança (inputs, segredos, auth), performance óbvia, migrações.
+   - **Testes** — O que deveria ser coberto ou correr localmente (comandos sugeridos se conhecidos do repo).
+   - **Checklist PR** — Título sugerido, descrição curta, breaking changes, rollback.
+6. **Opcional em disco** — Se o utilizador pedir registo: criar ou atualizar **`.oxe/PR-REVIEW.md`** com data, URL ou refs (base/head), resumo, achados e próximos passos (formato Markdown legível).
+</process>
+
+<success>
+- [ ] URL da PR ou par base/head está explícito na resposta (ou foi pedida clarificação).
+- [ ] A análise baseia-se no diff (terminal ou colado), não só em suposições.
+- [ ] Há secção de riscos e de testes/verificação sugerida.
+- [ ] Nenhum segredo ou credencial é repetido na análise; redigir se aparecerem no diff.
+</success>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "OXE — spec-driven workflows for Cursor and GitHub Copilot (install via npx)",
   "license": "GPL-3.0",
   "author": "",
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "oxe",
+    "assets",
     ".cursor",
     ".github",
     "commands",