oxe-cc 0.3.0

package/README.md

@@ -0,0 +1,206 @@
+# oxe-build
+
+[![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)
+
+*(O badge de versão só reflete uma release real depois de `npm publish` concluído com sucesso.)*
+
+Fluxo **spec-driven** enxuto (inspirado em context engineering / GSD), com prefixo **OXE** e artefatos em **`.oxe/`**.
+
+Os alvos **iniciais** são **Cursor** e **GitHub Copilot** (VS Code e IDEs compatíveis). Outros clientes podem usar os mesmos workflows em Markdown.
+
+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.
+
+## Instalação (escolhe uma)
+
+Precisas de **Node.js 18+**. O executável chama-se **`oxe-cc`**.
+
+### 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
+```
+
+Ou, sem `link`, apontando ao script:
+
+```bash
+node C:\caminho\para\oxe-build\bin\oxe-cc.js
+```
+
+### B) Depois de publicado no npm
+
+```bash
+cd /caminho/do/teu-projeto
+npx oxe-cc@latest
+```
+
+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).
+
+### 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:
+
+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.
+
+Até o 404 desaparecer, usa a opção **A** (`npm link` ou `node …/bin/oxe-cc.js`).
+
+Opções úteis:
+
+| 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 |
+
+**Subcomandos:**
+
+| 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/` |
+
+A pasta **`oxe/`** (workflows + templates) é **sempre** copiada na instalação normal. `--cursor` / `--copilot` apenas controlam se entram ficheiros em `.cursor/` e `.github/`.
+
+Instalação global (só depois do pacote existir no npm): `npm install -g oxe-cc`.
+
+### Nova versão no npm (mantenedores)
+
+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.
+
+### 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).
+
+### CLI com nome personalizado
+
+No `package.json`, o binário é o mapa **`bin`**: a chave é o comando no terminal, o valor é o script.
+
+```json
+"bin": {
+  "oxe-cc": "bin/oxe-cc.js",
+  "meu-oxe": "bin/oxe-cc.js"
+}
+```
+
+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`.
+
+**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`.
+
+### Imagem / banner no início do CLI
+
+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.
+
+- 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.
+
+## Fonte única
+
+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.
+
+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`**.
+
+## Cursor
+
+| 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` |
+
+Ficheiros: `.cursor/commands/oxe-*.md` e regra `.cursor/rules/oxe-workflow.mdc`.
+
+## GitHub Copilot
+
+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**.
+
+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.
+
+## Fluxo recomendado
+
+**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).
+
+## Artefatos (`.oxe/` no projeto alvo)
+
+| 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) |
+
+Templates: **`oxe/templates/`** (`STATE.md`, `config.template.json`, `CONFIG.md`, `SPEC.template.md`, `PLAN.template.md`, `SUMMARY.template.md`).
+
+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.
+
+## Usar noutro projeto
+
+- 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`**.
+
+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).
+
+`commands/oxe/*.md` mantém frontmatter estilo GSD (`name: oxe:scan`, …) para ferramentas que importam comandos nesse formato.
+
+## Estrutura deste repositório
+
+| 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).

package/bin/banner.txt

@@ -0,0 +1,5 @@
+   .============================================.
+   |     OXE     ·  spec-driven workflow CLI    |
+   |     Cursor  ·  GitHub Copilot              |
+   '============================================'
+                    v{version}

package/bin/oxe-cc.js

@@ -0,0 +1,473 @@
+#!/usr/bin/env node
+/**
+ * OXE — install workflows into a target project; bootstrap `.oxe/`; doctor.
+ * Usage:
+ *   npx oxe-cc [options] [target-dir]
+ *   npx oxe-cc doctor [options] [target-dir]
+ *   npx oxe-cc init-oxe [options] [target-dir]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const red = '\x1b[31m';
+const bold = '\x1b[1m';
+const reset = '\x1b[0m';
+
+/** Plain banner if banner.txt is missing (keep in sync with bin/banner.txt style). */
+const DEFAULT_BANNER = `   .============================================.
+   |     OXE     ·  spec-driven workflow CLI    |
+   |     Cursor  ·  GitHub Copilot              |
+   '============================================'
+                    v{version}
+`;
+
+function useAnsiColors() {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR === '0') return false;
+  return process.stdout.isTTY === true;
+}
+
+/** 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;
+  const color = useAnsiColors();
+  const ver = readPkgVersion();
+  const bannerPath = path.join(PKG_ROOT, 'bin', 'banner.txt');
+  let raw = DEFAULT_BANNER;
+  if (fs.existsSync(bannerPath)) {
+    try {
+      raw = fs.readFileSync(bannerPath, 'utf8');
+    } catch {
+      /* keep default */
+    }
+  }
+  const text = raw.replace(/\{version\}/g, ver).replace(/\r\n/g, '\n').trimEnd();
+  if (!color) {
+    console.log(text + '\n');
+    return;
+  }
+  const lines = text.split('\n');
+  for (const line of lines) {
+    if (line.includes(`v${ver}`)) console.log(`${dim}${line}${reset}`);
+    else console.log(`${cyan}${bold}${line}${reset}`);
+  }
+  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 */
+
+/**
+ * @param {string[]} argv
+ * @returns {InstallOpts & { restPositional: string[] }}
+ */
+function parseInstallArgs(argv) {
+  /** @type {InstallOpts & { restPositional: string[] }} */
+  const out = {
+    help: false,
+    version: false,
+    cursor: false,
+    copilot: false,
+    vscode: false,
+    commands: true,
+    agents: true,
+    force: false,
+    dryRun: false,
+    dir: process.cwd(),
+    all: false,
+    noInitOxe: false,
+    oxeOnly: false,
+    parseError: false,
+    unknownFlag: '',
+    restPositional: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.help = true;
+    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 === '--vscode') out.vscode = true;
+    else if (a === '--no-commands') out.commands = false;
+    else if (a === '--no-agents') out.agents = false;
+    else if (a === '--force' || a === '-f') out.force = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    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 === '--dir' && argv[i + 1]) {
+      out.dir = path.resolve(argv[++i]);
+    } else if (!a.startsWith('-')) out.restPositional.push(a);
+    else {
+      out.parseError = true;
+      out.unknownFlag = a;
+      break;
+    }
+  }
+  if (out.oxeOnly) {
+    out.cursor = false;
+    out.copilot = false;
+    out.vscode = false;
+    out.commands = false;
+    out.agents = false;
+  } else if (out.all || (!out.cursor && !out.copilot)) {
+    out.cursor = true;
+    out.copilot = true;
+  }
+  if (out.restPositional.length) out.dir = path.resolve(out.restPositional[0]);
+  return out;
+}
+
+function readPkgVersion() {
+  try {
+    const p = path.join(PKG_ROOT, 'package.json');
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return j.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function readMinNode() {
+  try {
+    const p = path.join(PKG_ROOT, 'package.json');
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const eng = j.engines && j.engines.node;
+    if (!eng || typeof eng !== 'string') return 18;
+    const m = eng.match(/>=?\s*(\d+)/);
+    return m ? parseInt(m[1], 10) : 18;
+  } catch {
+    return 18;
+  }
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+/** @param {string} src @param {string} dest @param {{ dryRun: boolean }} opts */
+function copyFile(src, dest, opts) {
+  if (opts.dryRun) {
+    console.log(`${dim}file${reset}  ${src} → ${dest}`);
+    return;
+  }
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+/** @param {string} srcDir @param {string} destDir @param {{ dryRun: boolean, force: boolean }} opts */
+function copyDir(srcDir, destDir, opts) {
+  if (!fs.existsSync(srcDir)) return;
+  ensureDir(destDir);
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path.join(srcDir, e.name);
+    const d = path.join(destDir, e.name);
+    if (e.isDirectory()) copyDir(s, d, opts);
+    else {
+      if (fs.existsSync(d) && !opts.force) {
+        console.log(`${dim}skip${reset} ${d} (exists, use --force)`);
+        continue;
+      }
+      if (opts.dryRun) console.log(`${dim}file${reset}  ${s} → ${d}`);
+      else {
+        ensureDir(path.dirname(d));
+        fs.copyFileSync(s, d);
+      }
+    }
+  }
+}
+
+/**
+ * Create `.oxe/STATE.md` from template and ensure `.oxe/codebase/` exists.
+ * @param {string} target
+ * @param {{ dryRun: boolean, force: boolean }} opts
+ */
+function bootstrapOxe(target, opts) {
+  const oxeDir = path.join(target, '.oxe');
+  const codebaseDir = path.join(oxeDir, 'codebase');
+  const stateSrc = path.join(PKG_ROOT, 'oxe', 'templates', 'STATE.md');
+  const stateDest = path.join(oxeDir, 'STATE.md');
+  const configSrc = path.join(PKG_ROOT, 'oxe', 'templates', 'config.template.json');
+  const configDest = path.join(oxeDir, 'config.json');
+
+  if (!fs.existsSync(stateSrc)) {
+    console.error(`${yellow}warn:${reset} template missing: ${stateSrc}`);
+    return;
+  }
+
+  if (opts.dryRun) {
+    console.log(`${dim}init${reset}  ${oxeDir}/ (STATE.md, config.json, codebase/)`);
+    return;
+  }
+
+  ensureDir(codebaseDir);
+
+  if (!fs.existsSync(stateDest) || opts.force) {
+    copyFile(stateSrc, stateDest, { dryRun: false });
+    console.log(`${green}init${reset}  ${stateDest}`);
+  } else {
+    console.log(`${dim}skip${reset} ${stateDest} (exists, use --force to replace)`);
+  }
+
+  if (fs.existsSync(configSrc)) {
+    if (!fs.existsSync(configDest) || opts.force) {
+      copyFile(configSrc, configDest, { dryRun: false });
+      console.log(`${green}init${reset}  ${configDest}`);
+    } else {
+      console.log(`${dim}skip${reset} ${configDest} (exists, use --force to replace)`);
+    }
+  }
+}
+
+/** @param {string} target */
+function runDoctor(target) {
+  const v = process.versions.node;
+  const major = parseInt(v.split('.')[0], 10);
+  const minNode = readMinNode();
+  console.log(`${cyan}oxe-cc doctor${reset} — ${target}`);
+  console.log(`Node.js ${v} (require >= ${minNode})`);
+  if (major < minNode) {
+    console.log(`${red}FAIL${reset} Node.js version below package engines`);
+    process.exit(1);
+  }
+  console.log(`${green}OK${reset} Node.js`);
+
+  const wfPkg = path.join(PKG_ROOT, 'oxe', 'workflows');
+  const wfTgt = path.join(target, 'oxe', 'workflows');
+  if (!fs.existsSync(wfPkg)) {
+    console.log(`${red}FAIL${reset} package workflows missing: ${wfPkg}`);
+    process.exit(1);
+  }
+  const expected = fs
+    .readdirSync(wfPkg)
+    .filter((f) => f.endsWith('.md'))
+    .sort();
+
+  if (!fs.existsSync(wfTgt)) {
+    console.log(`${yellow}WARN${reset} Target has no oxe/workflows/ — run ${cyan}oxe-cc${reset} to install.`);
+    process.exit(1);
+  }
+
+  const actual = fs
+    .readdirSync(wfTgt)
+    .filter((f) => f.endsWith('.md'))
+    .sort();
+  const missing = expected.filter((f) => !actual.includes(f));
+  const extra = actual.filter((f) => !expected.includes(f));
+
+  if (missing.length) {
+    console.log(`${red}FAIL${reset} Missing workflows vs package: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+  if (extra.length) console.log(`${dim}Note:${reset} Extra workflows in target (ok for forks): ${extra.join(', ')}`);
+  console.log(`${green}OK${reset} oxe/workflows has all ${expected.length} package files`);
+
+  const oxeState = path.join(target, '.oxe', 'STATE.md');
+  if (fs.existsSync(oxeState)) console.log(`${green}OK${reset} .oxe/STATE.md present`);
+  else console.log(`${dim}Note:${reset} .oxe/STATE.md absent — run ${cyan}oxe-cc init-oxe${reset} or install without ${cyan}--no-init-oxe${reset}`);
+
+  const cfgPath = path.join(target, '.oxe', 'config.json');
+  if (fs.existsSync(cfgPath)) {
+    try {
+      JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      console.log(`${green}OK${reset} .oxe/config.json (valid JSON)`);
+    } catch (e) {
+      console.log(`${red}FAIL${reset} .oxe/config.json invalid JSON: ${e.message}`);
+      process.exit(1);
+    }
+  } else {
+    console.log(`${dim}Note:${reset} .oxe/config.json absent (optional — see oxe/templates/CONFIG.md)`);
+  }
+
+  const cbDir = path.join(target, '.oxe', 'codebase');
+  const expectedMaps = [
+    'OVERVIEW.md',
+    'STACK.md',
+    'STRUCTURE.md',
+    'TESTING.md',
+    'INTEGRATIONS.md',
+    'CONVENTIONS.md',
+    'CONCERNS.md',
+  ];
+  if (fs.existsSync(cbDir)) {
+    const missingMaps = expectedMaps.filter((f) => !fs.existsSync(path.join(cbDir, f)));
+    if (missingMaps.length) {
+      console.log(
+        `${yellow}Note:${reset} scan incomplete — missing under .oxe/codebase/: ${missingMaps.join(', ')} (run ${cyan}/oxe-scan${reset})`
+      );
+    } else {
+      console.log(`${green}OK${reset} .oxe/codebase/ has all ${expectedMaps.length} map files`);
+    }
+  }
+
+  console.log(`\n${green}Doctor finished.${reset}`);
+}
+
+function usage() {
+  console.log(`
+${cyan}oxe-cc${reset} — install OXE workflows (Cursor + GitHub Copilot) into a project
+
+${green}Usage:${reset}
+  npx oxe-cc@latest [options] [target-dir]
+  npx oxe-cc@latest --dir /path/to/project
+  npx oxe-cc doctor [options] [target-dir]
+  npx oxe-cc init-oxe [options] [target-dir]
+
+${green}Install options:${reset}
+  --cursor       Install .cursor/commands and .cursor/rules (default with --all)
+  --copilot      Install .github/copilot-instructions.md and .github/prompts
+  --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)
+  --force, -f    Overwrite existing files
+  --dry-run      Print actions without writing
+  --dir <path>   Target directory (default: cwd)
+  -h, --help
+  -v, --version
+
+${green}Examples:${reset}
+  npx oxe-cc@latest
+  npx oxe-cc@latest ./my-app
+  npx oxe-cc@latest --cursor --dry-run
+  npx oxe-cc doctor
+  npx oxe-cc init-oxe --dir ./my-app
+`);
+}
+
+function runInstall(opts) {
+  const target = opts.dir;
+  if (!opts.dryRun && !fs.existsSync(target)) {
+    console.error(`${yellow}Target directory does not exist: ${target}${reset}`);
+    process.exit(1);
+  }
+
+  console.log(`${cyan}OXE${reset} install → ${green}${target}${reset}`);
+  if (opts.dryRun) console.log(`${yellow}(dry-run)${reset}`);
+
+  const copyOpts = { dryRun: opts.dryRun, force: opts.force };
+
+  copyDir(path.join(PKG_ROOT, 'oxe'), path.join(target, 'oxe'), copyOpts);
+
+  if (opts.cursor) {
+    const cCmd = path.join(PKG_ROOT, '.cursor', 'commands');
+    const cRules = path.join(PKG_ROOT, '.cursor', 'rules');
+    if (fs.existsSync(cCmd)) copyDir(cCmd, path.join(target, '.cursor', 'commands'), copyOpts);
+    if (fs.existsSync(cRules)) copyDir(cRules, path.join(target, '.cursor', 'rules'), copyOpts);
+  }
+
+  if (opts.copilot) {
+    const gh = path.join(PKG_ROOT, '.github');
+    const inst = path.join(gh, 'copilot-instructions.md');
+    const prompts = path.join(gh, 'prompts');
+    if (fs.existsSync(inst)) {
+      const dest = path.join(target, '.github', 'copilot-instructions.md');
+      if (opts.dryRun) console.log(`${dim}file${reset}  ${inst} → ${dest}`);
+      else {
+        if (fs.existsSync(dest) && !opts.force) console.log(`${dim}skip${reset} ${dest} (exists)`);
+        else copyFile(inst, dest, copyOpts);
+      }
+    }
+    if (fs.existsSync(prompts)) copyDir(prompts, path.join(target, '.github', 'prompts'), copyOpts);
+  }
+
+  if (opts.vscode) {
+    const vs = path.join(PKG_ROOT, '.vscode', 'settings.json');
+    if (fs.existsSync(vs)) {
+      const dest = path.join(target, '.vscode', 'settings.json');
+      if (opts.dryRun) console.log(`${dim}file${reset}  ${vs} → ${dest}`);
+      else {
+        if (fs.existsSync(dest) && !opts.force) console.log(`${dim}skip${reset} ${dest} (exists)`);
+        else copyFile(vs, dest, copyOpts);
+      }
+    }
+  }
+
+  if (opts.commands) {
+    const cmdSrc = path.join(PKG_ROOT, 'commands', 'oxe');
+    const cmdDest = path.join(target, 'commands', 'oxe');
+    if (fs.existsSync(cmdSrc)) copyDir(cmdSrc, cmdDest, copyOpts);
+  }
+
+  if (opts.agents) {
+    const agents = path.join(PKG_ROOT, 'AGENTS.md');
+    if (fs.existsSync(agents)) {
+      const dest = path.join(target, 'AGENTS.md');
+      if (opts.dryRun) console.log(`${dim}file${reset}  ${agents} → ${dest}`);
+      else if (fs.existsSync(dest) && !opts.force) console.log(`${dim}skip${reset} ${dest} (exists)`);
+      else copyFile(agents, dest, copyOpts);
+    }
+  }
+
+  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}).`
+  );
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  let command = 'install';
+  if (argv[0] === 'doctor' || argv[0] === 'init-oxe') {
+    command = argv[0];
+    argv.shift();
+  }
+
+  const opts = parseInstallArgs(argv);
+
+  if (opts.version) {
+    console.log(`oxe-cc v${readPkgVersion()}`);
+    process.exit(0);
+  }
+
+  if (opts.parseError) {
+    printBanner();
+    console.error(`${red}Unknown option:${reset} ${opts.unknownFlag}`);
+    usage();
+    process.exit(1);
+  }
+
+  if (opts.help) {
+    printBanner();
+    usage();
+    process.exit(0);
+  }
+
+  printBanner();
+
+  const target = opts.dir;
+  if (command === 'doctor') {
+    if (!fs.existsSync(target)) {
+      console.error(`${yellow}Target directory does not exist: ${target}${reset}`);
+      process.exit(1);
+    }
+    runDoctor(target);
+    return;
+  }
+
+  if (command === 'init-oxe') {
+    if (!opts.dryRun && !fs.existsSync(target)) {
+      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}`);
+    bootstrapOxe(target, { dryRun: opts.dryRun, force: opts.force });
+    console.log(`\n${green}Done.${reset}`);
+    return;
+  }
+
+  runInstall(opts);
+}
+
+main();