trackops 2.0.1 → 2.0.3

package/README.md

@@ -15,62 +15,59 @@
 </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="#espanol">Espanol</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#english">English</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://baxahaun.github.io/trackops/">Web</a>
 </p>
 
 ---
 
-## Español
+## Espanol
 
-TrackOps es un sistema local de orquestación y automatización operativa para proyectos y desarrollo asistido por agentes IA.
+TrackOps es un sistema local de orquestacion y automatizacion operativa para proyectos y desarrollo asistido por agentes IA.
 
 Hace tres cosas:
 
-1. prepara a tu agente con una skill global
+1. prepara al 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
+3. media entre el usuario y el agente cuando el proyecto aun esta poco definido
 
 ### Modelo actual
 
 TrackOps trabaja en dos capas:
 
 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
+   se instala una vez en el agente
+2. `runtime + activacion local`
+   se instalan y ejecutan cuando decides gestionar una maquina y un repo concretos
 
-La activación local tiene dos caminos:
+La activacion local tiene dos caminos:
 
 - `arranque asistido por agente`
-  para ideas tempranas, usuarios poco técnicos o documentación insuficiente
+  para ideas tempranas, usuarios poco tecnicos o documentacion insuficiente
 - `bootstrap directo`
-  para proyectos ya definidos y usuarios técnicos
+  para proyectos ya definidos y usuarios tecnicos
 
-### Instalación global
+### Instalacion global
 
-TrackOps se distribuye como skill global:
+Instala la skill global:
 
 ```bash
 npx skills add Baxahaun/trackops
 ```
 
-La skill:
-
-- prepara el agente
-- asegura el runtime en el primer uso real
-- no modifica repos por sí sola
-
-### Primer uso
-
-En el primer uso, la skill ejecuta:
+Instala el runtime de forma explicita:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-Ese bootstrap valida `Node.js >= 18`, valida `npm`, instala o actualiza `trackops` y registra el estado en `~/.trackops/runtime.json`.
+Esta separacion es intencional:
+
+- la skill se audita como capa de instrucciones
+- el runtime se instala con un paso visible y verificable
+- no hay instalacion transitiva oculta desde la propia skill
 
-### Activación local
+### Activacion local
 
 Dentro de un repo:
 
@@ -79,12 +76,12 @@ trackops init
 trackops opera install
 ```
 
-Semántica:
+Semantica:
 
 - `trackops init`
   activa TrackOps en el repo
 - `trackops opera install`
-  añade OPERA cuando quieres el framework operativo completo
+  anade OPERA cuando quieres el framework operativo completo
 - `trackops init --with-opera`
   existe como atajo
 - `trackops init --legacy-layout`
@@ -92,30 +89,30 @@ Semántica:
 
 ### Workspace split
 
-Por defecto, TrackOps separa producto y operación:
+Por defecto, TrackOps separa producto y operacion:
 
 ```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/
+|- .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/
 ```
 
 Fuente de verdad operativa:
@@ -127,9 +124,9 @@ Fuente de verdad operativa:
 
 #### Tengo una idea
 
-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:
+Si el usuario no es tecnico, el proyecto esta en fase idea, o no hay documentacion suficiente, OPERA no sigue con preguntas de arquitectura en terminal. En su lugar:
 
-1. pregunta nivel técnico, estado del proyecto y documentación disponible
+1. pregunta nivel tecnico, estado del proyecto y documentacion disponible
 2. genera un handoff en `ops/bootstrap/agent-handoff.md`
 3. espera a que el agente produzca:
    - `ops/bootstrap/intake.json`
@@ -143,9 +140,9 @@ trackops opera bootstrap --resume
 
 #### Ya tengo un repo
 
-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`.
+Si el usuario es tecnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo, compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md`.
 
-También puedes forzar el modo:
+Tambien puedes forzar el modo:
 
 ```bash
 trackops opera install --bootstrap-mode handoff
@@ -161,12 +158,12 @@ Flags disponibles:
 
 ### Entorno y secretos
 
-TrackOps gestiona un contrato explícito de entorno:
+TrackOps gestiona un contrato explicito de entorno:
 
 - `/.env`
   secretos reales del workspace
 - `/.env.example`
-  contrato público de variables
+  contrato publico de variables
 - `app/.env`
   puente de compatibilidad
 
@@ -194,28 +191,9 @@ trackops locale set es
 trackops doctor locale
 ```
 
-### Trabajo diario
-
-```bash
-trackops status
-trackops next
-trackops sync
-trackops env status
-trackops dashboard
-```
-
-Reglas:
-
-- 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`
-
 ### CLI principal
 
