npm package: @lucian_bitencourt/epox
Description: CLI do EPOX para instalar contexto operacional em projetos com foco em continuidade e economia de tokens.
Author: Lucian Bitencourt
Latest version: 0.1.2

﻿# EPOX

EPOX e uma CLI para instalar e operar uma camada de contexto persistente em projetos de software, com foco em continuidade entre sessoes, organizacao modular e economia de tokens.

## Visao rapida

- Produto/CLI: `EPOX`
- Pasta recomendada: `.epox/`
- Pasta legada suportada: `.project-brain/`
- Execucao sem instalacao global: `npx @lucian_bitencourt/epox`

## Inicio rapido

### Modo guiado no terminal

```bash
npx @lucian_bitencourt/epox
```

Abre menu navegavel por setas com fluxos assistidos (modulos, agentes, quality, reconcile e prepare-task).

Menu principal:

- Instalar ou atualizar EPOX
- Projeto novo
- Projeto existente
- Reconcile context
- Modulos
- Agentes
- Quality
- Prepare task
- Uninstall
- Sair

No modo guiado, `Uninstall` abre submenu com:
- somente local
- full (local + Codex + Claude)
- escopo customizado por checklist

### Projeto novo

```bash
npx @lucian_bitencourt/epox init new
```

### Projeto existente

```bash
npx @lucian_bitencourt/epox init existing
npx @lucian_bitencourt/epox reconcile-context
```

### Contexto minimo para execucao

```bash
npx @lucian_bitencourt/epox prepare-task
```

## Comandos CLI (resumo)

### Modo guiado

- `epox` abre o menu principal interativo.

### Inicializacao e contexto

- `epox init new`
- `epox init existing`
- `epox sync-context`
- `epox migrate`
- `epox reconcile-context`
- `epox prepare-task`

### Modulos

- `epox modules scan`
- `epox modules scan-assisted`
- `epox modules list`
- `epox modules select <nome-ou-id>`
- `epox modules create`

### Agentes

- `epox agents list`
- `epox agents select <nome-ou-id>`
- `epox agents create`
- `epox agents edit <nome-ou-id>`
- `epox agents remove <nome-ou-id>`
- `epox agents disable <nome-ou-id>`
- `epox agents enable <nome-ou-id>`

### Quality setup (opcional)

- `epox quality setup`
- `epox quality status`
- `epox quality install`
- `epox quality run`
- `epox quality doctor`

### Uninstall seguro

- `epox uninstall`
- `epox uninstall --full`
- `epox uninstall --dry-run`
- `epox uninstall --yes`
- `epox uninstall --scope`
- `epox uninstall --scope local,codex,claude`

`--full` amplia a limpeza para escopos globais (`~/.codex`, `~/.claude`) com filtros de seguranca.

### Migracao de raiz legada (opcional)

- `epox migrate`
- `epox migrate --force`
- `epox migrate --full`

## Flags globais importantes

- `--yes` ou `-y`: usa defaults sem perguntas interativas.
- `--force`: permite sobrescrever arquivos/scripts quando aplicavel.
- `--preset`: `minimal|standard|modular|ai-system|custom`.
- `--profile`: define profile no `quality setup`.
- `--dry-run`: mostra plano sem executar (`quality run`, `uninstall`).
- `--full`: uninstall ampliado e remocao de raiz legada no `migrate`.
- `--scope`: escopos de uninstall (`local`, `codex`, `claude`), com selecao interativa quando usado sem valor.

## Modo guiado x modo direto

- Modo direto: comandos com argumentos continuam funcionando como antes.
- Modo guiado: `epox` sem subcomando abre menus com selecao visual (setas + checkbox).
- Retrocompatibilidade: os dois modos coexistem.

## Comandos slash (`/...`) instalados

Esses comandos sao guias para agentes dentro da estrutura instalada.

### Base (`commands/` do template principal)

- `/analyze-project`: organiza leitura inicial do projeto.
- `/create-feature`: guia para implementar feature nova.
- `/fix-issue`: guia de diagnostico e correcao.
- `/init-existing`: guia de setup para brownfield.
- `/init-new`: guia de setup para greenfield.
- `/prepare-task`: guia de contexto minimo antes de executar.
- `/reconcile-context`: guia de reconciliacao codigo + docs.
- `/review-feature`: guia de revisao tecnica/funcional.
- `/sync-context`: guia de sync incremental.
- `/uninstall`: guia de desinstalacao segura.

### Extras de quality (quando aplicavel)

- `/quality-setup`: guia de configuracao do pipeline de qualidade.
- `/quality-run`: guia de execucao das validacoes.

## Estruturas principais geradas

- `project-config.json`: configuracao de presets/features.
- `project-config.json` tambem registra:
  - ambientes (`codex`, `claude-code`)
  - modo de projeto (`new`/`existing`)
  - profile principal quando aplicavel
  - preferencias operacionais da CLI guiada
- `project-context/current-state.md`: porta de entrada curta da sessao.
- `project-context/index/*.md`: indices para leitura rapida.
- `project-context/task-context.md`: contexto minimo gerado pelo `prepare-task`.
- `project-context/quality-profile.md`: resumo do pipeline de qualidade.
- `project-context/quality-config.json`: configuracao persistente de quality.
- `modules/registry.json`: registro de modulos.
- `registry/agents.json`: registro de agentes.
- `install-manifest.json`: manifesto para uninstall seguro.

## Documentacao completa

O README e uma porta de entrada. A documentacao operacional detalhada esta em `docs/`.

- [Getting Started](docs/getting-started.md)
- [Instalacao](docs/installation.md)
- [Fluxo para projeto novo](docs/project-new.md)
- [Fluxo para projeto existente](docs/project-existing.md)
- [Fluxos operacionais](docs/flows.md)

### Conceitos

- [Arquitetura do EPOX](docs/concepts/architecture.md)
- [Estrutura de pastas e arquivos](docs/concepts/project-structure.md)
- [Otimizacao de tokens](docs/concepts/token-optimization.md)
- [Knowledge Library](docs/concepts/knowledge-library.md)
- [Sistema de modulos](docs/concepts/module-system.md)
- [Sistema de agentes](docs/concepts/agent-system.md)
- [Sistema de quality](docs/concepts/quality-system.md)

### Comandos

- [init new](docs/commands/init-new.md)
- [init existing](docs/commands/init-existing.md)
- [sync-context](docs/commands/sync-context.md)
- [migrate](docs/commands/migrate.md)
- [reconcile-context](docs/commands/reconcile-context.md)
- [modules](docs/commands/modules.md)
- [agents](docs/commands/agents.md)
- [quality](docs/commands/quality.md)
- [prepare-task](docs/commands/prepare-task.md)
- [uninstall](docs/commands/uninstall.md)

## Desenvolvimento local da CLI

```bash
npm install
npm run lint
npm test
npm start
```