trackops 1.0.1 → 1.1.0

package/README.md

@@ -5,407 +5,463 @@
 <h1 align="center">TrackOps</h1>
 
 <p align="center">
-  <strong>El motor operativo open-source para desarrolladores que construyen con IA.</strong>
+  <strong>Local orchestration and operational automation for AI-agent projects.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/trackops"><img src="https://img.shields.io/npm/v/trackops?color=D97706&style=flat-square" alt="npm" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/licencia-MIT-22C55E?style=flat-square" alt="MIT" /></a>
-  <img src="https://img.shields.io/badge/estado-beta-F59E0B?style=flat-square" alt="Beta" />
-  <img src="https://img.shields.io/badge/dependencias-0-D97706?style=flat-square" alt="0 deps" />
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E?style=flat-square" alt="MIT" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D18-333?style=flat-square" alt="Node 18+" />
 </p>
 
 <p align="center">
-  <a href="#español">Español</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#english">English</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://baxahaun.github.io/trackops">Web</a>
+  <a href="#español">Español</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#english">English</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://baxahaun.github.io/trackops/">Web</a>
 </p>
 
-<br/>
-
 ---
 
 ## Español
 
-> **Estado beta:** TrackOps ya es usable, pero sigue evolucionando rápido. La interfaz, los comandos y algunos flujos pueden cambiar entre versiones.
+TrackOps es un sistema local de orquestación y automatización operativa de proyectos y desarrollo con agentes IA.
 
-> **Descargo de responsabilidad:** Revisa siempre los archivos generados, los cambios automáticos y los resultados de tus agentes antes de usarlos en proyectos sensibles o en producción.
+Prepara a tus agentes, ordena el trabajo del proyecto y mantiene separadas la aplicación real y la capa operativa, sin depender de una nube externa.
 
-### El Problema: La IA es rápida. El caos también.
+### Modelo actual
 
-Escribir código con asistentes de IA (Cursor, Copilot, Claude Code, agentes autónomos) es increíblemente rápido. Pero a medida que el proyecto crece, **la IA pierde el contexto**, olvida las prioridades y el proyecto se convierte en una pesadilla de mantenimiento.
+TrackOps funciona con dos capas:
 
-Tu agente no sabe qué tarea es prioritaria. No sabe qué está bloqueado. No sabe en qué fase estás. Y tú terminas repitiendo instrucciones en cada prompt.
+1. `skill global`
+   se instala una vez en tu agente o CLI
+2. `activación local por proyecto`
+   se ejecuta cuando quieres gestionar un repo concreto
 
-### La Solución: TrackOps
+El flujo oficial es este:
 
-TrackOps es un **motor operativo local de código abierto** que actúa como puente entre tú (el humano) y tus agentes de IA.
+1. instala la skill global
+2. deja que la skill asegure el runtime en primer uso
+3. activa TrackOps en un repo con `trackops init`
+4. añade OPERA solo si lo necesitas con `trackops opera install`
 
-**Tú** gestionas el proyecto visualmente a través de un elegante **Dashboard Web local**. TrackOps compila automáticamente ese estado en **archivos Markdown hiper-estructurados** (`task_plan.md`, `progress.md`, `findings.md`) que tu IA lee para saber exactamente qué hacer, qué reglas seguir y qué prioridades existen.
+### Instalación global
 
-> **La IA se encarga del código. TrackOps se encarga del proyecto.**
+TrackOps se distribuye como skill global desde el ecosistema `skills`.
 
-<br/>
+```bash
+npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+```
 
-### Por qué TrackOps se volverá indispensable en tu flujo
+Targets soportados en la skill:
 
-| | |
-|---|---|
-| **Adopción en 10 segundos** | Un solo comando: `npx trackops init`. Cero configuración, cero dependencias, cero bases de datos. |
-| **Contexto determinista** | No dejes que la IA adivine. TrackOps sincroniza la verdad absoluta de tu proyecto en archivos Markdown que las IAs entienden nativamente. |
-| **Dashboard local premium** | Interfaz web profesional que corre en tu terminal. Sin telemetría, sin nube, **100% privado**. |
-| **Integración Git nativa** | TrackOps sabe cuándo haces commit, merge o checkout, capturando la salud del repositorio de forma automática. |
-| **Portfolio multi-proyecto** | Registra todos tus proyectos y navega entre ellos desde un solo dashboard. |
-| **Framework OPERA** | Metodología de desarrollo con agentes IA en 5 fases: Orquestar, Probar, Estructurar, Refinar, Automatizar. |
-| **Ecosistema de Skills** | Integración nativa a un click con el marketplace **skills.sh**. Habilidades y agentes modulares que dotan a tu proyecto de capacidades automatizadas avanzadas e IA pre-entrenada para tu workflow. |
+- `antigravity`
+- `claude-code`
+- `codex`
+- `cursor`
+- `gemini-cli`
+- `github-copilot`
+- `kiro-cli`
+
+La skill global:
 