-#### Core
-
-| Comando | Descripción |
+| Comando | Descripcion |
 |---|---|
 | `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa TrackOps |
 | `trackops status` | Muestra estado operativo |
@@ -229,28 +207,23 @@ Reglas:
 | `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
-
-| 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 bootstrap [--resume]` | Continua 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 status` | Muestra estado de instalacion y bootstrap |
 | `trackops opera configure` | Reconfigura idioma o fases |
-| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la versión estable actual |
+| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la version estable actual |
 
 ### Skills del proyecto
 
 Hay dos conceptos distintos:
 
 - la skill global `trackops`
-  prepara el sistema
+  prepara al agente y guia el flujo
 - `trackops skill ...`
   gestiona skills nativas del proyecto en `ops/.agents/skills/`
 
-### Publicación
+### Publicacion
 
 Antes de publicar:
 
@@ -264,7 +237,7 @@ npm run release:check
 
 `trackops release` publica solo `app/`, incluye `.env.example` y no publica `/.env`, `ops/` ni `.trackops-workspace.json`.
 
-Guía ampliada: [UserGUIDE.md](./UserGUIDE.md)
+Guia ampliada: [UserGUIDE.md](./UserGUIDE.md)
 
 ---
 
@@ -274,7 +247,7 @@ TrackOps is a local orchestration and operational automation system for projects
 
 It does three things:
 
-1. prepares your agent with a global skill
+1. prepares the 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
 
@@ -283,9 +256,9 @@ It does three things:
 TrackOps works in two layers:
 
 1. `global skill`
-   installed once in the agent or CLI
-2. `local per-project activation`
-   run when you decide to manage a specific repository
+   installed once in the agent
+2. `runtime + local activation`
+   installed and used when you decide to manage a specific machine and repository
 
 Local activation has two paths:
 
@@ -296,23 +269,24 @@ Local activation has two paths:
 
 ### Global install
 
-Install the global skill with:
+Install the global skill:
 
 ```bash
 npx skills add Baxahaun/trackops
 ```
 
-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:
+Install the runtime explicitly:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-It validates `Node.js >= 18`, validates `npm`, installs or updates `trackops`, and records state in `~/.trackops/runtime.json`.
+This split is intentional:
+
+- the skill is audited as an instruction layer
+- the runtime is installed through a visible and verifiable step
+- there is no hidden transitive install from the skill itself
 
 ### Local activation
 
@@ -329,25 +303,25 @@ TrackOps separates product and operations by default:
 
 ```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/
+|- .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/
 ```
 
 Operational source of truth:
@@ -395,6 +369,13 @@ TrackOps manages:
 - `app/.env`
   compatibility bridge
 
+Use:
+
+```bash
+trackops env status
+trackops env sync
+```
+
 ### Language
 
 TrackOps can work with:
