trackops 1.0.1 → 2.0.0

package/README.md

@@ -5,407 +5,427 @@
 <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 projects built with AI agents.</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 para proyectos y desarrollo asistido por 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.
+Hace tres cosas:
 
-### El Problema: La IA es rápida. El caos también.
+1. prepara a tu agente con una skill global
+2. activa control operativo dentro de cada repo
+3. media entre el usuario y el agente cuando el proyecto todavía está poco definido
 
-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.
+### Modelo actual
 
-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.
+TrackOps trabaja en dos capas:
 
-### La Solución: TrackOps
+1. `skill global`
+   se instala una vez en tu agente o CLI
+2. `activación local por proyecto`
+   se ejecuta cuando decides gestionar un repo concreto
 
-TrackOps es un **motor operativo local de código abierto** que actúa como puente entre tú (el humano) y tus agentes de IA.
+La activación local tiene dos caminos:
 
-**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.
+- `arranque asistido por agente`
+  para ideas tempranas, usuarios poco técnicos o documentación insuficiente
+- `bootstrap directo`
+  para proyectos ya definidos y usuarios técnicos
 
-> **La IA se encarga del código. TrackOps se encarga del proyecto.**
+### Instalación global
 
-<br/>
+TrackOps se distribuye como skill global:
 
-### Por qué TrackOps se volverá indispensable en tu flujo
+```bash
+npx skills add Baxahaun/trackops
+```
 
-| | |
-|---|---|
-| **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. |
+La skill:
 
-<br/>
+- prepara el agente
+- asegura el runtime en el primer uso real
+- no modifica repos por sí sola
 
-### Inicio Rápido
+### Primer uso
 
-No necesitas instalar nada globalmente. Ve a cualquier proyecto y ejecuta:
+En el primer uso, la skill ejecuta:
 
 ```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 valida `Node.js >= 18`, valida `npm`, instala o actualiza `trackops` y registra el estado en `~/.trackops/runtime.json`.
 
-```bash
-npm run ops:status
-npm run ops:dashboard
-npm run ops:sync
-```
+### Activación local
 
-El flujo desde consola en tu día a día:
+Dentro de 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:
 
-<br/>
+- `trackops init`
+  activa TrackOps en el repo
+- `trackops opera install`
+  añade OPERA cuando quieres el framework operativo completo
+- `trackops init --with-opera`
+  existe como atajo
+- `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.
+Por defecto, TrackOps separa producto y operación:
 
-```
-┌─────────────────────────────────────────────────────┐
-│  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/
+│   └── ...producto real...
+└── ops/
+    ├── project_control.json
+    ├── contract/
+    │   └── operating-contract.json
+    ├── policy/
+    │   └── autonomy.json
+    ├── task_plan.md
+    ├── progress.md
+    ├── findings.md
+    ├── genesis.md
+    ├── bootstrap/
+    ├── .agent/
+    ├── .agents/
+    ├── .githooks/
+    └── .tmp/
 ```
 
-<br/>
+Fuente de verdad operativa:
 
-### Metodología OPERA
+- layout split: `ops/project_control.json`
+- layout legacy: `project_control.json`
 
-Framework opcional de 5 fases para desarrollo estructurado con IA. Cada fase tiene un **Definition of Done** verificable:
+### Dos formas de arrancar OPERA
 
-| 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 |
+#### Tengo una idea
 
-Las fases son totalmente configurables por proyecto vía `project_control.json`.
+Si el usuario no es técnico, el proyecto está en fase idea, o no hay documentación suficiente, OPERA no sigue con preguntas de arquitectura en terminal. En su lugar:
 
-<br/>
+1. pregunta nivel técnico, estado del proyecto y documentación disponible
+2. genera un handoff en `ops/bootstrap/agent-handoff.md`
+3. espera a que el agente produzca:
+   - `ops/bootstrap/intake.json`
+   - `ops/bootstrap/spec-dossier.md`
+   - `ops/bootstrap/open-questions.md` si quedan huecos importantes
+4. reanudas con:
 
-### Referencia de Comandos
+```bash
+trackops opera bootstrap --resume
+```
 
-<details>
-<summary><strong>Motor Core</strong></summary>
+#### Ya tengo un repo
 
-| 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>
+Si el usuario es técnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo, compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md`.
 
-| 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 |
+También puedes forzar el modo:
 
-</details>
+```bash
+trackops opera install --bootstrap-mode handoff
+trackops opera install --bootstrap-mode direct
+```
 
-<details>
-<summary><strong>Skills</strong></summary>
+Flags disponibles:
 
-| 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 |
+- `--technical-level low|medium|high|senior`
+- `--project-state idea|draft|existing_repo|advanced`
+- `--docs-state none|notes|sos|spec_dossier|repo_docs`
+- `--decision-ownership user|shared|agent`
 
-</details>
+### Entorno y secretos
 
-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`.
+TrackOps gestiona un contrato explícito de entorno:
 