-<br/>
+- hace disponible TrackOps para tu agente
+- asegura el runtime npm en primer uso
+- no modifica repos por sí sola
 
-### Inicio Rápido
+### Bootstrap del runtime
 
-No necesitas instalar nada globalmente. Ve a cualquier proyecto y ejecuta:
+En el primer uso real, la skill ejecuta su bootstrap:
 
 ```bash
-npx trackops init               # Inicializa el motor en tu proyecto
-npx trackops dashboard           # Levanta el centro de control web
+node scripts/bootstrap-trackops.js
 ```
 
-Tras `init`, también quedan disponibles atajos npm para el proyecto:
+Ese bootstrap:
 
-```bash
-npm run ops:status
-npm run ops:dashboard
-npm run ops:sync
-```
+- valida `Node.js >= 18`
+- valida `npm`
+- instala o actualiza `trackops`
+- verifica el comando
+- registra el estado en `~/.trackops/runtime.json`
+
+Contrato de la skill: [skills/trackops/skill.json](./skills/trackops/skill.json)
+
+### Activación local por proyecto
 
-El flujo desde consola en tu día a día:
+Cuando quieres gestionar un repo:
 
 ```bash
-npx trackops status              # Salud del proyecto y bloqueos
-npx trackops next                # Siguiente tarea priorizada
-npx trackops task start T-001    # Empieza a trabajar
-npx trackops sync                # Genera contexto Markdown para tu IA
+trackops init
+trackops opera install
 ```
 
-Guía de uso paso a paso: [UserGUIDE.md](UserGUIDE.md)
+Semántica oficial:
 
-<br/>
+- `trackops init`
+  crea por defecto un workspace split con `app/`, `ops/`, `/.env`, `/.env.example` y `.trackops-workspace.json`
+- `trackops opera install`
+  añade OPERA sobre un proyecto ya inicializado y escribe solo en `ops/`
+- `trackops init --with-opera`
+  existe como atajo explícito
+- `trackops init --legacy-layout`
+  existe solo por compatibilidad
 
-### Arquitectura de 3 Capas
+### Workspace split
 
-Diseñado para escalar desde un script de fin de semana hasta infraestructura empresarial.
+TrackOps separa tu producto real en `app/` y la operación en `ops/`, para que no se mezclen.
 