@@ -410,19 +391,9 @@ trackops locale set en
 trackops doctor locale
 ```
 
-### Daily workflow
-
-```bash
-trackops status
-trackops next
-trackops sync
-trackops env status
-trackops dashboard
-```
-
 ### Main CLI
 
-Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff` and `trackops opera bootstrap --resume`.
+Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff`, `trackops opera bootstrap --resume`, and the explicit `npm install -g trackops` runtime step.
 
 ### Publishing
 

package/locales/en.json

@@ -125,8 +125,8 @@
   "cli.help.skill.desc": "Manage skills.",
   "cli.help.help.desc": "Show this help.",
   "cli.help.globalWorkflow": "Global agent workflow:",
-  "cli.help.globalWorkflow.line1": "Install with 'npx skills add Baxahaun/trackops'",
-  "cli.help.globalWorkflow.line2": "and the global/agent flags you need; then use 'trackops init' and 'trackops opera install' explicitly inside each project.",
+  "cli.help.globalWorkflow.line1": "Install the skill with 'npx skills add Baxahaun/trackops' and then the runtime with 'npm install -g trackops'.",
+  "cli.help.globalWorkflow.line2": "Then verify with 'trackops --version' and use 'trackops init' and 'trackops opera install' explicitly inside each project.",
   "cli.usage.workspace": "Usage: trackops workspace <status|migrate>",
   "cli.usage.env": "Usage: trackops env <status|sync>",
   "cli.usage.opera": "Usage: trackops opera <install|bootstrap|handoff|status|configure|upgrade>",

package/locales/es.json

@@ -125,8 +125,8 @@
   "cli.help.skill.desc": "Gestiona skills.",
   "cli.help.help.desc": "Muestra esta ayuda.",
   "cli.help.globalWorkflow": "Flujo global del agente:",
-  "cli.help.globalWorkflow.line1": "Instala con 'npx skills add Baxahaun/trackops'",
-  "cli.help.globalWorkflow.line2": "y los flags globales/de agente que necesites; despues usa 'trackops init' y 'trackops opera install' de forma explicita dentro de cada proyecto.",
+  "cli.help.globalWorkflow.line1": "Instala la skill con 'npx skills add Baxahaun/trackops' y luego el runtime con 'npm install -g trackops'.",
+  "cli.help.globalWorkflow.line2": "Despues verifica con 'trackops --version' y usa 'trackops init' y 'trackops opera install' de forma explicita dentro de cada proyecto.",
   "cli.usage.workspace": "Uso: trackops workspace <status|migrate>",
   "cli.usage.env": "Uso: trackops env <status|sync>",
   "cli.usage.opera": "Uso: trackops opera <install|bootstrap|handoff|status|configure|upgrade>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackops",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Operational project control with task management, document generation, multi-project dashboard, and optional OPERA methodology",
   "main": "lib/control.js",
   "bin": {

package/scripts/skills-marketplace-smoke.js

@@ -108,9 +108,9 @@ function main() {
   assert.ok(installed.length >= 1, `trackops skill was not installed under ${homeRoot}`);
 
   const installedSkillDir = installed[0];
-  assert.ok(fs.existsSync(path.join(installedSkillDir, "scripts", "bootstrap-trackops.js")));
   assert.ok(fs.existsSync(path.join(installedSkillDir, "references", "activation.md")));
   assert.ok(fs.existsSync(path.join(installedSkillDir, "skill.json")));
+  assert.ok(!fs.existsSync(path.join(installedSkillDir, "scripts", "bootstrap-trackops.js")));
 
   fs.rmSync(tempRoot, { recursive: true, force: true });
   console.log("skills marketplace smoke OK");

package/scripts/smoke-tests.js

@@ -11,7 +11,6 @@ const { spawn, spawnSync } = require("child_process");
 const ROOT = path.resolve(__dirname, "..");
 const BIN = path.join(ROOT, "bin", "trackops.js");
 const SKILL_VALIDATE = path.join(ROOT, "scripts", "validate-skill.js");
-const SKILL_BOOTSTRAP = path.join(ROOT, "skills", "trackops", "scripts", "bootstrap-trackops.js");
 
 function getNpmCommand() {
   return process.platform === "win32" ? "npm.cmd" : "npm";
@@ -220,17 +219,12 @@ async function main() {
   const bootstrapEnv = {
     TRACKOPS_BOOTSTRAP_HOME: bootstrapHome,
     TRACKOPS_BOOTSTRAP_PREFIX: bootstrapPrefix,
-    TRACKOPS_BOOTSTRAP_INSTALL_SOURCE: tarballPath,
   };
 
-  const firstBootstrap = runCommand(process.execPath, [SKILL_BOOTSTRAP], tempRoot, bootstrapEnv);
-  assert.strictEqual(firstBootstrap.status, 0, firstBootstrap.stderr || firstBootstrap.stdout || "bootstrap skill fallo");
-  assert.match(firstBootstrap.stdout, /TrackOps runtime .* is ready/i);
+  const explicitInstall = runNpm(["install", "-g", "--prefix", bootstrapPrefix, tarballPath], tempRoot, bootstrapEnv);
+  assert.strictEqual(explicitInstall.status, 0, explicitInstall.stderr || explicitInstall.stdout || "instalacion global explicita fallo");
 
   const runtimeStamp = readJson(path.join(bootstrapHome, ".trackops", "runtime.json"));
-  assert.strictEqual(runtimeStamp.runtimeVersion, packageVersion);
-  assert.strictEqual(runtimeStamp.skill, "trackops");
-  assert.strictEqual(runtimeStamp.bootstrapPolicy, "first_use");
   assert.ok(["es", "en"].includes(runtimeStamp.locale), "el bootstrap global debe fijar un idioma");
 
   const installedCli = path.join(bootstrapPrefix, "node_modules", "trackops", "bin", "trackops.js");
@@ -238,16 +232,6 @@ async function main() {
   const installedVersion = runNode([installedCli, "--version"], tempRoot);
   assert.strictEqual(installedVersion.trim(), packageVersion);
 
-  const secondBootstrap = runCommand(process.execPath, [SKILL_BOOTSTRAP], tempRoot, bootstrapEnv);
-  assert.strictEqual(secondBootstrap.status, 0, secondBootstrap.stderr || secondBootstrap.stdout || "bootstrap idempotente fallo");
-  assert.match(secondBootstrap.stdout, /already ready/i);
-
-  const untouchedRepo = path.join(tempRoot, "untouched-repo");
-  fs.mkdirSync(untouchedRepo, { recursive: true });
-  const bootstrapNoRepoMutation = runCommand(process.execPath, [SKILL_BOOTSTRAP], untouchedRepo, bootstrapEnv);
-  assert.strictEqual(bootstrapNoRepoMutation.status, 0, bootstrapNoRepoMutation.stderr || bootstrapNoRepoMutation.stdout || "bootstrap repetido fallo");
-  assert.ok(!fs.existsSync(path.join(untouchedRepo, "project_control.json")), "la skill global no debe crear artefactos de proyecto por si sola");
-
   const helpOutput = runNode([BIN, "help"], ROOT);
   assert.doesNotMatch(helpOutput, /\btrackops agent\b/i);
   assert.match(helpOutput, /workspace status\|migrate/i);

package/scripts/validate-skill.js

@@ -10,7 +10,6 @@ const SKILL_FILE = path.join(SKILL_DIR, "skill.json");
 const REQUIRED_FILES = [
   path.join(SKILL_DIR, "SKILL.md"),
   path.join(SKILL_DIR, "skill.json"),
-  path.join(SKILL_DIR, "scripts", "bootstrap-trackops.js"),
   path.join(SKILL_DIR, "references", "activation.md"),
   path.join(SKILL_DIR, "references", "workflow.md"),
   path.join(SKILL_DIR, "references", "troubleshooting.md"),
@@ -48,8 +47,8 @@ function main() {
     fail(`skills/trackops/skill.json must target npm package '${pkg.name}'.`);
   }
 
-  if (skill.bootstrapPolicy !== "first_use") {
-    fail("skills/trackops/skill.json must use bootstrapPolicy 'first_use'.");
+  if (skill.bootstrapPolicy !== "explicit_install") {
+    fail("skills/trackops/skill.json must use bootstrapPolicy 'explicit_install'.");
   }
 
   const supportedAgents = Array.isArray(skill.supportedAgentsV1) ? skill.supportedAgentsV1 : [];
@@ -73,7 +72,8 @@ function main() {
 
   for (const requiredPhrase of [
     "npx skills add Baxahaun/trackops",
-    "node scripts/bootstrap-trackops.js",
+    "npm install -g trackops",
+    "trackops --version",
     "trackops init",
     "trackops opera install",
     "trackops opera bootstrap --resume",
@@ -83,6 +83,20 @@ function main() {
     }
   }
 
+  for (const forbiddenPhrase of [
+    "node scripts/bootstrap-trackops.js",
+    "ensures the runtime on first use",
+    "asegura el runtime en el primer uso",
+  ]) {
+    if (skillMd.includes(forbiddenPhrase)) {
+      fail(`skills/trackops/SKILL.md must not mention '${forbiddenPhrase}'.`);
+    }
+  }
+
+  if (fs.existsSync(path.join(SKILL_DIR, "scripts", "bootstrap-trackops.js"))) {
+    fail("skills/trackops must not publish scripts/bootstrap-trackops.js.");
+  }
+
   console.log("skills/trackops validated successfully.");
 }
 

package/skills/trackops/SKILL.md

@@ -1,13 +1,40 @@
 ---
 name: "trackops"
-description: "Skill global de TrackOps para instalar y activar la orquestacion local de proyectos con OPERA, entorno y handoff a agentes. Usala cuando el usuario quiera instalar TrackOps desde skills.sh, bootstrapear el runtime con `node scripts/bootstrap-trackops.js`, ejecutar `trackops init`, ejecutar `trackops opera install`, revisar `trackops opera handoff`, o trabajar sobre el flujo operativo de un repositorio."
+description: "Skill global de TrackOps para explicar que hace TrackOps, exigir la instalacion explicita del runtime con npm y guiar la activacion local de proyectos y OPERA en cada repositorio."
 ---
 
 # TrackOps
 
 Si la conversacion y el proyecto deben trabajar en ingles, lee `locales/en/SKILL.md` antes de seguir.
 
-## Capa global
+TrackOps sirve para trabajar con agentes sobre proyectos reales sin mezclar la aplicacion y la capa operativa.
+
+Esta skill es la puerta de entrada cuando alguien:
+
+- quiere arrancar un proyecto con agentes IA
+- ya tiene un repo y necesita orden operativo
+- necesita activar TrackOps y, si hace falta, OPERA
+- quiere trabajar en espanol o en ingles con el mismo flujo
+
+## Que hace esta skill
+
+Esta skill:
+
+- explica que es TrackOps y cuando conviene usarlo
+- exige una instalacion explicita y visible del runtime
+- guia la activacion por repositorio
+- ayuda a decidir si OPERA debe seguir por `direct bootstrap` o por `agent handoff`
+
+## Que no hace esta skill
+
+Esta skill no:
+
+- instala paquetes por su cuenta
+- ejecuta codigo remoto en silencio
+- modifica un repositorio antes de que el runtime exista
+- sustituye al runtime `trackops`
+
+## Flujo rapido
 
 Instala la skill del marketplace con:
 
@@ -15,21 +42,21 @@ Instala la skill del marketplace con:
 npx skills add Baxahaun/trackops
 ```
 