-<br/>
+- `/.env`
+  secretos reales del workspace
+- `/.env.example`
+  contrato público de variables
+- `app/.env`
+  puente de compatibilidad
 
-### Estructura del Proyecto
+Comandos:
 
+```bash
+trackops env status
+trackops env sync
 ```
-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 nunca imprime ni persiste valores sensibles en docs, dashboard o `project_control.json`.
+
+### Idioma
+
+TrackOps puede trabajar con:
+
+- idioma global en `~/.trackops/runtime.json`
+- idioma por proyecto en `ops/project_control.json`
+
+Comandos:
+
+```bash
+trackops locale get
+trackops locale set es
+trackops doctor locale
 ```
 
-**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.
+### Trabajo diario
 
-<br/>
+```bash
+trackops status
+trackops next
+trackops sync
+trackops env status
+trackops dashboard
+```
 
-### Apoya el Proyecto
+Reglas:
 
-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.
+- usa `trackops status` para leer foco, fase y bloqueadores
+- usa `trackops next` para ver la siguiente tarea lista
+- usa `trackops sync` para regenerar docs operativos
+- no edites a mano `task_plan.md`, `progress.md` ni `findings.md`
 
-Si TrackOps te ha ayudado a recuperar el control de tus proyectos con IA:
+### CLI principal
 
-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.
+#### Core
 
-   ```text
-   Red: Polygon
-   Moneda: USDC
-   Dirección: 0x7B3d964247Dd309D13FF702649827947633e27F3
-   ```
+| Comando | Descripción |
+|---|---|
+| `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa TrackOps |
+| `trackops status` | Muestra estado operativo |
+| `trackops next` | Muestra la siguiente cola priorizada |
+| `trackops sync` | Regenera docs operativos |
+| `trackops workspace status` | Muestra layout y roots |
+| `trackops workspace migrate` | Migra un proyecto legacy |
+| `trackops env status` | Audita claves presentes y faltantes |
+| `trackops env sync` | Regenera `/.env`, `/.env.example` y el puente |
+| `trackops locale get\|set [es\|en]` | Lee o fija el idioma global |
+| `trackops doctor locale` | Explica el origen del idioma efectivo |
+| `trackops release [--push]` | Publica la rama configurada desde `app/` |
+| `trackops dashboard` | Lanza el dashboard local |
+
+#### OPERA
 
-   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.
+| Comando | Descripción |
+|---|---|
+| `trackops opera install [--bootstrap-mode ...] [--technical-level ...] [--project-state ...] [--docs-state ...] [--decision-ownership ...]` | Instala OPERA y decide la ruta de bootstrap |
+| `trackops opera bootstrap [--resume]` | Continúa el bootstrap o ingiere el resultado del agente |
+| `trackops opera handoff [--print\|--json]` | Muestra el handoff listo para copiar al agente |
+| `trackops opera status` | Muestra estado de instalación y bootstrap |
+| `trackops opera configure` | Reconfigura idioma o fases |
+| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la versión estable actual |
 
-<br/>
+### Skills del proyecto
 
----
+Hay dos conceptos distintos:
 
-## English
+- la skill global `trackops`
+  prepara el sistema
+- `trackops skill ...`
+  gestiona skills nativas del proyecto en `ops/.agents/skills/`
 
-> **Beta status:** TrackOps is already usable, but it is still evolving quickly. The interface, commands, and some flows may change between releases.
+### Publicación
 
-> **Disclaimer:** Always review generated files, automated changes, and agent output before using them in sensitive or production projects.
+Antes de publicar:
 
-### The Problem: AI is fast. So is chaos.
+```bash
+trackops workspace status
+trackops env status
+npm run skill:validate
+npm run skill:smoke
+npm run release:check
+```
 
-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 release` publica solo `app/`, incluye `.env.example` y no publica `/.env`, `ops/` ni `.trackops-workspace.json`.
 
-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.
+Guía ampliada: [UserGUIDE.md](./UserGUIDE.md)
 
-### The Solution: TrackOps
+---
 
-TrackOps is a **local, open-source operational engine** that acts as a bridge between you (the human) and your AI agents.
+## English
 
-**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.
+TrackOps is a local orchestration and operational automation system for projects and AI-agent development.
 
-> **AI handles the code. TrackOps handles the project.**
+It does three things:
 
-<br/>
+1. prepares your agent with a global skill
+2. activates operational control inside each repository
+3. mediates between the user and the agent when the project is still loosely defined
 
-### Why TrackOps will become essential in your workflow
+### Current model
 