-```
-┌─────────────────────────────────────────────────────┐
-│  Capa 3 · Ecosistema de Skills                      │
-│  Plugins modulares para automatizar capacidades     │
-│  trackops skill install / list / remove / catalog   │
-├─────────────────────────────────────────────────────┤
-│  Capa 2 · Framework OPERA (opcional)                │
-│  Enrutamiento de agentes y metodología estructurada │
-│  trackops opera install / configure / status        │
-├─────────────────────────────────────────────────────┤
-│  Capa 1 · Motor Core (siempre activo)               │
-│  CLI + Servidor Web Local + Generador de Markdown   │
-│  tareas · dashboard · registro · git hooks · sync   │
-└─────────────────────────────────────────────────────┘
+```text
+mi-proyecto/
+├── .trackops-workspace.json
+├── .env
+├── .env.example
+├── app/
+│   ├── .env
+│   └── ...producto real...
+└── ops/
+    ├── project_control.json
+    ├── task_plan.md
+    ├── progress.md
+    ├── findings.md
+    ├── genesis.md
+    ├── .agent/hub/
+    ├── .agents/skills/
+    ├── .githooks/
+    └── .tmp/
 ```
 
-<br/>
+Fuente de verdad operativa:
 
-### Metodología OPERA
+- split layout: `ops/project_control.json`
+- legacy layout: `project_control.json`
 
-Framework opcional de 5 fases para desarrollo estructurado con IA. Cada fase tiene un **Definition of Done** verificable:
+### Entorno y secretos
 
-| Fase | Nombre | Foco | Entregable |
-|------|--------|------|------------|
-| **O** | Orquestar | Visión, datos, reglas de negocio | Schema JSON en `genesis.md` |
-| **P** | Probar | Conectividad y validación | Scripts de test pasando |
-| **E** | Estructurar | Construcción en 3 capas | SOPs + tools + integración |
-| **R** | Refinar | Refinamiento y calidad | Outputs validados |
-| **A** | Automatizar | Despliegue y triggers | Triggers + smoke test |
+TrackOps gestiona un contrato explícito de entorno:
 
-Las fases son totalmente configurables por proyecto vía `project_control.json`.
+- `/.env`
+  archivo real de secretos del workspace
+- `/.env.example`
+  contrato público de variables
+- `app/.env`
+  puente de compatibilidad para herramientas del producto
 
-<br/>
+Comandos principales:
 
-### Referencia de Comandos
+```bash
+trackops env status
+trackops env sync
+```
 
-<details>
-<summary><strong>Motor Core</strong></summary>
+### Trabajo diario
 
-| Comando | Descripción |
-|---------|-------------|
-| `trackops init [--with-opera] [--locale es\|en]` | Inicializar en el directorio actual. `--with-etapa` se mantiene solo como alias heredado. |
-| `trackops status` | Estado: foco, fase, tareas, bloqueadores, repo |
-| `trackops next` | Próximas tareas ejecutables priorizadas |
-| `trackops sync` | Regenerar task_plan.md, progress.md, findings.md |
-| `trackops dashboard` | Lanzar dashboard web local |
-| `trackops task <acción> <id> [nota]` | start, review, complete, block, pending, cancel, note |
-| `trackops refresh-repo [--quiet]` | Actualizar runtime con estado del repo |
-| `trackops register` | Registrar en el portfolio multi-proyecto |
-| `trackops projects` | Listar proyectos registrados |
-
-</details>
-
-<details>
-<summary><strong>OPERA</strong></summary>
+```bash
+trackops status
+trackops next
+trackops sync
+trackops env status
+trackops dashboard
+```
 
-| Comando | Descripción |
-|---------|-------------|
-| `trackops opera install` | Instalar metodología OPERA |
-| `trackops opera status` | Estado de instalación e integridad |
-| `trackops opera configure [--phases '...']` | Reconfigurar fases o idioma |
-| `trackops opera upgrade` | Actualizar templates a la versión del paquete |
+Reglas operativas:
 
-</details>
+- usa `trackops status` para leer foco, fase y bloqueadores
+- usa `trackops next` para identificar la siguiente tarea lista
+- usa `trackops sync` para regenerar docs operativos
+- no edites a mano `task_plan.md`, `progress.md` ni `findings.md`
 
-<details>
-<summary><strong>Skills</strong></summary>
+El dashboard es local, encuentra un puerto libre si el preferido está ocupado y puede copiar la URL al portapapeles.
 
-| Comando | Descripción |
-|---------|-------------|
-| `trackops skill install <nombre>` | Instalar skill del catálogo |
-| `trackops skill list` | Listar skills instaladas |
-| `trackops skill remove <nombre>` | Desinstalar skill |
-| `trackops skill catalog` | Ver skills disponibles |
+### CLI principal
 
-</details>
+#### Core
 
-Antes de publicar una versión, ejecuta `npm run release:check`. La política mínima de versiones y publicación está en `docs/RELEASE.md`.
+| Comando | Descripción |
+|---|---|
+| `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa TrackOps en el repo actual |
+| `trackops status` | Muestra el estado operativo actual |
+| `trackops next` | Muestra las siguientes tareas listas |
+| `trackops sync` | Regenera la documentación operativa |
+| `trackops workspace status` | Muestra layout, roots y configuración del workspace |
+| `trackops workspace migrate` | Migra un proyecto legacy al layout `app/` + `ops/` |
+| `trackops env status` | Audita claves requeridas, presentes y faltantes sin mostrar valores |
+| `trackops env sync` | Crea o regenera `/.env`, `/.env.example` y el puente `app/.env` |
+| `trackops release [--push]` | Publica la rama configurada a partir de `app/` |
+| `trackops dashboard [--port N] [--host HOST] [--public] [--strict-port]` | Lanza el dashboard local |
+| `trackops version` | Imprime la versión instalada |
+
+#### OPERA
 