-Antes de depender del CLI, ejecuta el script empaquetado de la skill:
+Despues, confirma que el runtime `trackops` existe. Si no esta disponible, pide al usuario que lo instale de forma explicita:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-Ese bootstrap:
+Reglas:
 
-- asegura el runtime npm de `trackops`
-- valida que el binario global sea ejecutable
-- registra estado en `~/.trackops/runtime.json`
+- la skill no debe instalar paquetes ni ejecutar codigo remoto por si sola
+- el runtime se instala con un paso visible y auditable
+- la skill puede verificar `trackops --version`, pero no debe encadenar instalaciones silenciosas
+- la skill no debe crear archivos dentro de un repositorio por si sola
 
-No debe crear archivos dentro de un repositorio por si solo.
-
-## Capa local del proyecto
+## Activacion en un proyecto
 
 Dentro del repositorio:
 
@@ -40,7 +67,8 @@ trackops opera install
 
 Reglas base:
 
-- trata la instalacion global como no invasiva
+- trata la skill global como capa de instrucciones
+- trata la instalacion del runtime como explicita y separada
 - usa `ops/contract/operating-contract.json` como contrato de maquina cuando exista
 - usa `ops/project_control.json` como fuente de verdad operativa
 - usa `ops/policy/autonomy.json` antes de acciones sensibles
