oxe-cc 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudança
 
 ---
 
+## [1.14.0] — 2026-05-30
+
+### Contratos de integração para hosts — reatividade + dashboard embutível
+
+Aditivo — nenhum contrato existente muda. Complementa o 1.13.0 (`status --json --summary`, `agentSkills`) para hosts como o OXESpace embutirem o oxe-cc de forma reativa e visual.
+
+- **`oxe events --tail [N] --json [--since <evt_id>] [--session <s>]`** — projeção read-only e versionada (`oxeEventsSchema: 1`) do log append-only `.oxe/OXE-EVENTS.ndjson`: `{ summary: { total, byType, lastEvent }, events: [...] }`. `--since` devolve só os eventos novos desde um `event_id` conhecido (leitura incremental). Reusa `operational.readEvents`/`summarizeEvents`. Um host normalmente observa o arquivo e chama `status --json --summary`; este comando é a forma documentada de ler o tail sem reparsear tudo.
+- **`oxe dashboard --json`** — emite **uma linha** estável e versionada (`oxeDashboardSchema: 1`) com `{ url, port, readOnly, projectRoot }` assim que o servidor sobe, e **continua servindo**. Permite a um host capturar URL/porta de forma robusta e embutir o dashboard num webview, em vez de raspar o banner humano. Combine com `--no-open --port 0` para porta efêmera.
+- **`dashboard --port 0`** agora seleciona uma porta efêmera de verdade (antes caía no default `4173`).
+- **`docs/INTEGRATION.md`** — contrato estável para hosts: `status --json --summary`, `agentSkills`, schema do `OXE-EVENTS.ndjson`, `events --json` e `dashboard --json`; marca o que é estável vs experimental.
+
+---
+
+## [1.13.0] — 2026-05-29
+
+### Contratos de integração para hosts (IDEs, OXESpace)
+
+Aditivo — nenhum contrato existente muda. Facilita hosts consumirem o oxe-cc.
+
+- **`oxe status --json --summary`** — projeção compacta e versionada (`oxeSummarySchema: 1`) com `workspaceMode, phase, healthStatus, activeSession, nextStep, cursorCmd, reason, eventsCount, warningsCount` + um `agentSkills` compacto. Troca ~150KB do status completo por <1KB para o "glance" que um host precisa.
+- **`agentSkills` no `status --json`** e **`agentSkillsReport(target)` no SDK** (`health.agentSkillsReport`) — status das skills `/oxe-*` por agente no workspace (`copilot-vscode`, `codex`, `copilot-cli`): `detected/skillsInstalled/skillsPath/status/issues`. Permite a um host detectar skills ausentes e oferecer instalação **antes** de lançar o agente (resolve o "Failed to load N skills").
+- **SDK**: `health.buildStatusSummary(report)` e `health.agentSkillsReport(target)` exportados + tipados em `lib/sdk/index.d.ts`.
+
+---
+
 ## [1.12.0] — 2026-05-12
 
 ### Agent Mode, Swarm Mode, Memory Kernel & Learning Kernel

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-**Versão:** `1.12.0` · [package.json](package.json)
+**Versão:** `1.14.0` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 

package/bin/lib/oxe-project-health.cjs

@@ -2730,6 +2730,79 @@ function buildHealthReport(target) {
   };
 }
 