-<br/>
+| Comando | Descripción |
+|---|---|
+| `trackops opera install [--locale es\|en] [--non-interactive] [--no-bootstrap]` | Instala OPERA en el proyecto actual |
+| `trackops opera bootstrap [--locale es\|en] [--non-interactive]` | Reanuda el bootstrap OPERA |
+| `trackops opera status` | Muestra el estado de instalación y bootstrap |
+| `trackops opera configure [--phases '...'] [--locale es\|en]` | Reconfigura fases o idioma |
+| `trackops opera upgrade` | Actualiza los templates OPERA a la versión del paquete |
 
-### Estructura del Proyecto
+#### Skills del proyecto
 
-```
-mi-proyecto/
-├── project_control.json       # Fuente de verdad operativa
-├── task_plan.md               # Plan de tareas (auto-generado)
-├── progress.md                # Diario de progreso (auto-generado)
-├── findings.md                # Hallazgos (auto-generado)
-├── genesis.md                 # Constitución del proyecto (OPERA)
-├── .agent/hub/                # Identidad del agente + router (OPERA)
-└── .agents/skills/            # Skills instaladas (OPERA)
+`trackops skill ...` gestiona skills nativas del proyecto. En split layout viven en `ops/.agents/skills/`.
+
+```bash
+trackops skill catalog
+trackops skill install commiter
+trackops skill list
+trackops skill remove commiter
 ```
 
-**Higiene del repositorio del paquete:** este repositorio solo versiona archivos propios de `trackops` como producto. Los artefactos generados al ejecutar `trackops` u `OPERA` sobre un proyecto (`project_control.json`, `task_plan.md`, `progress.md`, `findings.md`, `genesis.md`, `.agent/`, `.agents/`, `.githooks/`) se consideran salidas de uso y no deben subirse a este repo.
+### Vía alternativa sin skill global
 
-<br/>
+Si no quieres usar la distribución por skill:
 
-### Apoya el Proyecto
+```bash
+npx trackops init
+npx trackops dashboard
+```
 
-TrackOps es y siempre será **libre, gratuito y de código abierto** (MIT). Construimos esto para resolver un problema real de la comunidad de desarrolladores.
+O instala el paquete globalmente con npm:
+
+```bash
+npm install -g trackops
+trackops init
+trackops opera install
+```
 
-Si TrackOps te ha ayudado a recuperar el control de tus proyectos con IA:
+### Publicación y validación
 
-1. **Dale una estrella en GitHub** — ayuda enormemente a la visibilidad.
-2. **Comparte TrackOps** con tu equipo y en tus redes.
-3. **Apoya con USDC en Polygon** para ayudar a mantener la documentación, las mejoras y el soporte del proyecto.
+Antes de publicar:
 
-   ```text
-   Red: Polygon
-   Moneda: USDC
-   Dirección: 0x7B3d964247Dd309D13FF702649827947633e27F3
-   ```
+```bash
+trackops workspace status
+trackops env status
+npm run skill:validate
+npm run skill:smoke
+npm run release:check
+```
 
-   Envía solo `USDC` por la red `Polygon`. No envíes `BTC` ni activos de otras redes a esta dirección.
-4. **Contribuye** — Pull Requests, reporte de bugs y nuevas Skills son siempre bienvenidos.
+En proyectos split, `trackops release` publica solo el contenido de `app/` hacia la rama configurada e incluye `.env.example`. No publica `/.env`, `ops/` ni `.trackops-workspace.json`.
 
-<br/>
+Guía ampliada: [UserGUIDE.md](./UserGUIDE.md)
 
 ---
 
 ## English
 
-> **Beta status:** TrackOps is already usable, but it is still evolving quickly. The interface, commands, and some flows may change between releases.
+TrackOps is a local orchestration and operational automation system for projects and AI-agent development.
 
-> **Disclaimer:** Always review generated files, automated changes, and agent output before using them in sensitive or production projects.
+It prepares your agents, organizes project execution, and keeps the real app separate from the operational layer, without depending on an external cloud.
 
-### The Problem: AI is fast. So is chaos.
+### Current model
 
-Writing code with AI assistants (Cursor, Copilot, Claude Code, autonomous agents) is incredibly fast. But as the project grows, **the AI loses context**, forgets priorities, and the project becomes a maintenance nightmare.
+TrackOps works in two layers:
 
-Your agent doesn't know which task is a priority. It doesn't know what's blocked. It doesn't know what phase you're in. And you end up repeating instructions in every prompt.
+1. `global skill`
+   installed once in your agent or CLI
+2. `local per-project activation`
+   run only when you want to manage a specific repository
 
-### The Solution: TrackOps
+Official flow:
 
-TrackOps is a **local, open-source operational engine** that acts as a bridge between you (the human) and your AI agents.
+1. install the global skill
+2. let the skill ensure the runtime on first use
+3. activate TrackOps in a repo with `trackops init`
+4. add OPERA only when needed with `trackops opera install`
 
-**You** manage the project visually through an elegant **local Web Dashboard**. TrackOps automatically compiles that state into **hyper-structured Markdown files** (`task_plan.md`, `progress.md`, `findings.md`) that your AI reads to know exactly what to do, what rules to follow, and what priorities exist.
+### Global install
 
-> **AI handles the code. TrackOps handles the project.**
+TrackOps is distributed as a global skill through the `skills` ecosystem.
 
-<br/>
+```bash
+npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+```
 
-### Why TrackOps will become essential in your workflow
+Supported skill targets:
 
-| | |
-|---|---|
-| **10-second adoption** | One command: `npx trackops init`. Zero config, zero dependencies, zero databases. |
-| **Deterministic context** | Don't let AI guess. TrackOps syncs the absolute truth of your project into Markdown files that AIs understand natively. |
-| **Premium local dashboard** | Professional web interface running in your terminal. No telemetry, no cloud, **100% private**. |
-| **Native Git integration** | TrackOps knows when you commit, merge, or checkout, capturing repository health automatically. |
-| **Multi-project portfolio** | Register all your projects and navigate between them from a single dashboard. |
-| **OPERA Framework** | AI development methodology in 5 phases: Orchestrate, Prove, Establish, Refine, Automate. |
-| **Skills ecosystem** | Modular plugins that give your project automated capabilities: `trackops skill install <name>`. |
+- `antigravity`
+- `claude-code`
+- `codex`
+- `cursor`
+- `gemini-cli`
+- `github-copilot`
+- `kiro-cli`
+
+The global skill:
 
-<br/>
+- makes TrackOps available to your agent
+- ensures the npm runtime on first use
+- does not mutate repositories by itself
 
-### Quick Start
+### Runtime bootstrap
 
-No global install needed. Go to any project and run:
+On first real use, the skill runs:
 
 ```bash