@@ -48,7 +76,7 @@ Reglas base:
 - deja la documentacion operativa generada dentro de `ops/`
 - usa `trackops locale get|set` y `trackops doctor locale` cuando el idioma importe
 
-## Onboarding de OPERA
+## Como entra OPERA
 
 OPERA ya no asume que todo usuario es tecnico.
 
@@ -79,8 +107,16 @@ Si TrackOps deriva al agente:
 trackops opera bootstrap --resume
 ```
 
+## Que debe entender alguien que llega desde skills.sh
+
+- la skill global instala instrucciones en el agente
+- el runtime se instala por separado con npm
+- `trackops init` activa el proyecto
+- `trackops opera install` anade el framework operativo completo solo cuando hace falta
+- TrackOps separa producto y operacion para que el repo no se vuelva caotico
+
 ## Que referencia leer y cuando
 
-- lee `references/activation.md` solo para instalacion, primer uso, locale bootstrap y activacion de un repo
+- lee `references/activation.md` solo para instalacion, verificacion del runtime, locale bootstrap y activacion de un repo
 - lee `references/workflow.md` solo cuando TrackOps ya esta activo y haga falta operar el dia a dia del repositorio
-- lee `references/troubleshooting.md` solo cuando fallen la instalacion, el bootstrap, el resume o el contrato de entorno
+- lee `references/troubleshooting.md` solo cuando fallen la instalacion explicita, la deteccion de `trackops`, el resume o el contrato de entorno

package/skills/trackops/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "TrackOps"
-  short_description: "Bootstrap TrackOps and activate OPERA"
-  default_prompt: "Use $trackops to bootstrap the TrackOps runtime and activate OPERA in this repository."
+  short_description: "Explain TrackOps and guide explicit install"
+  default_prompt: "Use $trackops to explain what TrackOps does, require explicit npm installation of the TrackOps runtime, and then activate TrackOps and OPERA in this repository."
 
 policy:
   allow_implicit_invocation: true