+/**
+ * Compact, stable projection of `buildHealthReport` for host integrations
+ * (IDEs, OXESpace). Versioned independently via `oxeSummarySchema` so a host
+ * can depend on a small, cheap payload instead of parsing the full ~100KB
+ * status. Pure — pass in a report from `buildHealthReport`.
+ * @param {ReturnType<typeof buildHealthReport>} report
+ */
+function buildStatusSummary(report) {
+  const next = (report && report.next) || {};
+  const gaps = Array.isArray(report && report.criticalExecutionGaps) ? report.criticalExecutionGaps.length : 0;
+  const planWarn = report && report.planSelfEvaluation && Array.isArray(report.planSelfEvaluation.warnings)
+    ? report.planSelfEvaluation.warnings.length
+    : 0;
+  return {
+    oxeSummarySchema: 1,
+    workspaceMode: (report && report.workspaceMode) || 'oxe_project',
+    phase: (report && report.phase) || null,
+    healthStatus: (report && report.healthStatus) || null,
+    activeSession: (report && report.activeSession) || null,
+    nextStep: next.step || null,
+    cursorCmd: next.cursorCmd || null,
+    reason: next.reason || null,
+    eventsCount: report && report.eventsSummary && typeof report.eventsSummary.total === 'number' ? report.eventsSummary.total : 0,
+    warningsCount: gaps + planWarn,
+  };
+}
+
+/**
+ * Per-agent OXE skills/integration status for a workspace. Lets a host detect
+ * when an agent lacks the `/oxe-*` skills BEFORE launching it — directly
+ * addresses the "Failed to load N skills" failure seen in agent CLIs. Reuses
+ * the tested copilot/codex integration reports plus a filesystem check of the
+ * Copilot CLI skills home (~/.copilot/skills).
+ * @param {string} target
+ */
+function agentSkillsReport(target) {
+  const agents = [];
+
+  const cp = copilotIntegrationReport(target);
+  agents.push({
+    agent: 'copilot-vscode',
+    detected: cp.detected,
+    skillsInstalled: cp.promptSource === 'workspace',
+    skillsPath: cp.workspace.promptsDir,
+    status: cp.status,
+    issues: cp.warnings || [],
+  });
+
+  const cx = codexIntegrationReport(target);
+  agents.push({
+    agent: 'codex',
+    detected: cx.detected,
+    skillsInstalled: Boolean(cx.skillsReady),
+    skillsPath: cx.skillsRoot,
+    status: cx.status,
+    issues: cx.warnings || [],
+  });
+
+  const cliSkillsRoot = path.join(copilotLegacyHome(), 'skills');
+  const cliSkillDirs = listOxeSkillDirs(cliSkillsRoot);
+  const cliInstalled = cliSkillDirs.length > 0;
+  agents.push({
+    agent: 'copilot-cli',
+    detected: cliInstalled,
+    skillsInstalled: cliInstalled,
+    skillsPath: cliSkillsRoot,
+    status: cliInstalled ? 'healthy' : 'not_installed',
+    issues: cliInstalled ? [] : ['Skills OXE ausentes em ~/.copilot/skills — rode `oxe install --copilot-cli` e depois `/skills reload`'],
+  });
+
+  return agents;
+}
+
 module.exports = {
   ALLOWED_CONFIG_KEYS,
   EXECUTION_PROFILES,
@@ -2775,6 +2848,8 @@ module.exports = {
   shouldSuppressExecutionWorkspaceGates,
   suggestNextStep,
   buildHealthReport,
+  buildStatusSummary,
+  agentSkillsReport,
   buildExecutionRationality: rationality.buildExecutionRationality,
   oxePaths,
   scopedOxePaths,

package/bin/oxe-cc.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * OXE — CLI em pt-BR: instala workflows no projeto, bootstrap `.oxe/`, doctor, uninstall, update.
  * Uso: npx oxe-cc, doctor, status, init-oxe, uninstall, update (ver --help).
@@ -203,26 +203,26 @@ function buildInstallSummary(opts, fullLayout) {
     cmd: 'npx oxe-cc status',
   });
 
-  const agentHint = [];
-  if (opts.cursor) agentHint.push('Cursor');
-  if (opts.copilot) agentHint.push('Copilot no VS Code');
-  if (opts.copilotCli || opts.allAgents || anyGranularAgent(opts)) agentHint.push('CLIs / multi-agente');
-  const onlyCodexAgent =
-    opts.agentCodex &&
-    !opts.allAgents &&
-    !opts.copilotCli &&
-    !opts.cursor &&
-    !opts.copilot &&
-    !opts.agentOpenCode &&
-    !opts.agentGemini &&
-    !opts.agentWindsurf &&
-    !opts.agentAntigravity;
-  if (agentHint.length) {
-    nextSteps.push({
-      desc: `Entrar no fluxo OXE no agente (${agentHint.join(', ')}) e deixar o router indicar o primeiro passo:`,
-      cmd: onlyCodexAgent ? '/prompts:oxe' : '/oxe',
-    });
-  } else if (opts.oxeOnly) {
+  const agentHint = [];
+  if (opts.cursor) agentHint.push('Cursor');
+  if (opts.copilot) agentHint.push('Copilot no VS Code');
+  if (opts.copilotCli || opts.allAgents || anyGranularAgent(opts)) agentHint.push('CLIs / multi-agente');
+  const onlyCodexAgent =
+    opts.agentCodex &&
+    !opts.allAgents &&
+    !opts.copilotCli &&
+    !opts.cursor &&
+    !opts.copilot &&
+    !opts.agentOpenCode &&
+    !opts.agentGemini &&
+    !opts.agentWindsurf &&
+    !opts.agentAntigravity;
+  if (agentHint.length) {
+    nextSteps.push({
+      desc: `Entrar no fluxo OXE no agente (${agentHint.join(', ')}) e deixar o router indicar o primeiro passo:`,
+      cmd: onlyCodexAgent ? '/prompts:oxe' : '/oxe',
+    });
+  } else if (opts.oxeOnly) {
     nextSteps.push({
       desc: 'Para ativar integrações IDE/CLI neste repo, instale de novo sem --oxe-only:',
       cmd: 'npx oxe-cc@latest',
@@ -234,19 +234,19 @@ function buildInstallSummary(opts, fullLayout) {
     });
   }
 
-  if (opts.copilotCli || opts.allAgents) {
-    nextSteps.push({
-      desc: 'No Copilot CLI: após instalar, rode /skills reload (ou reinicie o copilot) e use /oxe ou /oxe-scan:',
-      cmd: '/skills list',
-    });
-  }
-  if (opts.agentCodex || opts.allAgents) {
-    nextSteps.push({
-      desc: 'No Codex Desktop: reinicie o app ou abra uma nova conversa para recarregar prompts/skills; use a superfície de prompts do Codex:',
-      cmd: '/prompts:oxe   ou   /prompts:oxe-spec',
-    });
-  }
-  if (opts.allAgents || opts.agentGemini) {
+  if (opts.copilotCli || opts.allAgents) {
+    nextSteps.push({
+      desc: 'No Copilot CLI: após instalar, rode /skills reload (ou reinicie o copilot) e use /oxe ou /oxe-scan:',
+      cmd: '/skills list',
+    });
+  }
+  if (opts.agentCodex || opts.allAgents) {
+    nextSteps.push({
+      desc: 'No Codex Desktop: reinicie o app ou abra uma nova conversa para recarregar prompts/skills; use a superfície de prompts do Codex:',
+      cmd: '/prompts:oxe   ou   /prompts:oxe-spec',
+    });
+  }
+  if (opts.allAgents || opts.agentGemini) {
     nextSteps.push({
       desc: 'No Gemini CLI: recarregar comandos personalizados (/oxe, /oxe:scan, …):',
       cmd: '/commands reload',
@@ -390,6 +390,8 @@ function parseInstallArgs(argv) {
     statusHints: false,
     /** Visão extendida CLI-first: coverage matrix + readiness gate no terminal. */
     statusFull: false,
+    /** Saída JSON compacta/versionada para hosts (status --json --summary). */
+    statusSummary: false,
     restPositional: [],
   };
   for (let i = 0; i < argv.length; i++) {
@@ -435,6 +437,7 @@ function parseInstallArgs(argv) {
     } else if (a === '--json') out.jsonOutput = true;
     else if (a === '--hints') out.statusHints = true;
     else if (a === '--full') out.statusFull = true;
+    else if (a === '--summary') out.statusSummary = true;
     else if (a === '--release') out.releaseDoctor = true;
     else if (a === '--write-manifest') out.writeManifest = true;
     else if (!a.startsWith('-')) out.restPositional.push(a);
@@ -1892,6 +1895,18 @@ function runStatus(target, opts = {}) {
   const routineHints = collectOxeRoutineHints(target, report, config);
   const next = report.next;
 
+  // Lightweight, versioned summary for host integrations (IDEs, OXESpace) —
+  // a small stable payload instead of the full ~100KB status. Includes a
+  // compact per-agent skills view so a host can decide whether to offer
+  // "install OXE skills" before launching an agent.
+  if (opts.json && opts.summary) {
+    const summary = oxeHealth.buildStatusSummary(report);
+    summary.projectRoot = path.resolve(target);
+    summary.agentSkills = oxeHealth.agentSkillsReport(target).map((a) => ({ agent: a.agent, skillsInstalled: a.skillsInstalled }));
+    console.log(JSON.stringify(summary));
+    return;
+  }
+
   if (opts.json) {
     /** @type {Record<string, unknown>} */
     const payload = {
@@ -1947,6 +1962,7 @@ function runStatus(target, opts = {}) {
       azure: report.azure,
       copilot: report.copilot,
       codex: report.codex,
+      agentSkills: oxeHealth.agentSkillsReport(target),
       contextPacks: report.contextPacks,
       contextQuality: report.contextQuality,
       semanticsDrift: report.semanticsDrift,
@@ -2553,6 +2569,7 @@ ${cyan}oxe-cc${reset} — instala workflows OXE (núcleo .oxe/ + integrações:
     npx oxe-cc init-oxe [opções] [pasta-do-projeto]
     npx oxe-cc context <build|inspect> [opções] [pasta-do-projeto]
     npx oxe-cc dashboard [opções] [pasta-do-projeto]
+    npx oxe-cc events [--tail N] [--since <evt_id>] [--json] [opções] [pasta-do-projeto]
   npx oxe-cc runtime <status|start|pause|resume|replay|compile|verify|project|ci|promote|recover|gates|agents|execute> [opções] [pasta-do-projeto]
     npx oxe-cc azure <status|doctor|auth|sync|find|servicebus|eventgrid|sql|operations> [opções] [pasta-do-projeto]
     npx oxe-cc capabilities <list|install|remove|update> [opções] [id]
@@ -2587,12 +2604,21 @@ ${green}update${reset} (executa npx oxe-cc@latest --force na pasta do projeto)
   ${dim}CI / sem rede:${reset} OXE_UPDATE_SKIP_REGISTRY=1 desativa consultas (--check sai 2; --if-newer sai 2 sem npx)
 
 ${green}dashboard${reset} (interface web local para revisão e aprovação do plano)
-  --port <número>                        porta local (padrão: 4173)
+  --port <número>                        porta local (padrão: 4173; use 0 para porta efêmera)
   --no-open                              não abre o browser automaticamente
+  --json                                 emite {url,port,...} (oxeDashboardSchema:1) e segue servindo — para embutir num host
+  --read-only                            UI visual sem persistência (embed seguro)
   --session <sessions/sNNN-slug>         força visualização de uma sessão específica
   --dump-context                         imprime JSON consolidado e sai
   --dir <pasta>                          raiz do projeto (padrão: diretório atual)
 
+${green}events${reset} (projeção read-only do log .oxe/OXE-EVENTS.ndjson — para hosts)
+  --tail <N>                             só os últimos N eventos (padrão: 50)
+  --since <evt_id>                       só eventos posteriores a um event_id conhecido (leitura incremental)
+  --json                                 saída estruturada (oxeEventsSchema:1) com summary + events
+  --session <sessions/sNNN-slug>         força sessão específica (padrão: sessão ativa do STATE.md)
+  --dir <pasta>                          raiz do projeto (padrão: diretório atual)
+
 ${green}context${reset} (Context Engine V2: seleção, compressão e inspeção determinística)
   build [--workflow <slug>]              gera pack(s) em .oxe/context/packs/
   inspect [--workflow <slug>]            lê um pack existente ou resolve sob demanda
@@ -3924,7 +3950,7 @@ function parseCapabilitiesArgs(argv) {
 }
 
 /**
- * @typedef {{ help: boolean, dir: string, port: number, noOpen: boolean, readOnly: boolean, dumpContext: boolean, activeSession: string|null, parseError: boolean, unknownFlag: string }} DashboardOpts
+ * @typedef {{ help: boolean, dir: string, port: number, noOpen: boolean, readOnly: boolean, dumpContext: boolean, json: boolean, activeSession: string|null, parseError: boolean, unknownFlag: string }} DashboardOpts
  */
 
 /**
@@ -3985,6 +4011,7 @@ function parseDashboardArgs(argv) {
     noOpen: false,
     readOnly: false,
     dumpContext: false,
+    json: false,
     activeSession: null,
     parseError: false,
     unknownFlag: '',
@@ -3993,10 +4020,15 @@ function parseDashboardArgs(argv) {
     const a = argv[i];
     if (a === '-h' || a === '--help') out.help = true;
     else if (a === '--dir' && argv[i + 1]) out.dir = path.resolve(argv[++i]);
-    else if (a === '--port' && argv[i + 1]) out.port = Number(argv[++i]) || 4173;
-    else if (a === '--no-open') out.noOpen = true;
+    else if (a === '--port' && argv[i + 1] !== undefined) {
+      // Allow `--port 0` (OS picks an ephemeral port — used by hosts that embed
+      // the dashboard and read the real port back from `--json`).
+      const n = Number(argv[++i]);
+      out.port = Number.isFinite(n) && n >= 0 ? n : 4173;
+    } else if (a === '--no-open') out.noOpen = true;
     else if (a === '--read-only') out.readOnly = true;
     else if (a === '--dump-context') out.dumpContext = true;
+    else if (a === '--json') out.json = true;
     else if (a === '--session' && argv[i + 1]) out.activeSession = String(argv[++i]).replace(/\\/g, '/');
     else if (!a.startsWith('-') && i === 0) out.dir = path.resolve(a);
     else {
@@ -4357,7 +4389,7 @@ async function runDashboard(opts) {
     return;
   }
   const c = useAnsiColors();
-  printSection('OXE ▸ dashboard');
+  if (!opts.json) printSection('OXE ▸ dashboard');
   const server = oxeDashboard.createDashboardServer(target, { activeSession: opts.activeSession });
   await new Promise((resolve, reject) => {
     server.once('error', reject);
@@ -4366,6 +4398,24 @@ async function runDashboard(opts) {
   const address = server.address();
   const port = address && typeof address === 'object' ? address.port : opts.port;
   const url = `http://127.0.0.1:${port}/`;
+  // Host-integration mode: emit one stable, versioned line with the live URL/port
+  // as soon as the server is listening, then keep serving until killed. Lets a
+  // host (OXESpace) embed the dashboard in a webview without scraping the
+  // human-readable banner. Pair with `--no-open --port 0` for an ephemeral port.
+  if (opts.json) {
+    console.log(JSON.stringify({
+      oxeDashboardSchema: 1,
+      projectRoot: path.resolve(target),
+      url,
+      port,
+      readOnly: Boolean(opts.readOnly),
+    }));
+    if (!opts.noOpen) {
+      try { openUrlInBrowser(url); } catch { /* host owns presentation */ }
+    }
+    await new Promise(() => {});
+    return;
+  }
   console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
   console.log(`  ${c ? green : ''}URL:${c ? reset : ''} ${c ? cyan : ''}${url}${c ? reset : ''}`);
   if (opts.readOnly) {
@@ -4383,6 +4433,99 @@ async function runDashboard(opts) {
   await new Promise(() => {});
 }
 
+/**
+ * @typedef {{ help: boolean, dir: string, tail: number, since: string, activeSession: string|null, json: boolean, parseError: boolean, unknownFlag: string }} EventsOpts
+ */
+
+/**
+ * @param {string[]} argv
+ * @returns {EventsOpts}
+ */
+function parseEventsArgs(argv) {
+  /** @type {EventsOpts} */
+  const out = {
+    help: false,
+    dir: process.cwd(),
+    tail: 50,
+    since: '',
+    activeSession: null,
+    json: false,
+    parseError: false,
+    unknownFlag: '',
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.help = true;
+    else if (a === '--dir' && argv[i + 1]) out.dir = path.resolve(argv[++i]);
+    else if (a === '--tail') {
+      // `--tail` alone keeps the default; `--tail N` overrides the count.
+      const next = argv[i + 1];
+      if (next && /^\d+$/.test(next)) out.tail = Number(argv[++i]);
+    } else if (a === '--since' && argv[i + 1]) out.since = String(argv[++i]);
+    else if (a === '--json') out.json = true;
+    else if (a === '--session' && argv[i + 1]) out.activeSession = String(argv[++i]).replace(/\\/g, '/');
+    else if (!a.startsWith('-') && i === 0) out.dir = path.resolve(a);
+    else {
+      out.parseError = true;
+      out.unknownFlag = a;
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Read-only projection of the append-only event log (.oxe/OXE-EVENTS.ndjson)
+ * for host integrations. A host typically watches that file directly and then
+ * calls `status --json --summary`; this command is the documented way to read
+ * the tail of the log (optionally since a known event_id) without parsing the
+ * whole file. Reuses the same SDK helpers the runtime uses.
+ * @param {EventsOpts} opts
+ */
+function runEvents(opts) {
+  const target = opts.dir;
+  if (!fs.existsSync(target)) {
+    if (opts.json) console.log(JSON.stringify({ oxeEventsSchema: 1, projectRoot: path.resolve(target), error: 'dir-not-found', events: [] }));
+    else console.error(`${yellow}Diretório não encontrado: ${target}${reset}`);
+    process.exit(1);
+  }
+  const stateText = fs.existsSync(oxeHealth.oxePaths(target).state)
+    ? fs.readFileSync(oxeHealth.oxePaths(target).state, 'utf8')
+    : '';
+  const activeSession = opts.activeSession || oxeHealth.parseActiveSession(stateText) || null;
+  let events = oxeOperational.readEvents(target, activeSession);
+  if (opts.since) {
+    const idx = events.findIndex((e) => e && e.event_id === opts.since);
+    if (idx >= 0) events = events.slice(idx + 1);
+  }
+  const tail = opts.tail > 0 ? events.slice(-opts.tail) : events;
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      oxeEventsSchema: 1,
+      projectRoot: path.resolve(target),
+      activeSession,
+      summary: oxeOperational.summarizeEvents(events),
+      events: tail,
+    }));
+    return;
+  }
+
+  const c = useAnsiColors();
+  printSection('OXE ▸ events');
+  const summary = oxeOperational.summarizeEvents(events);
+  console.log(`  ${c ? green : ''}Total:${c ? reset : ''} ${summary.total}${activeSession ? `  ${c ? dim : ''}(sessão: ${activeSession})${c ? reset : ''}` : ''}`);
+  if (!tail.length) {
+    console.log(`  ${c ? dim : ''}Sem eventos.${c ? reset : ''}\n`);
+    return;
+  }
+  for (const e of tail) {
+    const ts = e.timestamp ? String(e.timestamp).replace('T', ' ').replace(/\..*$/, '') : '';
+    console.log(`  ${c ? dim : ''}${ts}${c ? reset : ''}  ${c ? cyan : ''}${e.type}${c ? reset : ''}${e.run_id ? ` ${c ? dim : ''}run=${e.run_id}${c ? reset : ''}` : ''}`);
+  }
+  console.log('');
+}
+
 /**
  * @param {RuntimeOpts} opts
  */
@@ -5473,6 +5616,7 @@ async function main() {
     argv[0] === 'init-oxe' ||
     argv[0] === 'context' ||
     argv[0] === 'dashboard' ||
+    argv[0] === 'events' ||
     argv[0] === 'runtime' ||
     argv[0] === 'azure' ||
     argv[0] === 'uninstall' ||
@@ -5582,11 +5726,29 @@ async function main() {
       usage();
       process.exit(1);
     }
-    printBanner();
+    if (!d.json) printBanner();
     await runDashboard(d);
     return;
   }
 
+  if (command === 'events') {
+    const e = parseEventsArgs(argv);
+    if (e.help) {
+      printBanner();
+      usage();
+      process.exit(0);
+    }
+    if (e.parseError) {
+      printBanner();
+      console.error(`${red}Opção desconhecida:${reset} ${e.unknownFlag}`);
+      usage();
+      process.exit(1);
+    }
+    if (!e.json) printBanner();
+    runEvents(e);
+    return;
+  }
+
   if (command === 'context') {
     const contextOpts = parseContextArgs(argv);
     if (contextOpts.help) {
@@ -5768,7 +5930,7 @@ async function main() {
     if (opts.statusFull) {
       runStatusFull(target);
     } else {
-      runStatus(target, { json: opts.jsonOutput, hints: opts.statusHints });
+      runStatus(target, { json: opts.jsonOutput, hints: opts.statusHints, summary: opts.statusSummary });
     }
     return;
   }

package/docs/INTEGRATION.md

@@ -0,0 +1,152 @@
+# Integração com hosts (IDEs, OXESpace, …)
+
+Este documento descreve o **contrato estável** que o `oxe-cc` expõe para um *host* — um app que embute o oxe-cc e mostra o estado de um projeto OXE (ex.: o [OXESpace](https://github.com/propagno) embute o painel OXE).
+
+O `oxe-cc` e o host têm **releases independentes**. Para que evoluam sem se quebrar:
+
+- Toda saída de máquina é **versionada** com um campo `oxe*Schema` próprio (independente da versão do pacote).
+- Os campos são **aditivos**: campos novos podem aparecer; campos existentes não mudam de tipo nem somem dentro da mesma `*Schema`.
+- O host deve **degradar graciosamente**: detectar a versão / o schema e usar o caminho antigo quando um recurso novo não existir.
+
+Detecte a versão com `oxe --version` (imprime `oxe-cc vX.Y.Z`). Tabela de disponibilidade:
+
+| Recurso | Desde | Schema |
+|---|---|---|
+| `status --json` (completo) | 1.0 | `oxeStatusSchema: 5` |
+| `status --json --summary` | 1.13.0 | `oxeSummarySchema: 1` |
+| `agentSkills[]` no `status --json` + `agentSkills` no summary | 1.13.0 | — |
+| `events --tail --json` | 1.14.0 | `oxeEventsSchema: 1` |
+| `dashboard --json` + `--port 0` efêmero | 1.14.0 | `oxeDashboardSchema: 1` |
+
+> **Estável:** `status --json --summary`, `agentSkills`, `events --json`, `dashboard --json`.
+> **Experimental (pode mudar):** o conteúdo de `payload` dentro de cada evento; o HTML servido pelo dashboard; o corpo de `status --json` completo (`oxeStatusSchema`) além dos campos listados abaixo.
+
+---
+
+## 1. Glance barato — `status --json --summary`
+
+Em vez do `status --json` completo (~100KB), use a projeção compacta no *hot path* (atualizações frequentes):
+
+```bash
+oxe status --json --summary --dir <projeto>
+```
+
+```jsonc
+{
+  "oxeSummarySchema": 1,
+  "projectRoot": "/abs/path",
+  "workspaceMode": "oxe_project",
+  "phase": "execute",
+  "healthStatus": "warning",
+  "activeSession": "sessions/s003-foo",
+  "nextStep": "execute",
+  "cursorCmd": "/oxe-execute",
+  "reason": "…",
+  "eventsCount": 42,
+  "warningsCount": 7,
+  "agentSkills": [ { "agent": "copilot-cli", "skillsInstalled": false } ]
+}
+```
+
+O `status --json` completo (`oxeStatusSchema: 5`) continua disponível para a vista detalhada (diagnósticos, `criticalExecutionGaps`, `planSelfEvaluation`, artefatos, `agentSkills[]` detalhado).
+
+---
+
+## 2. Skills por-agente — `agentSkills`
+
+O summary traz um `agentSkills` compacto (`{ agent, skillsInstalled }`). O `status --json` completo traz a forma detalhada:
+
+```jsonc
+{
+  "agent": "copilot-cli",        // copilot-vscode | codex | copilot-cli | cursor | …
+  "detected": true,               // o agente está configurado neste ambiente
+  "skillsInstalled": false,       // as skills /oxe-* estão instaladas neste workspace
+  "skillsPath": "/abs/.../skills",
+  "status": "no_skills",
+  "issues": ["…"]                 // por que falhou (caminho ausente, frontmatter, versão)
+}
+```
+
+Via SDK, sem shell: `require('oxe-cc').health.agentSkillsReport(target)`.
+
+**Uso típico do host:** se algum agente relevante tem `skillsInstalled:false`, ofereça instalar as skills daquele agente **antes** de lançá-lo (resolve o "Failed to load N skills"). Hoje o host dispara a instalação via os comandos `install` do oxe-cc (no terminal); uma saída `install --json` silenciosa está planejada (ver §5).
+
+---
+
+## 3. Reatividade — observar eventos
+
+O `oxe-cc` mantém um log **append-only** em:
+
+```
+.oxe/OXE-EVENTS.ndjson                                  # projeto sem sessão ativa
+.oxe/<session>/execution/OXE-EVENTS.ndjson              # quando há sessão ativa (ex.: sessions/s003-foo)
+```
+
+Cada linha é um JSON (NDJSON). Campos estáveis por evento:
+
+```jsonc
+{
+  "event_id": "evt-...",      // único; use como cursor em --since
+  "type": "RunStarted",       // RunStarted, WorkItemReady, ToolInvoked, GateRequested, RunCompleted, …
+  "timestamp": "2026-05-30T10:00:00.000Z",
+  "run_id": "run-1" | null,
+  "session_id": "sessions/s003-foo" | null,
+  "wave_id": 1 | null,
+  "task_id": "T1" | null,
+  "payload": { /* experimental — específico do tipo */ }
+}
+```
+
+**Padrão recomendado (reativo + barato):**
+
+1. O host faz `fs.watch` do `OXE-EVENTS.ndjson` (com debounce ~400ms).
+2. A cada mudança, re-chama `status --json --summary` para atualizar a UI.
+3. Um poll lento de segurança (~15s) cobre o caso de o watch falhar (rede/symlink).
+
+Para **ler os eventos** sem reparsear o arquivo inteiro, use o comando read-only:
+
+```bash
+oxe events --tail 50 --json --dir <projeto>
+oxe events --since evt-abc123 --json --dir <projeto>   # só os novos desde um event_id
+```
+
+```jsonc
+{
+  "oxeEventsSchema": 1,
+  "projectRoot": "/abs/path",
+  "activeSession": "sessions/s003-foo" | null,
+  "summary": { "total": 3, "byType": { "RunStarted": 1, "…": 1 }, "lastEvent": { /* … */ } },
+  "events": [ /* … */ ]
+}
+```
+
+Via SDK: `oxe.operational.readEvents(root, session)` e `oxe.operational.summarizeEvents(events)`.
+
+---
+
+## 4. Dashboard embutível — `dashboard --json`
+
+O dashboard é um servidor HTTP local (serve `/` HTML + `/api/context` + endpoints de review/runtime). Para embutir num webview/iframe, suba-o em modo host:
+
+```bash
+oxe dashboard --no-open --port 0 --json --dir <projeto>
+```
+
+A **primeira linha** do stdout é, assim que o servidor está ouvindo, e o processo **continua servindo** até ser morto:
+
+```json
+{"oxeDashboardSchema":1,"projectRoot":"/abs/path","url":"http://127.0.0.1:52555/","port":52555,"readOnly":false}
+```
+
+- `--port 0` → o SO escolhe uma porta efêmera; leia a porta real do `port`/`url`.
+- `--read-only` → UI visual sem persistir mudanças (embed seguro).
+- O servidor é localhost-only (`127.0.0.1`), sem autenticação — adequado a embed local.
+
+**Ciclo de vida (host):** faça spawn do processo, leia a primeira linha JSON, carregue `url` no webview, e **mate o processo** ao fechar o workspace/app. Fallback para versões < 1.14: rode `dashboard` sem `--json` e raspe a linha `URL: …`, ou abra no navegador externo.
+
+---
+
+## 5. Roadmap de integração (ainda não estável)
+
+- **`install … --json`** — saída idempotente `{ ok, agents:[{agent, installedPaths[]}], skipped[], errors[] }` para instalar skills sem terminal. Hoje a instalação é via os comandos `install` (no terminal) + reconferir com `agentSkills`.
+- **`events --follow` / streaming (SSE)** — hoje a reatividade é via `fs.watch` + `events --tail`/`--since`.