-npx trackops init               # Initialize the engine in your project
-npx trackops dashboard           # Launch the web control center
+node scripts/bootstrap-trackops.js
 ```
 
-After `init`, npm shortcuts are also ready to use inside the project:
+That bootstrap:
 
-```bash
-npm run ops:status
-npm run ops:dashboard
-npm run ops:sync
-```
+- validates `Node.js >= 18`
+- validates `npm`
+- installs or updates `trackops`
+- verifies the command
+- records state in `~/.trackops/runtime.json`
 
-Your daily workflow from the console:
+Skill contract: [skills/trackops/skill.json](./skills/trackops/skill.json)
+
+### Local per-project activation
+
+When you want to manage a repository:
 
 ```bash
-npx trackops status              # Project health and blockers
-npx trackops next                # Next prioritized task
-npx trackops task start T-001    # Start working
-npx trackops sync                # Generate Markdown context for your AI
+trackops init
+trackops opera install
 ```
 
-Step-by-step user guide: [UserGUIDE.md](UserGUIDE.md)
+Official semantics:
 
-<br/>
+- `trackops init`
+  creates a split workspace by default with `app/`, `ops/`, `/.env`, `/.env.example`, and `.trackops-workspace.json`
+- `trackops opera install`
+  adds OPERA to an initialized project and writes only inside `ops/`
+- `trackops init --with-opera`
+  exists as an explicit shortcut
+- `trackops init --legacy-layout`
+  exists only for compatibility
 
-### 3-Layer Architecture
+### Split workspace
 
-Designed to scale from a weekend script to enterprise infrastructure.
+TrackOps separates your real product into `app/` and operations into `ops/`, so they do not get mixed.
 
-```
-┌─────────────────────────────────────────────────────┐
-│  Layer 3 · Skills Ecosystem                         │
-│  Modular plugins for automated capabilities         │
-│  trackops skill install / list / remove / catalog   │
-├─────────────────────────────────────────────────────┤
-│  Layer 2 · OPERA Framework (optional)               │
-│  Agent routing and structured methodology           │
-│  trackops opera install / configure / status        │
-├─────────────────────────────────────────────────────┤
-│  Layer 1 · Core Engine (always active)              │
-│  CLI + Local Web Server + Markdown Generator        │
-│  tasks · dashboard · registry · git hooks · sync    │
-└─────────────────────────────────────────────────────┘
+```text
+my-project/
+├── .trackops-workspace.json
+├── .env
+├── .env.example
+├── app/
+│   ├── .env
+│   └── ...real product...
+└── ops/
+    ├── project_control.json
+    ├── task_plan.md
+    ├── progress.md
+    ├── findings.md
+    ├── genesis.md
+    ├── .agent/hub/
+    ├── .agents/skills/
+    ├── .githooks/
+    └── .tmp/
 ```
 