-| | |
-|---|---|
-| **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>`. |
+TrackOps works in two layers:
 
-<br/>
+1. `global skill`
+   installed once in the agent or CLI
+2. `local per-project activation`
+   run when you decide to manage a specific repository
 
-### Quick Start
+Local activation has two paths:
 
-No global install needed. Go to any project and run:
+- `agent-led start`
+  for early ideas, non-technical users, or weak documentation
+- `direct bootstrap`
+  for already defined projects and technical users
 
-```bash
-npx trackops init               # Initialize the engine in your project
-npx trackops dashboard           # Launch the web control center
-```
+### Global install
 
-After `init`, npm shortcuts are also ready to use inside the project:
+Install the global skill with:
 
 ```bash
-npm run ops:status
-npm run ops:dashboard
-npm run ops:sync
+npx skills add Baxahaun/trackops
 ```
 
-Your daily workflow from the console:
+The skill prepares the agent, ensures the runtime on first use, and does not mutate repositories by itself.
+
+### First use
+
+On first use the skill runs:
 
 ```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
+node scripts/bootstrap-trackops.js
 ```
 
-Step-by-step user guide: [UserGUIDE.md](UserGUIDE.md)
+It validates `Node.js >= 18`, validates `npm`, installs or updates `trackops`, and records state in `~/.trackops/runtime.json`.
 
-<br/>
+### Local activation
 
-### 3-Layer Architecture
+Inside a repository:
 
-Designed to scale from a weekend script to enterprise infrastructure.
-
-```
-┌─────────────────────────────────────────────────────┐
-│  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    │
-└─────────────────────────────────────────────────────┘
+```bash
+trackops init
+trackops opera install
 ```
 
-<br/>
-
-### OPERA Methodology
+### Split workspace
 
-Optional 5-phase framework for structured AI-assisted development. Each phase has a verifiable **Definition of Done**:
+TrackOps separates product and operations by default:
 
-| 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 |
+```text
+my-project/
+├── .trackops-workspace.json
+├── .env
+├── .env.example
+├── app/
+└── ops/
+    ├── project_control.json
+    ├── contract/
+    │   └── operating-contract.json
+    ├── policy/
+    │   └── autonomy.json
+    ├── task_plan.md
+    ├── progress.md
+    ├── findings.md
+    ├── genesis.md
+    ├── bootstrap/
+    ├── .agent/
+    ├── .agents/
+    ├── .githooks/
+    └── .tmp/
+```
 
-Phases are fully configurable per project via `project_control.json`.
+Operational source of truth:
 
-<br/>
+- split layout: `ops/project_control.json`
+- legacy layout: `project_control.json`
 
-### Command Reference
+### Two ways to start OPERA
 
-<details>
-<summary><strong>Core Engine</strong></summary>
+#### I only have an idea
 
-| 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 |
+If the user is not technical, the project is still in idea stage, or documentation is weak, OPERA does not keep asking architecture questions in the terminal. Instead it:
 
-</details>
+1. asks for technical level, project state, and available documentation
+2. writes a handoff in `ops/bootstrap/agent-handoff.md`
+3. waits for the agent to produce:
+   - `ops/bootstrap/intake.json`
+   - `ops/bootstrap/spec-dossier.md`
+   - `ops/bootstrap/open-questions.md` when important gaps remain
+4. resumes with:
 
-<details>
-<summary><strong>OPERA</strong></summary>
+```bash
+trackops opera bootstrap --resume
+```
 
-| 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 |
+#### I already have a repository
 
-</details>
+If the user is technical and the project already has enough context, OPERA continues with direct bootstrap, compiles `ops/contract/operating-contract.json`, and recompiles `ops/genesis.md`.
 
-<details>
-<summary><strong>Skills</strong></summary>
+You can also force the mode:
 
-| 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 |
+```bash
+trackops opera install --bootstrap-mode handoff
+trackops opera install --bootstrap-mode direct
+```
 
-</details>
+### Environment and secrets
 
-<br/>
+TrackOps manages:
 
-### Project Structure
+- `/.env`
+  real workspace secrets
+- `/.env.example`
+  public variable contract
+- `app/.env`
+  compatibility bridge
 
-```
-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)
-```
+### Language
 
-**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.
+TrackOps can work with:
 
-<br/>
+- a global language in `~/.trackops/runtime.json`
+- a per-project language in `ops/project_control.json`
 
-### Support the Project
+Commands:
 
-TrackOps is and will always be **free and open-source** (MIT). We built this to solve a real problem in the developer community.
+```bash
+trackops locale get
+trackops locale set en
+trackops doctor locale
+```
 
-If TrackOps has helped you regain control of your AI-assisted projects:
+### Daily workflow
 
-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
+trackops status
+trackops next
+trackops sync
+trackops env status
+trackops dashboard
+```
 
-   ```text
-   Network: Polygon
-   Asset: USDC
-   Address: 0x7B3d964247Dd309D13FF702649827947633e27F3
-   ```
+### Main CLI
 
-   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.
+Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff` and `trackops opera bootstrap --resume`.
 
-<br/>
+### Publishing
 
----
+`trackops release` publishes only `app/`, includes `.env.example`, and 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)