create-harness-btp 0.1.1 → 0.2.1

package/README.md

@@ -1,13 +1,13 @@
 # harness-btp
 
-[![version](https://img.shields.io/badge/version-v0.1.0-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.1.0)
+[![version](https://img.shields.io/badge/version-v0.2.1-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.2.1)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![platform](https://img.shields.io/badge/platform-windows%20%7C%20linux-lightgrey)](https://github.com/horangelmillan/harness-btp)
-[![opencode](https://img.shields.io/badge/agent-OpenCode-purple)](https://opencode.ai)
+[![platform](https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macos-lightgrey)](https://github.com/horangelmillan/harness-btp)
+[![agent](https://img.shields.io/badge/agent-any%20AGENTS.md--compatible-purple)](https://github.com/horangelmillan/harness-btp)
 
-Reglas, agentes y scripts reutilizables para llevar un MVP SAP de la especificación al despliegue en Cloud Foundry con OpenCode.
+Reglas, agentes y scripts reutilizables para llevar un MVP SAP de la especificación al despliegue en Cloud Foundry, con cualquier cliente agéntico que lea `AGENTS.md`.
 
-Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empezar cada proyecto con el mismo flujo probado, sin copiar y pegar.
+Para quien construye MVPs SAP BTP y quiere empezar cada proyecto con el mismo flujo probado, sin copiar y pegar. Funciona en Windows, Linux y macOS, con OpenCode, Claude Code o cualquier otro cliente que lea `AGENTS.md` y ejecute scripts del proyecto.
 
 ## Contenidos
 
@@ -15,7 +15,9 @@ Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empeza
 - [Requisitos](#requisitos)
 - [Quickstart](#quickstart)
 - [Instalación](#instalación)
+- [Instalación asistida por agente](#instalación-asistida-por-agente)
 - [Actualizar y desinstalar](#actualizar-y-desinstalar)
+- [Adaptadores opcionales](#adaptadores-opcionales)
 - [Estructura del repo](#estructura-del-repo)
 - [Cómo lo descubre el agente](#cómo-lo-descubre-el-agente)
 - [Troubleshooting](#troubleshooting)
@@ -27,71 +29,101 @@ Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empeza
 ## Features
 
 - **Carpeta `AI/` sin envolver:** se instala dentro de tu proyecto (nuevo o existente) sin mover ni renombrar nada de lo que ya tienes.
-- **Idempotente con `SKIP` / `-Force` + backup:** repetir la instalación no pisa nada; solo reemplaza con `-Force` y guarda copia en `AI.bak`.
+- **Idempotente con `SKIP` / `-Force` + backup:** repetir la instalación no pisa nada; solo reemplaza con `-Force` (`.ps1`) o `--force` (`.sh`) y guarda copia en `AI.bak`.
 - **Sin secretos:** el repo no contiene credenciales, tokens ni rutas de máquina; solo nombres y placeholders por paisaje.
 - **Tres formas de instalar:** `degit`, `git clone` o `pnpm dlx`, todas ancladas a un tag versionado.
 - **Versionado por tags:** cada versión es un tag `vX.Y.Z`; actualizar es repetir el comando contra el tag nuevo.
-- **El agente se adapta solo:** deja un puntero `AGENTS.md` en la raíz y OpenCode encuentra `AI/AGENTS.md`, `INICIO.md`, agentes, skills y plantilla de spec.
+- **Instaladores pares:** `install.ps1` (PowerShell) e `install.sh` (bash/sh) con la misma lógica (`SKIP` / `CREATE` / `BACKUP` / `OK`). Elige el de tu shell.
+- **Agnóstico al cliente:** el núcleo es Markdown + shell (`AI/AGENTS.md`, `AI/INICIO.md`, `AI/docs/`, `AI/scripts/`). `AI/.opencode/` y `AI/opencode.fragment.jsonc` son adaptadores opcionales de ejemplo, no requisitos (ver [Adaptadores opcionales](#adaptadores-opcionales)).
+- **El agente se adapta solo:** deja un puntero `AGENTS.md` en la raíz y el cliente encuentra `AI/AGENTS.md`, `INICIO.md`, agentes, skills y plantilla de spec.
 
 ## Requisitos
 
 | Necesitas | Versión | Para qué |
 |---|---|---|
-| Windows PowerShell 5.1 / bash | incluido en el SO | ejecutar `install.ps1` / `install.sh` |
+| PowerShell 5.1+ o bash/sh | incluido en el SO | ejecutar `install.ps1` / `install.sh` |
 | Node.js 18+ | solo si usas `degit` o `pnpm dlx` | descargar e instalar el harness |
 | `gh` (opcional) | cualquiera reciente | clonar repo privado o crear PRs |
-| OpenCode | cualquiera reciente | leer `AGENTS.md` y orquestar el flujo |
+| Cliente agéntico | cualquiera reciente que lea `AGENTS.md` (OpenCode, Claude Code, etc.) | leer `AGENTS.md` y orquestar el flujo |
 
 > Sin Node también puedes instalar vía `git clone`, que no lo necesita.
 
 ## Quickstart
 
-El camino de 30 segundos en un proyecto nuevo (Windows, recomendado):
+El camino de 30 segundos en un proyecto nuevo. Elige tu shell:
+
+PowerShell (Windows):
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.1.0 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
-Eso es todo. Abre el proyecto en OpenCode y el agente ya sabe qué hacer: lee `AGENTS.md` → `AI/AGENTS.md` → `AI/INICIO.md`.
+bash (Linux, macOS o Git Bash):
 
-## Instalación
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
 
-> En Linux/macOS sustituye `install.ps1 -Dest .` por `install.sh --dest .` en todos los ejemplos.
+Eso es todo. Abre el proyecto en tu cliente agéntico y el agente ya sabe qué hacer: lee `AGENTS.md` → `AI/AGENTS.md` → `AI/INICIO.md`.
+
+## Instalación
 
 ### Opción 1 — degit (recomendado)
 
 Descarga solo lo necesario, sin historial git:
 
+PowerShell:
+
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.1.0 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
+bash:
+
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
+
 ### Opción 2 — git clone
 
 Clon superficial anclado al tag:
 
+PowerShell:
+
 ```powershell
-git clone --branch v0.1.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+git clone --branch v0.2.1 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
+bash:
+
+```bash
+git clone --branch v0.2.1 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
+
 ### Opción 3 — pnpm dlx
 
-Sin descargas manuales (requiere publicar `create-harness-btp` en el registry):
+Sin descargas manuales (requiere publicar `create-harness-btp` en el registry). Igual en todos los SO:
 
-```powershell
-pnpm dlx create-harness-btp --dest .
+```bash
+pnpm dlx create-harness-btp@0.2.1 --dest .
 ```
 
 ### Qué hace el instalador
 
-- `CREATE: AI/` o `SKIP: AI/ ya existe` (solo lo reemplaza con `-Force`, con backup a `AI.bak`).
-- `CREATE: AGENTS.md` o `SKIP: AGENTS.md ya existe` (tu `AGENTS.md` propio se conserva; con `-Force` se respalda a `AGENTS.md.bak`).
+- `CREATE: AI/` o `SKIP: AI/ ya existe` (solo lo reemplaza con `-Force` / `--force`, con backup a `AI.bak`).
+- `CREATE: AGENTS.md` o `SKIP: AGENTS.md ya existe` (tu `AGENTS.md` propio se conserva; con `-Force` / `--force` se respalda a `AGENTS.md.bak`).
 - Fusiona `.gitignore`: añade las líneas que falten, sin duplicar ni borrar las tuyas.
 - **No toca** `package.json` ni `mta.yaml` de tu proyecto, nunca.
 
@@ -100,29 +132,67 @@ Salida típica en proyecto nuevo:
 ```text
 CREATE: AI/
 CREATE: AGENTS.md
-OK: harness v0.1.0 instalado
+OK: harness v0.2.1 instalado
+```
+
+## Instalación asistida por agente
+
+Si prefieres que tu agente lo instale por ti, pégale este bloque:
+
+```text
+Pégale esto a tu agente: Instala el harness BTP versión 0.2.1 en la raíz del proyecto: 1) Lee el README del repo harness-btp (opción pnpm). 2) Ejecuta EXACTAMENTE pnpm dlx create-harness-btp@0.2.1 --dest . (sin --force salvo que AI/ ya exista y yo lo autorice; con --force verifica BACKUP primero). 3) PROHIBIDO pisar o borrar: AGENTS.md raíz existente, package.json, mta.yaml, lockfiles. 4) Verifica lo INSTALADO (no vale pnpm view): AI/VERSION debe decir 0.2.1. 5) Si migraste npm→pnpm con import+install+test en verde, borra package-lock.json. 6) Corre AI/scripts/check-prereqs y reporta faltantes. 7) Si hay placeholders por adaptar, dímelos antes de desplegar. Sin secretos en el reporte. Repórtame: comando, salida del instalador, contenido de AI/VERSION, git status y pendientes.
 ```
 
 ## Actualizar y desinstalar
 
-**Actualizar:** repite el mismo comando de instalación contra el tag nuevo. Sin `-Force` lo existente se conserva (`SKIP:`); con `-Force` se reemplaza con backup:
+**Actualizar:** repite el mismo comando de instalación contra el tag nuevo. Sin `-Force` / `--force` lo existente se conserva (`SKIP:`); con fuerza se reemplaza con backup:
+
+PowerShell:
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest . -Force
 Remove-Item -Recurse -Force AI-tmp
 # tu versión anterior queda en AI.bak por si quieres comparar
 ```
 
+bash:
+
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.1 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest . --force
+rm -rf AI-tmp
+# tu versión anterior queda en AI.bak por si quieres comparar
+```
+
 **Desinstalar:** borra la carpeta y el puntero. No deja servicios ni hooks:
 
+PowerShell:
+
 ```powershell
 Remove-Item -Recurse -Force AI
 Remove-Item -Force AGENTS.md  # solo si es el puntero al harness
 ```
 
+bash:
+
+```bash
+rm -rf AI
+rm -f AGENTS.md  # solo si es el puntero al harness
+```
+
 > Si tu `AGENTS.md` tenía contenido propio antes del harness, el instalador lo respaldó en `AGENTS.md.bak`: restáuralo en vez de borrarlo.
 
+## Adaptadores opcionales
+
+El harness funciona con **cualquier** cliente agéntico que lea `AGENTS.md`. Estos archivos son ayudas para un cliente concreto, no requisitos:
+
+- **`AI/.opencode/`** — agentes, comandos y skills de ejemplo con el layout de OpenCode. Si tu cliente usa otro layout, ignóralos o adaptalos: el flujo vive en `AI/AGENTS.md`, `AI/INICIO.md`, `AI/docs/` y `AI/scripts/`, que son Markdown + shell portátil.
+- **`AI/opencode.fragment.jsonc`** — fragmento de ejemplo para fusionar en tu `opencode.jsonc` (p. ej. el bloque MCP `graphify-code`, deshabilitado por defecto). Solo aplica a OpenCode; otros clientes lo ignoran sin efecto.
+- **`install.ps1` / `install.sh`** — elige el de tu shell; ambos aplican la misma lógica idempotente. Los scripts de `AI/scripts/` también vienen en par `.ps1` / `.sh`.
+
+Nada del núcleo exige OpenCode, Windows ni ningún modelo concreto.
+
 ## Estructura del repo
 
 ```text
@@ -130,9 +200,9 @@ harness-btp/
 ├── AI/                        # lo que queda instalado en tu proyecto
 │   ├── AGENTS.md              # reglas del harness (parametrizado, sin rutas absolutas)
 │   ├── INICIO.md              # punto de entrada para el agente
-│   ├── opencode.fragment.jsonc# fragmento relativo para tu opencode.jsonc
-│   ├── .opencode/             # 11 agents + 2 commands + 4 skills
-│   ├── scripts/               # 5 scripts .ps1 + provision-espacio.template.ps1
+│   ├── opencode.fragment.jsonc# ADAPTER opcional: ejemplo para opencode.jsonc
+│   ├── .opencode/             # ADAPTER opcional: agents + commands + skills de ejemplo
+│   ├── scripts/               # pares .ps1 / .sh + provision-espacio.template.ps1
 │   ├── docs/                  # flujo-etapas, cf-safe, habilitacion-trial
 │   ├── specs/                 # plantilla _template.md
 │   └── .gitignore.fragment    # líneas a fusionar en tu .gitignore
@@ -141,15 +211,15 @@ harness-btp/
 ├── install.ps1 / install.sh   # instaladores idempotentes (SKIP / CREATE / BACKUP / OK)
 ├── bin/                       # ejecutable de create-harness-btp (pnpm dlx)
 ├── package.json               # name create-harness-btp
-└── VERSION                    # 0.1.0
+└── VERSION                    # 0.2.1
 ```
 
 ## Cómo lo descubre el agente
 
-1. OpenCode abre tu proyecto y lee `AGENTS.md` en la raíz (el puntero que deja el instalador).
-2. El puntero lo lleva a `AI/AGENTS.md`: reglas, herramientas (`sap_cf`, `mbt`) y presupuestos.
-3. Desde ahí sigue a `AI/INICIO.md` para el flujo por etapas (`/flow`), descubre agentes en `.opencode/`, skills y scripts, y usa `AI/specs/_template.md` para nuevas especificaciones.
-4. Antes del primer despliegue adapta los dos placeholders a tu máquina y destino (ver `AI/INICIO.md`).
+1. Tu cliente agéntico abre el proyecto y lee `AGENTS.md` en la raíz (el puntero que deja el instalador).
+2. El puntero lo lleva a `AI/AGENTS.md`: reglas, herramientas (`cf`, `mbt`) y presupuestos.
+3. Desde ahí sigue a `AI/INICIO.md` para el flujo por etapas (`/flow`), descubre los agentes de ejemplo en `.opencode/`, skills y scripts, y usa `AI/specs/_template.md` para nuevas especificaciones.
+4. Antes del primer despliegue adapta los dos placeholders a tu destino (ver `AI/INICIO.md`).
 
 Tú no configuras nada: el agente se adapta solo.
 
@@ -157,24 +227,31 @@ Tú no configuras nada: el agente se adapta solo.
 
 | Problema | Causa | Comando |
 |---|---|---|
-| `SKIP: AI/ ya existe` y quería actualizar | reinstalación sin `-Force` conserva lo existente | repite con `-Force` (guarda `AI.bak`) |
-| Mi `AGENTS.md` propio desapareció | se instaló con `-Force` | recupera `AGENTS.md.bak` |
+| `SKIP: AI/ ya existe` y quería actualizar | reinstalación sin fuerza conserva lo existente | repite con `-Force` (`.ps1`) o `--force` (`.sh`); guarda `AI.bak` |
+| Mi `AGENTS.md` propio desapareció | se instaló con fuerza | recupera `AGENTS.md.bak` |
 | Líneas duplicadas en `.gitignore` | edición manual tras la fusión | el instalador fusiona sin duplicar; borra el duplicado a mano |
-| `ExecutionPolicy` bloquea `install.ps1` | política de PowerShell | `powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .` |
-| `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.1.0` |
+| `ExecutionPolicy` bloquea `install.ps1` | política de PowerShell | `powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .` (o usa `install.sh` en Git Bash) |
+| `ABORT: opción desconocida` en `install.sh` | flag inexistente | `sh install.sh --help` lista `--dest`, `--force` |
+| `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.2.1` |
+| Tu cliente no lee los agentes de `.opencode/` | layout específico de OpenCode | son un adapter opcional; el flujo está en `AI/AGENTS.md` + `AI/INICIO.md` |
 
 ## Compatibilidad
 
-- Windows 10/11 + PowerShell 5.1 verificado.
-- Linux/macOS vía `install.sh` (mismo comportamiento `SKIP` / `--force` + backup).
-- OpenCode como orquestador del flujo.
+Matriz honesta cliente × SO (`verificado` = probado con evidencia; `esperado` = sin bloqueo conocido, pendiente de evidencia):
+
+| Cliente agéntico | Windows | Linux | macOS |
+|---|---|---|---|
+| OpenCode | verificado | esperado (`install.sh` par verificado en Git Bash) | esperado |
+| Claude Code, otros que lean `AGENTS.md` | esperado | esperado | esperado |
+
+- Instaladores y `check-prereqs` / `check-docs` verificados en Windows (`.ps1` nativo, `.sh` vía Git Bash, paridad CREATE/SKIP/BACKUP/OK + mismos `exit`).
 - SAP BTP Cloud Foundry solo cuando el MVP lo pida: el harness no crea cuentas ni espacios por sí solo.
 
 ## Contribuir
 
 - Abre un issue antes que un PR si el cambio afecta reglas o scripts.
 - PRs pequeños, en español, con evidencia del comando corrido.
-- Versionado semver: los cambios se publican como tags `vX.Y.Z` (`VERSION` + `package.json` + tag git coinciden).
+- Versionado semver: los cambios se publican como tags `vX.Y.Z` (`package.json` + `VERSION` + `AI/VERSION` + tag git coinciden; el workflow lo verifica).
 
 ## Licencia
 
@@ -182,4 +259,5 @@ MIT. Haz lo que quieras con el harness; sin garantía.
 
 ## Changelog
 
-- **v0.1.0** — versión inicial: carpeta `AI/` parametrizada, instaladores idempotentes `install.ps1` / `install.sh`, `create-harness-btp` vía `pnpm dlx`, plantilla de puntero, docs de flujo / cf-safe / habilitación trial, plantilla de spec.
+- **v0.2.1** — trazabilidad y versión visible: `AI/VERSION` viaja en el paquete, los instaladores imprimen la versión (`OK: harness vX.Y.Z…`, `BACKUP` con vieja→nueva) y el workflow exige que `package.json`, `VERSION` y `AI/VERSION` coincidan. Comandos fijados a `@0.2.1` / `#v0.2.1` / `--branch v0.2.1`.
+- **v0.2.0** — versión inicial: carpeta `AI/` parametrizada, instaladores idempotentes `install.ps1` / `install.sh`, `create-harness-btp` vía `pnpm dlx`, plantilla de puntero, docs de flujo / cf-safe / habilitación trial, plantilla de spec.

package/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.1

package/bin/harness-btp.js

@@ -29,22 +29,28 @@ if (!fs.existsSync(path.join(src, "AI"))) {
   console.log("ABORT: no se encontró AI/ junto al paquete");
   process.exit(1);
 }
+function readVer(p) {
+  try {
+    return fs.readFileSync(p, "utf8").split(/\r?\n/)[0].trim() || "desconocida";
+  } catch { return "desconocida"; }
+}
+const harnessVersion = readVer(path.join(src, "AI", "VERSION"));
 
 const aiDst = path.join(dest, "AI");
 if (fs.existsSync(aiDst)) {
   if (force) {
+    const oldVersion = readVer(path.join(aiDst, "VERSION"));
     const bak = path.join(dest, "AI.bak");
     fs.rmSync(bak, { recursive: true, force: true });
     fs.renameSync(aiDst, bak);
-    console.log("BACKUP: AI/ -> AI.bak");
     fs.cpSync(path.join(src, "AI"), aiDst, { recursive: true });
-    console.log("CREATE: AI/ (reinstalado con --force)");
+    console.log("BACKUP: AI/ (v" + oldVersion + ") -> AI.bak; CREATE: AI/ (v" + harnessVersion + ")");
   } else {
     console.log("SKIP: AI/ ya existe (usa --force para reinstalar con backup .bak)");
   }
 } else {
   fs.cpSync(path.join(src, "AI"), aiDst, { recursive: true });
-  console.log("CREATE: AI/");
+  console.log("CREATE: AI/ (v" + harnessVersion + ")");
 }
 
 const agentsDst = path.join(dest, "AGENTS.md");
@@ -67,4 +73,4 @@ if (missing.length === 0) {
   fs.appendFileSync(giDst, (cur.length ? "" : "") + missing.join("\n") + "\n");
   console.log("CREATE: .gitignore (+" + missing.length + " líneas)");
 }
-console.log("OK: harness instalado en " + dest + " (package.json y mta.yaml intactos)");
+console.log("OK: harness v" + harnessVersion + " instalado en " + dest + " (package.json y mta.yaml intactos)");

package/install.ps1

@@ -16,21 +16,29 @@ $TplPointer = Join-Path $Src "templates\AGENTS.pointer.md"
 
 if (-not (Test-Path $AiSrc)) { Write-Output "ABORT: no se encontró AI/ junto a install.ps1"; exit 1 }
 
+$HarnessVersion = "desconocida"
+$VersionFile = Join-Path $AiSrc "VERSION"
+if (Test-Path $VersionFile) { $HarnessVersion = ((Get-Content $VersionFile | Select-Object -First 1) + "").Trim() }
+if (-not $HarnessVersion) { $HarnessVersion = "desconocida" }
+
 $AiDst = Join-Path $Dest "AI"
 if (Test-Path $AiDst) {
   if ($Force) {
+    $OldVersion = "desconocida"
+    $DstVersionFile = Join-Path $AiDst "VERSION"
+    if (Test-Path $DstVersionFile) { $OldVersion = ((Get-Content $DstVersionFile | Select-Object -First 1) + "").Trim() }
+    if (-not $OldVersion) { $OldVersion = "desconocida" }
     $Bak = Join-Path $Dest "AI.bak"
     if (Test-Path $Bak) { Remove-Item $Bak -Recurse -Force }
     Rename-Item $AiDst "AI.bak"
-    Write-Output "BACKUP: AI/ -> AI.bak"
     Copy-Item $AiSrc $AiDst -Recurse -Force
-    Write-Output "CREATE: AI/ (reinstalado con -Force)"
+    Write-Output "BACKUP: AI/ (v$OldVersion) -> AI.bak; CREATE: AI/ (v$HarnessVersion)"
   } else {
     Write-Output "SKIP: AI/ ya existe (usa -Force para reinstalar con backup .bak)"
   }
 } else {
   Copy-Item $AiSrc $AiDst -Recurse -Force
-  Write-Output "CREATE: AI/"
+  Write-Output "CREATE: AI/ (v$HarnessVersion)"
 }
 
 $AgentsDst = Join-Path $Dest "AGENTS.md"
@@ -57,4 +65,10 @@ if (Test-Path $GiDst) {
   Write-Output "CREATE: .gitignore"
 }
 
-Write-Output "OK: harness instalado en $Dest (package.json y mta.yaml intactos)"
+Write-Output "OK: harness v$HarnessVersion instalado en $Dest (package.json y mta.yaml intactos)"
+
+# Verificación de prerrequisitos en modo aviso (no bloquea la instalación).
+try {
+  $Check = Join-Path $AiSrc "scripts\check-prereqs.ps1"
+  if (Test-Path $Check) { & $Check -WarnOnly }
+} catch { Write-Output "AVISO: no se pudo ejecutar check-prereqs.ps1 (ver AI/docs/prerequisitos.md)" }

package/install.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Instalador del harness BTP (idempotente, POSIX sh).
-# Uso: ./install.sh [--dest .] [--force]
+# Uso: ./install.sh [--dest <dir>] [--force] [--help]
 # Sin secretos. No toca package.json ni mta.yaml del proyecto.
 DEST="."
 FORCE=0
@@ -8,22 +8,33 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --dest) DEST="$2"; shift 2 ;;
     --force) FORCE=1; shift ;;
-    *) echo "ABORT: opción desconocida $1"; exit 1 ;;
+    -h|--help)
+      echo "Uso: ./install.sh [--dest <dir>] [--force] [--help]"
+      echo "  --dest <dir>  proyecto destino (por defecto: .)"
+      echo "  --force       reinstala AI/ con backup a AI.bak"
+      echo "  -h, --help    muestra esta ayuda"
+      exit 0 ;;
+    *) echo "ABORT: opción desconocida $1 (usa --help)"; exit 1 ;;
   esac
 done
 SRC="$(cd "$(dirname "$0")" && pwd)"
 if [ ! -d "$SRC/AI" ]; then echo "ABORT: no se encontró AI/ junto a install.sh"; exit 1; fi
+HARNESS_VERSION="desconocida"
+if [ -f "$SRC/AI/VERSION" ]; then HARNESS_VERSION="$(tr -d '[:space:]' < "$SRC/AI/VERSION")"; fi
+[ -n "$HARNESS_VERSION" ] || HARNESS_VERSION="desconocida"
 
 if [ -d "$DEST/AI" ]; then
   if [ "$FORCE" -eq 1 ]; then
+    OLD_VERSION="desconocida"
+    if [ -f "$DEST/AI/VERSION" ]; then OLD_VERSION="$(tr -d '[:space:]' < "$DEST/AI/VERSION")"; fi
+    [ -n "$OLD_VERSION" ] || OLD_VERSION="desconocida"
     rm -rf "$DEST/AI.bak" && mv "$DEST/AI" "$DEST/AI.bak"
-    echo "BACKUP: AI/ -> AI.bak"
-    cp -r "$SRC/AI" "$DEST/AI" && echo "CREATE: AI/ (reinstalado con --force)"
+    cp -r "$SRC/AI" "$DEST/AI" && echo "BACKUP: AI/ (v$OLD_VERSION) -> AI.bak; CREATE: AI/ (v$HARNESS_VERSION)"
   else
     echo "SKIP: AI/ ya existe (usa --force para reinstalar con backup .bak)"
   fi
 else
-  cp -r "$SRC/AI" "$DEST/AI" && echo "CREATE: AI/"
+  cp -r "$SRC/AI" "$DEST/AI" && echo "CREATE: AI/ (v$HARNESS_VERSION)"
 fi
 
 if [ -f "$DEST/AGENTS.md" ]; then
@@ -45,4 +56,11 @@ done < "$FRAG"
 if [ "$ADDED" -eq 0 ]; then echo "SKIP: .gitignore ya contiene el fragmento"
 else echo "CREATE: .gitignore (+$ADDED líneas)"; fi
 
-echo "OK: harness instalado en $DEST (package.json y mta.yaml intactos)"
+echo "OK: harness v$HARNESS_VERSION instalado en $DEST (package.json y mta.yaml intactos)"
+
+# Verificación de prerrequisitos en modo aviso (no bloquea la instalación).
+if [ -f "$SRC/AI/scripts/check-prereqs.sh" ]; then
+  sh "$SRC/AI/scripts/check-prereqs.sh" --warn-only || true
+else
+  echo "AVISO: no se encontró check-prereqs.sh (ver AI/docs/prerequisitos.md)"
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-btp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Instala el harness MVP SAP BTP como carpeta AI/ en cualquier proyecto",
   "keywords": ["sap-btp", "opencode", "harness", "agents", "scaffolder", "create"],
   "homepage": "https://github.com/horangelmillan/harness-btp#readme",

package/AI/.opencode/skills/sap-cf-cli/SKILL.md

@@ -1,41 +0,0 @@
----
-name: sap-cf-cli
-description: Uso seguro del CLI de Cloud Foundry como sap_cf en Windows
----
-
-# CLI Cloud Foundry (`sap_cf`)
-
-En [TU_PC] `cf` es el CLI de **Cloudflare**. Cloud Foundry se invoca
-**siempre** como `sap_cf` (`sap_cf.cmd`, ruta de instalación de
-Cloud Foundry CLI en [TU_PC]; verificado en Windows, adapta rutas).
-
-## Lectura segura (sin secretos)
-
-```
-sap_cf target          # endpoint / org / espacio actuales
-sap_cf api             # endpoint y versión API
-sap_cf orgs            # solo nombres
-sap_cf spaces          # solo nombres
-sap_cf apps            # estado observable (started/stopped, rutas)
-sap_cf services        # instancias visibles
-sap_cf logs <app> --recent
-```
-
-`target`, `api`, `orgs`, `spaces` y `app <nombre>` nunca muestran tokens.
-Si una salida incluyera un secreto, redáctalo antes de citarla.
-
-## Mutaciones (solo `deploy-cf`, con destino confirmado)
-
-- Confirmar endpoint/org/espacio contra la spec **antes** de cada despliegue.
-- `sap_cf push` para apps simples; `sap_cf deploy <archivo>.mtar` para MTA
-  (requiere plugin `multiapps`, no instalado: ver skill `mta-build`).
-- Verificar después: `sap_cf apps` + `sap_cf logs <app> --recent` + URL.
-
-## Denylist
-
-- `cf ...` para cualquier operación Foundry.
-- Borrar o renombrar orgs, espacios, apps o servicios fuera del MVP.
-- `sap_cf login`/re-autenticaciones no solicitadas (si la sesión caduca,
-  pedir al usuario el flujo interactivo, nunca credenciales en texto).
-- `--var`/`--vars-file` con secretos en shell compartida; usar archivos ya
-  ignorados por Git y no citar sus valores.