-<br/>
+Operational source of truth:
 
-### OPERA Methodology
+- split layout: `ops/project_control.json`
+- legacy layout: `project_control.json`
 
-Optional 5-phase framework for structured AI-assisted development. Each phase has a verifiable **Definition of Done**:
+### Environment and secrets
 
-| Phase | Name | Focus | Deliverable |
-|-------|------|-------|-------------|
-| **O** | Orchestrate | Vision, data, business rules | JSON schema in `genesis.md` |
-| **P** | Prove | Connectivity and validation | Passing test scripts |
-| **E** | Establish | 3-layer build | SOPs + tools + integration |
-| **R** | Refine | Refinement and quality | Validated outputs |
-| **A** | Automate | Deployment and triggers | Triggers + smoke test |
+TrackOps manages an explicit environment contract:
 
-Phases are fully configurable per project via `project_control.json`.
+- `/.env`
+  real secrets file for the workspace
+- `/.env.example`
+  public variable contract
+- `app/.env`
+  compatibility bridge for product tooling
 
-<br/>
+Main commands:
 
-### Command Reference
+```bash
+trackops env status
+trackops env sync
+```
 
-<details>
-<summary><strong>Core Engine</strong></summary>
+### Daily workflow
 
-| Command | Description |
-|---------|-------------|
-| `trackops init [--with-opera] [--locale es\|en]` | Initialize in current directory. `--with-etapa` remains as a legacy alias only. |
-| `trackops status` | State: focus, phase, tasks, blockers, repo |
-| `trackops next` | Next prioritized executable tasks |
-| `trackops sync` | Regenerate task_plan.md, progress.md, findings.md |
-| `trackops dashboard` | Launch local web dashboard |
-| `trackops task <action> <id> [note]` | start, review, complete, block, pending, cancel, note |
-| `trackops refresh-repo [--quiet]` | Update runtime with repo state |
-| `trackops register` | Register in multi-project portfolio |
-| `trackops projects` | List registered projects |
-
-</details>
-
-<details>
-<summary><strong>OPERA</strong></summary>
+```bash
+trackops status
+trackops next
+trackops sync
+trackops env status
+trackops dashboard
+```
 
-| Command | Description |
-|---------|-------------|
-| `trackops opera install` | Install OPERA methodology |
-| `trackops opera status` | Installation state and integrity |
-| `trackops opera configure [--phases '...']` | Reconfigure phases or locale |
-| `trackops opera upgrade` | Update templates to package version |
+Operating rules:
+
+- use `trackops status` to inspect focus, phase, and blockers
+- use `trackops next` to find the next ready task
+- use `trackops sync` to regenerate operational docs
+- do not hand-edit `task_plan.md`, `progress.md`, or `findings.md`
+
+The dashboard is local, finds a free port if the preferred one is busy, and can copy the URL to the clipboard.
 
-</details>
+### Main CLI
 
-<details>
-<summary><strong>Skills</strong></summary>
+#### Core
 
 | Command | Description |
