trackops 1.0.0 → 1.1.0

package/README.md

@@ -1,358 +1,467 @@
 <p align="center">
-  <img src="docs/assets/TrackOps.webp" alt="TrackOps" width="400" />
+  <img src="docs/assets/logo.svg" alt="TrackOps Logo" width="96" height="96" />
 </p>
 
 <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/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
 
-### El Problema: La IA es rápida. El caos también.
+TrackOps es un sistema local de orquestación y automatización operativa de proyectos y desarrollo con agentes IA.
 
-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.
+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.
 
-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.
+### Modelo actual
 
-### La Solución: TrackOps
+TrackOps funciona con dos capas:
 
-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. `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
 
-**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.
+El flujo oficial es este:
 
-> **La IA se encarga del código. TrackOps se encarga del proyecto.**
+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`
 
-<br/>
+### Instalación global
 
-### Por qué TrackOps se volverá indispensable en tu flujo
+TrackOps se distribuye como skill global desde el ecosistema `skills`.
 
-| | |
-|---|---|
-| **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** | Plugins modulares que dotan a tu proyecto de capacidades automatizadas: `trackops skill install <nombre>`. |
+```bash
+npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+```
+
+Targets soportados en la skill:
 
-<br/>
+- `antigravity`
+- `claude-code`
+- `codex`
+- `cursor`
+- `gemini-cli`
+- `github-copilot`
+- `kiro-cli`
 
-### Inicio Rápido
+La skill global:
 
-No necesitas instalar nada globalmente. Ve a cualquier proyecto y ejecuta:
+- hace disponible TrackOps para tu agente
+- asegura el runtime npm en primer uso
+- no modifica repos por sí sola
+
+### Bootstrap del runtime
+
+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
 ```
 
-El flujo desde consola en tu día a día:
+Ese bootstrap:
+
+- 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
+
+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
 ```
 
-<br/>
+Semántica oficial:
 
-### Arquitectura de 3 Capas
+- `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
 
-Diseñado para escalar desde un script de fin de semana hasta infraestructura empresarial.
+### Workspace split
 
-```
-┌─────────────────────────────────────────────────────┐
-│  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   │
-└─────────────────────────────────────────────────────┘
+TrackOps separa tu producto real en `app/` y la operación en `ops/`, para que no se mezclen.
+
+```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 |
-| `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:
+
+- 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`
+
+El dashboard es local, encuentra un puerto libre si el preferido está ocupado y puede copiar la URL al portapapeles.
 
-</details>
+### CLI principal
 
-<details>
-<summary><strong>Skills</strong></summary>
+#### Core
 
 | 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 |
+|---|---|
+| `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
 
-</details>
+| 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 |
 
-<br/>
+#### Skills del proyecto
 
-### Estructura del Proyecto
+`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
 ```
-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)
+
+### Vía alternativa sin skill global
+
+Si no quieres usar la distribución por skill:
+
+```bash
+npx trackops init
+npx trackops dashboard
 ```
 
-<br/>
+O instala el paquete globalmente con npm:
 
-### Apoya el Proyecto
+```bash
+npm install -g trackops
+trackops init
+trackops opera install
+```
 
-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.
+### Publicación y validación
 
-Si TrackOps te ha ayudado a recuperar el control de tus proyectos con IA:
+Antes de publicar:
 
-1. **Dale una estrella en GitHub** — ayuda enormemente a la visibilidad.
-2. **Comparte TrackOps** con tu equipo y en tus redes.
-3. **Contribuye** — Pull Requests, reporte de bugs y nuevas Skills son siempre bienvenidos.
+```bash
+trackops workspace status
+trackops env status
+npm run skill:validate
+npm run skill:smoke
+npm run release:check
+```
 
-<br/>
+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`.
+
+Guía ampliada: [UserGUIDE.md](./UserGUIDE.md)
 
 ---
 
 ## English
 
-### The Problem: AI is fast. So is chaos.
+TrackOps is a local orchestration and operational automation system for projects and AI-agent development.
 
-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.
+It prepares your agents, organizes project execution, and keeps the real app separate from the operational layer, without depending on an external cloud.
 
-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.
+### Current model
 
-### The Solution: TrackOps
+TrackOps works in two layers:
 
-TrackOps is a **local, open-source operational engine** that acts as a bridge between you (the human) and your AI agents.
+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
 
-**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.
+Official flow:
 
-> **AI handles the code. TrackOps handles the project.**
+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`
 
-<br/>
+### Global install
 
-### Why TrackOps will become essential in your workflow
+TrackOps is distributed as a global skill through the `skills` ecosystem.
 
-| | |
-|---|---|
-| **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>`. |
+```bash
+npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+```
+
+Supported skill targets:
+
+- `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
 ```
 
-Your daily workflow from the console:
+That bootstrap:
+
+- validates `Node.js >= 18`
+- validates `npm`
+- installs or updates `trackops`
+- verifies the command
+- records state in `~/.trackops/runtime.json`
+
+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
 ```
 
-<br/>
+Official semantics:
 
-### 3-Layer Architecture
+- `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
 
-Designed to scale from a weekend script to enterprise infrastructure.
+### Split workspace
 
-```
-┌─────────────────────────────────────────────────────┐
-│  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    │
-└─────────────────────────────────────────────────────┘
+TrackOps separates your real product into `app/` and operations into `ops/`, so they do not get mixed.
+
+```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 |
-| `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`
 
-</details>
+The dashboard is local, finds a free port if the preferred one is busy, and can copy the URL to the clipboard.
 
-<details>
-<summary><strong>Skills</strong></summary>
+### Main CLI
+
+#### 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/`.
 
+```bash
+trackops skill catalog
+trackops skill install commiter
+trackops skill list
+trackops skill remove commiter
 ```
-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)
-```
 
-<br/>
+### Alternative path without the global skill
+
+If you do not want to use the skill distribution path:
+
+```bash
+npx trackops init
+npx trackops dashboard
+```
 
-### Support the Project
+Or install the package globally with npm:
 
-TrackOps is and will always be **free and open-source** (MIT). We built this to solve a real problem in the developer community.
+```bash
+npm install -g trackops
+trackops init
+trackops opera install
+```
 
-If TrackOps has helped you regain control of your AI-assisted projects:
+### Publish and validate
 
-1. **Star us on GitHub** — it helps enormously with visibility.
-2. **Share TrackOps** with your team and on social media.
-3. **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)