-|---------|-------------|
-| `trackops skill install <name>` | Install skill from catalog |
-| `trackops skill list` | List installed skills |
-| `trackops skill remove <name>` | Uninstall skill |
-| `trackops skill catalog` | Show available skills |
+|---|---|
+| `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Initialize TrackOps in the current repo |
+| `trackops status` | Show the current operational state |
+| `trackops next` | Show the next ready tasks |
+| `trackops sync` | Regenerate operational docs |
+| `trackops workspace status` | Show workspace layout, roots, and publish configuration |
+| `trackops workspace migrate` | Migrate a legacy project to the `app/` + `ops/` layout |
+| `trackops env status` | Audit required, present, and missing keys without showing values |
+| `trackops env sync` | Create or regenerate `/.env`, `/.env.example`, and the `app/.env` bridge |
+| `trackops release [--push]` | Publish the configured branch from `app/` |
+| `trackops dashboard [--port N] [--host HOST] [--public] [--strict-port]` | Launch the local dashboard |
+| `trackops version` | Print the installed version |
+
+#### OPERA
 
-</details>
+| Command | Description |
+|---|---|
+| `trackops opera install [--locale es\|en] [--non-interactive] [--no-bootstrap]` | Install OPERA in the current project |
+| `trackops opera bootstrap [--locale es\|en] [--non-interactive]` | Resume the OPERA bootstrap |
+| `trackops opera status` | Show install and bootstrap state |
+| `trackops opera configure [--phases '...'] [--locale es\|en]` | Reconfigure phases or locale |
+| `trackops opera upgrade` | Update OPERA templates to the package version |
 
-<br/>
+#### Project skills
 
-### Project Structure
+`trackops skill ...` manages project-native skills. In split layout they live under `ops/.agents/skills/`.
 
-```
-my-project/
-├── project_control.json       # Operational source of truth
-├── task_plan.md               # Task plan (auto-generated)
-├── progress.md                # Progress log (auto-generated)
-├── findings.md                # Findings library (auto-generated)
-├── genesis.md                 # Project constitution (OPERA)
-├── .agent/hub/                # Agent identity + router (OPERA)
-└── .agents/skills/            # Installed skills (OPERA)
+```bash
+trackops skill catalog
+trackops skill install commiter
+trackops skill list
+trackops skill remove commiter
 ```
 
-**Package repository hygiene:** this repository only versions files that belong to `trackops` as a product. Artifacts generated when running `trackops` or `OPERA` on a project (`project_control.json`, `task_plan.md`, `progress.md`, `findings.md`, `genesis.md`, `.agent/`, `.agents/`, `.githooks/`) are considered runtime output and must not be committed to this repo.
+### Alternative path without the global skill
 
-<br/>
+If you do not want to use the skill distribution path:
 
-### Support the Project
-
-TrackOps is and will always be **free and open-source** (MIT). We built this to solve a real problem in the developer community.
+```bash
+npx trackops init
+npx trackops dashboard
+```
 
-If TrackOps has helped you regain control of your AI-assisted projects:
+Or install the package globally with npm:
 
-1. **Star us on GitHub** — it helps enormously with visibility.
-2. **Share TrackOps** with your team and on social media.
-3. **Support with USDC on Polygon** to help maintain documentation, improvements, and project support.
+```bash
+npm install -g trackops
+trackops init
+trackops opera install
+```
 
-   ```text
-   Network: Polygon
-   Asset: USDC
-   Address: 0x7B3d964247Dd309D13FF702649827947633e27F3
-   ```
+### Publish and validate
 
-   Send only `USDC` on `Polygon`. Do not send `BTC` or assets from other networks to this address.
-4. **Contribute** — Pull Requests, bug reports, and new Skills are always welcome.
+Before publishing:
 
-<br/>
+```bash
+trackops workspace status
+trackops env status
+npm run skill:validate
+npm run skill:smoke
+npm run release:check
+```
 
----
+In split projects, `trackops release` publishes only the contents of `app/` to the configured branch and includes `.env.example`. It never publishes `/.env`, `ops/`, or `.trackops-workspace.json`.
 
-<p align="center">
-  <a href="https://baxahaun.com"><strong>Xavier Crespo Gríman</strong></a> · <a href="https://baxahaun.com">Baxahaun AI Venture Studio</a>
-  <br/>
-  <a href="LICENSE">MIT License</a> · 2026
-</p>
+Extended guide: [UserGUIDE.md](./UserGUIDE.md)