create-harness-btp 0.2.5 → 0.3.1

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

@@ -0,0 +1,41 @@
+---
+name: cf-cli
+description: Uso estándar del CLI de Cloud Foundry (cf)
+---
+
+# CLI Cloud Foundry (`cf`)
+
+El CLI de Cloud Foundry se invoca **siempre** como `cf` (instalación
+estándar del CLI; adapta rutas según tu equipo). Si `cf` en tu máquina
+corresponde a otra herramienta, define un alias propio y úsalo de forma
+consistente donde el harness diga `cf`.
+
+## Lectura segura (sin secretos)
+
+```
+cf target          # endpoint / org / espacio actuales
+cf api             # endpoint y versión API
+cf orgs            # solo nombres
+cf spaces          # solo nombres
+cf apps            # estado observable (started/stopped, rutas)
+cf services        # instancias visibles
+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.
+- `cf push` para apps simples; `cf deploy <archivo>.mtar` para MTA
+  (requiere plugin `multiapps`, no instalado: ver skill `mta-build`).
+- Verificar después: `cf apps` + `cf logs <app> --recent` + URL.
+
+## Denylist
+
+- Borrar o renombrar orgs, espacios, apps o servicios fuera del MVP.
+- `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.

package/AI/clients/opencode/skills/mta-build/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mta-build
+description: Construir y verificar artefactos MTAR con mbt en este equipo
+---
+
+# Build MTA (`mbt`)
+
+`mbt` es Cloud MTA Build Tool 1.2.50 (verificado 2026-10-29). Invocarlo
+siempre como `mbt`, nunca como `cf` ni rutas inventadas.
+
+## Flujo
+
+```
+mbt build                # requiere mta.yaml en la raíz del proyecto
+```
+
+- El `.mtar` resultante queda en `mta_archives/` con el nombre/versión de
+  `mta.yaml`. Comprobar existencia y fecha antes de desplegar.
+- Para módulos Node.js, `mbt` ejecuta `npm install`/`npm run build` según
+  `mta.yaml`; para Java necesita Maven (`mvn` no instalado: documentar como
+  pendiente si una spec lo exige).
+- `mbt build --help` para flags (`--mtar`, `--platform=cf`).
+
+## Despliegue del MTAR
+
+`cf deploy <archivo>.mtar` requiere el **plugin multiapps**. Verificar
+siempre con `cf plugins` antes de asumir su ausencia (2026-10-30 resultó
+ya instalado contra lo documentado). Instalarlo solo cuando un MVP necesite
+despliegue MTA:
+
+```
+cf install-plugin -r CF-Community multiapps
+```
+
+Alternativa sin plugin para MVPs simples: `cf push` por app según plan.
+
+## Notas
+
+- El binario `mbt.exe` se obtuvo con el propio `install.js` del paquete npm
+  (`node install.js cloud-mta-build-tool`). Si `mbt` vuelve a fallar tras
+  una actualización global, repetir ese comando en el directorio del paquete.
+- Nunca versionar `mta_archives/*.mtar` ni `default-services.json` con claves.
+- `mbt` exige `make` en `%PATH%` (ver `AGENTS.md` § Disciplina de shell y
+  CLIs): si falla `exec: "make": executable file not found`, anteponer el
+  `bin` de ezwinports/GnuWin32 al `$env:PATH` solo para el comando.

package/AI/clients/opencode/skills/sap-verify/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: sap-verify
+description: Clasificar disponibilidad, cuenta y coste de servicios SAP/BTP
+---
+
+# Verificación de dependencias externas SAP
+
+Toda afirmación sobre un servicio, plan, API o capacidad BTP se clasifica en
+una de estas categorías, con fuente y fecha:
+
+| Categoría | Significado |
+|---|---|
+| **Documentado** | Docs oficiales vigentes + evidencia (comando, consola o enlace con fecha). |
+| **Pendiente en cuenta** | Existe en docs pero sin comprobar en la subcuenta/destino real. |
+| **Coste por cotizar** | Requiere plan de pago o métrica no verificada; no activar sin confirmación. |
+
+## Reglas
+
+- Desarrollo local y mocks primero; servicios reales solo con evidencia.
+- Distinguir Windows local frente a BAS/dev space remoto: una instalación o
+  capacidad de un lado no implica la del otro.
+- No afirmar que una integración está aprobada o disponible hasta comprobarla
+  con documentación y accesos vigentes.
+- Costes: antes de activar cualquier recurso con coste, verificar precio y
+  documentarlo en la spec; capa gratuita por defecto.
+- Bloqueos externos no paran el MVP: documentar evidencia y continuar con
+  mocks o adaptador local.

package/AI/commands/flow.md

@@ -0,0 +1,16 @@
+---
+description: Ciclo completo spec-despliegue de un MVP SAP BTP
+agent: orchestrator
+---
+
+Ejecuta el flujo sobre la especificación: $ARGUMENTS
+(p. ej. `/flow specs/mi-mvp.md`).
+
+El orquestador recorre las etapas 0–10 de `AGENTS.md` con los especialistas
+adecuados (`analyst`, `researcher`, `architect`, `frontend-ui5`,
+`backend-cap`, `qa-review`, `deploy-cf`, `documentarian`). En MVPs pequeños
+puede saltar etapas irrelevantes y registrarlo; ningún riesgo o
+incertidumbre bloquea por sí solo: se investiga, se decide con evidencia y
+se continúa con lo resoluble. La puerta de despliegue (etapa 7) es
+obligatoria antes de desplegar. Al cerrar: qué se hizo, verificaciones con
+comandos y resultado real, y qué quedó pendiente y por qué.

package/AI/commands/verify.md

@@ -0,0 +1,18 @@
+---
+description: Puerta de despliegue CF sin desplegar
+agent: orchestrator
+---
+
+Ejecuta solo la puerta de despliegue (etapa 7) para $ARGUMENTS
+(spec o nombre de app; si se omite, el MVP en curso).
+
+Verificaciones (delegables en `qa-review` + `deploy-cf` en solo lectura):
+
+1. `cf target` coincide con el destino de la spec (endpoint/org/espacio).
+2. El artefacto existe y es reciente (`.mtar` en `mta_archives/` o bundle
+   para `push`).
+3. Todos los criterios de aceptación están en verde con evidencia.
+4. Diff/Git sin secretos ni archivos que debieran estar ignorados.
+
+Veredicto: apto / no apto con motivos concretos. Este comando nunca
+despliega ni muta nada en Cloud Foundry.

package/AI/skills/cap-cli/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: cap-cli
+description: Invocación verificada del CLI de CAP y facets en este equipo
+---
+
+# CLI de CAP (`cds`)
+
+Nombres verificados el 2026-10-29 (docs cap.cloud.sap vía `context7`;
+paquete `@cap-js/cds-dk` **no existe** — el correcto es `@sap/cds-dk`):
+
+- CLI solo vía `npx -p @sap/cds-dk cds ...` (el `node_modules` del proyecto
+  no incluye el ejecutable `cds`; `npx cds` a secas falla).
+- Runtime del proyecto: `@sap/cds` v10 + `@cap-js/sqlite` v3 (SQLite solo
+  para dev local; sin persistencia en CF).
+- Scaffold: `npx -p @sap/cds-dk cds init <nombre> --nodejs` (no global).
+- Facets usadas en este harness: `mta xsuaa approuter html5-repo
+  destination ui5` (lista completa real con `cds add --help`, no de memoria).
+- Tras `cds add`, siempre `npm install` antes del siguiente comando.
+- `cds add` es aditivo y genera `mta.yaml`/`xs-security.json`: revisar el
+  diff antes de aceptar lo generado (nombres de instancia deben coincidir
+  con las existentes en la subcuenta).

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

@@ -0,0 +1,41 @@
+---
+name: cf-cli
+description: Uso estándar del CLI de Cloud Foundry (cf)
+---
+
+# CLI Cloud Foundry (`cf`)
+
+El CLI de Cloud Foundry se invoca **siempre** como `cf` (instalación
+estándar del CLI; adapta rutas según tu equipo). Si `cf` en tu máquina
+corresponde a otra herramienta, define un alias propio y úsalo de forma
+consistente donde el harness diga `cf`.
+
+## Lectura segura (sin secretos)
+
+```
+cf target          # endpoint / org / espacio actuales
+cf api             # endpoint y versión API
+cf orgs            # solo nombres
+cf spaces          # solo nombres
+cf apps            # estado observable (started/stopped, rutas)
+cf services        # instancias visibles
+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.
+- `cf push` para apps simples; `cf deploy <archivo>.mtar` para MTA
+  (requiere plugin `multiapps`, no instalado: ver skill `mta-build`).
+- Verificar después: `cf apps` + `cf logs <app> --recent` + URL.
+
+## Denylist
+
+- Borrar o renombrar orgs, espacios, apps o servicios fuera del MVP.
+- `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.

package/AI/skills/mta-build/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mta-build
+description: Construir y verificar artefactos MTAR con mbt en este equipo
+---
+
+# Build MTA (`mbt`)
+
+`mbt` es Cloud MTA Build Tool 1.2.50 (verificado 2026-10-29). Invocarlo
+siempre como `mbt`, nunca como `cf` ni rutas inventadas.
+
+## Flujo
+
+```
+mbt build                # requiere mta.yaml en la raíz del proyecto
+```
+
+- El `.mtar` resultante queda en `mta_archives/` con el nombre/versión de
+  `mta.yaml`. Comprobar existencia y fecha antes de desplegar.
+- Para módulos Node.js, `mbt` ejecuta `npm install`/`npm run build` según
+  `mta.yaml`; para Java necesita Maven (`mvn` no instalado: documentar como
+  pendiente si una spec lo exige).
+- `mbt build --help` para flags (`--mtar`, `--platform=cf`).
+
+## Despliegue del MTAR
+
+`cf deploy <archivo>.mtar` requiere el **plugin multiapps**. Verificar
+siempre con `cf plugins` antes de asumir su ausencia (2026-10-30 resultó
+ya instalado contra lo documentado). Instalarlo solo cuando un MVP necesite
+despliegue MTA:
+
+```
+cf install-plugin -r CF-Community multiapps
+```
+
+Alternativa sin plugin para MVPs simples: `cf push` por app según plan.
+
+## Notas
+
+- El binario `mbt.exe` se obtuvo con el propio `install.js` del paquete npm
+  (`node install.js cloud-mta-build-tool`). Si `mbt` vuelve a fallar tras
+  una actualización global, repetir ese comando en el directorio del paquete.
+- Nunca versionar `mta_archives/*.mtar` ni `default-services.json` con claves.
+- `mbt` exige `make` en `%PATH%` (ver `AGENTS.md` § Disciplina de shell y
+  CLIs): si falla `exec: "make": executable file not found`, anteponer el
+  `bin` de ezwinports/GnuWin32 al `$env:PATH` solo para el comando.

package/AI/skills/sap-verify/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: sap-verify
+description: Clasificar disponibilidad, cuenta y coste de servicios SAP/BTP
+---
+
+# Verificación de dependencias externas SAP
+
+Toda afirmación sobre un servicio, plan, API o capacidad BTP se clasifica en
+una de estas categorías, con fuente y fecha:
+
+| Categoría | Significado |
+|---|---|
+| **Documentado** | Docs oficiales vigentes + evidencia (comando, consola o enlace con fecha). |
+| **Pendiente en cuenta** | Existe en docs pero sin comprobar en la subcuenta/destino real. |
+| **Coste por cotizar** | Requiere plan de pago o métrica no verificada; no activar sin confirmación. |
+
+## Reglas
+
+- Desarrollo local y mocks primero; servicios reales solo con evidencia.
+- Distinguir Windows local frente a BAS/dev space remoto: una instalación o
+  capacidad de un lado no implica la del otro.
+- No afirmar que una integración está aprobada o disponible hasta comprobarla
+  con documentación y accesos vigentes.
+- Costes: antes de activar cualquier recurso con coste, verificar precio y
+  documentarlo en la spec; capa gratuita por defecto.
+- Bloqueos externos no paran el MVP: documentar evidencia y continuar con
+  mocks o adaptador local.

package/README.md

@@ -1,6 +1,6 @@
 # harness-btp
 
-[![version](https://img.shields.io/badge/version-v0.2.5-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.2.5)
+[![version](https://img.shields.io/badge/version-v0.3.1-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.3.1)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![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)
@@ -16,8 +16,10 @@ Para quien construye MVPs SAP BTP y quiere empezar cada proyecto con el mismo fl
 - [Quickstart](#quickstart)
 - [Instalación](#instalación)
 - [Instalación asistida por agente](#instalación-asistida-por-agente)
+- [Manual de uso](#manual-de-uso)
 - [Actualizar y desinstalar](#actualizar-y-desinstalar)
 - [Adaptadores opcionales](#adaptadores-opcionales)
+- [Multi-cliente](#multi-cliente)
 - [Estructura del repo](#estructura-del-repo)
 - [Cómo lo descubre el agente](#cómo-lo-descubre-el-agente)
 - [Troubleshooting](#troubleshooting)
@@ -55,7 +57,7 @@ El camino de 30 segundos en un proyecto nuevo. Elige tu shell:
 PowerShell (Windows):
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
@@ -63,7 +65,7 @@ Remove-Item -Recurse -Force AI-tmp
 bash (Linux, macOS o Git Bash):
 
 ```bash
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
 sh AI-tmp/install.sh --dest .
 rm -rf AI-tmp
 ```
@@ -79,7 +81,7 @@ Descarga solo lo necesario, sin historial git:
 PowerShell:
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
@@ -87,7 +89,7 @@ Remove-Item -Recurse -Force AI-tmp
 bash:
 
 ```bash
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
 sh AI-tmp/install.sh --dest .
 rm -rf AI-tmp
 ```
@@ -99,7 +101,7 @@ Clon superficial anclado al tag:
 PowerShell:
 
 ```powershell
-git clone --branch v0.2.5 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+git clone --branch v0.3.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
 ```
@@ -107,7 +109,7 @@ Remove-Item -Recurse -Force AI-tmp
 bash:
 
 ```bash
-git clone --branch v0.2.5 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+git clone --branch v0.3.1 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
 sh AI-tmp/install.sh --dest .
 rm -rf AI-tmp
 ```
@@ -117,24 +119,25 @@ rm -rf AI-tmp
 Sin descargas manuales (requiere publicar `create-harness-btp` en el registry). Igual en todos los SO:
 
 ```bash
-pnpm dlx create-harness-btp@0.2.5 --dest .
+pnpm dlx create-harness-btp@0.3.1 --dest .
 ```
 
 ### Qué hace el instalador
 
 - `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 `.opencode/` raíz desde `AI/.opencode/` (`agents` + `commands` + `skills`, lo que OpenCode descubre en la raíz del proyecto): sin fuerza solo copia los archivos que falten (`SKIP: .opencode/<ruta> ya existe` por cada uno conservado y `CREATE: .opencode/ (+N archivos)`); con `-Force` / `--force` respalda `.opencode/` a `.opencode.bak` (`BACKUP: .opencode/ -> .opencode.bak`) y copia todo.
+- Fusiona el árbol del cliente agéntico (`--client`, por defecto `auto`) desde `AI/clients/<cliente>/` en la raíz (ver [Multi-cliente](#multi-cliente)): sin fuerza solo copia los archivos que falten (`SKIP: <dir>/<ruta> ya existe` por cada uno conservado); con `-Force` / `--force` respalda cada dir a `<dir>.bak` (`BACKUP: <dir>/ -> <dir>.bak`) y copia todo.
 - 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.
 
 Salida típica en proyecto nuevo:
 
 ```text
-CREATE: AI/
+CREATE: AI/ (v0.3.1)
 CREATE: AGENTS.md
+CLIENT: auto -> opencode
 CREATE: .opencode/ (+17 archivos)
-OK: harness v0.2.5 instalado
+OK: harness v0.3.1 instalado
 ```
 
 ## Instalación asistida por agente
@@ -147,6 +150,36 @@ Déjame este proyecto listo con el harness BTP: lee https://raw.githubuserconten
 
 Vale para proyecto nuevo (con URL), existente, Windows/Linux/macOS y cualquier cliente que lea este README. El archivo `prompts/setup.md` vive versionado con el harness: siempre está al día sin que cambies tu línea.
 
+## Manual de uso
+
+El recorrido normal de un proyecto, en orden. Cada paso dice **qué hace, con qué comando y cuándo toca**.
+
+**1. Instalar (una sola vez por proyecto).** Copia la carpeta `AI/` dentro de tu proyecto con `pnpm dlx`, `degit` o `git clone` (ver [Instalación](#instalación)). No mueve ni renombra nada tuyo; si `AI/` ya existe, avisa en vez de pisar.
+
+**2. Comprobar que tu agente lo adoptó.** Abre el proyecto en tu cliente y verifica: el **orquestador** aparece entre sus agentes, existe el comando **`/flow`** y responde si le pides usar una **skill** (p. ej. que te muestre el `target` actual). Si algo de esto falta, mira [Troubleshooting](#troubleshooting) antes de seguir.
+
+**3. Contar lo que quieres (la spec).** Copia `AI/specs/_template.md` a `AI/specs/<tu-proyecto>.md` y rellénala: qué debe hacer, dónde vive en SAP y cómo se comprueba que funciona. Sin esto escrito no hay despliegue — el agente lo exige.
+
+**4. Ponerlo a trabajar: `/flow`.** Escribe `/flow AI/specs/<tu-proyecto>.md` y el orquestador recorre las etapas (revisar tu spec, investigar la doc oficial, planear, construir, probar, corregir). Te pregunta cuando le falta un dato y al cerrar te cuenta qué hizo, con qué comandos lo verificó y qué quedó pendiente.
+
+**5. Revisar antes de publicar: `/verify`.** Es la puerta de despliegue: comprueba destino, artefacto construido, pruebas en verde y Git limpio **sin desplegar nada**. Solo un veredicto "apto" permite pasar al despliegue.
+
+**6. Desplegar (solo con tu orden).** El despliegue lo ejecuta un único agente especialista y deja evidencia (apps en marcha, registros, URL). Primer despliegue a un destino nuevo siempre pide tu confirmación del destino.
+
+**7. Guardar y contar.** Los cambios se guardan en commits locales; nada sale a remoto sin que lo pidas expresamente. La spec y los informes quedan al día al cerrar.
+
+| Comando o guion | Para qué sirve (en una línea) | Cuándo usarlo |
+|---|---|---|
+| `pnpm dlx create-harness-btp …` / `degit` / `git clone` | traer el harness al proyecto | una vez por proyecto; repite contra otro tag para actualizar |
+| `install.ps1` / `install.sh` | copiar `AI/`, crear el puntero y fusionar `.gitignore` sin romper nada | lo corre el paquete solo; úsalo directo si instalaste por `degit`/`clone` |
+| `/flow <spec>` | ejecutar el ciclo completo sobre tu spec | cada vez que construyas o cambies el MVP |
+| `/verify` | revisar que todo está listo sin desplegar | antes de cada despliegue, siempre |
+| `AI/scripts/check-prereqs.*` | decirte qué herramientas te faltan y dónde instalarlas | al estrenar máquina o si algo falla por entorno |
+| `AI/scripts/check-docs.*` | comprobar que los enlaces a documentación oficial siguen vivos | si sospechas docs viejas, o antes de un MVP delicado |
+| `AI/scripts/cf-safe.*` | leer Cloud Foundry tapando secretos | no lo llamas tú: lo usan los agentes por dentro |
+
+**Cómo saber que todo va bien:** el instalador termina en `OK:`, `AI/VERSION` dice la versión que instalaste, tu agente muestra al orquestador y `/flow` existe, y `/verify` explica cada veredicto con motivos. Si algo de esto no cuadra, no sigas: está en [Troubleshooting](#troubleshooting).
+
 ## Actualizar y desinstalar
 
 **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:
@@ -154,7 +187,7 @@ Vale para proyecto nuevo (con URL), existente, Windows/Linux/macOS y cualquier c
 PowerShell:
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.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
@@ -163,7 +196,7 @@ Remove-Item -Recurse -Force AI-tmp
 bash:
 
 ```bash
-npx -p degit degit horangelmillan/harness-btp#v0.2.5 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.3.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
@@ -194,9 +227,32 @@ El harness funciona con **cualquier** cliente agéntico que lea `AGENTS.md`. Est
 - **`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`.
+- **Multi-cliente:** desde v0.3.0 la fuente única es `AI/agents/`, `AI/commands/`, `AI/skills/` y cada cliente recibe su árbol renderizado en `AI/clients/<cliente>/` (ver [Multi-cliente](#multi-cliente)). `AI/.opencode/` se conserva intacto por compatibilidad.
 
 Nada del núcleo exige OpenCode, Windows ni ningún modelo concreto.
 
+## Multi-cliente
+
+El harness se configura para el cliente agéntico de turno desde UNA sola definición canónica:
+
+- **Canónico (`AI/`):** `AI/agents/*.md` (11 agentes), `AI/commands/*.md` (`flow`, `verify`), `AI/skills/*/SKILL.md` (4 skills). Es la única fuente que se edita a mano.
+- **Render (`AI/clients/`):** generado con `node scripts/render-clients.js` (sin dependencias); `node scripts/render-clients.js --check` solo verifica. El CI lo exige en verde antes de publicar (ver `.github/workflows/publish.yml`). No edites `AI/clients/` a mano: tus cambios se pierden en el próximo render.
+
+| Cliente | `--client` | Rutas generadas en la raíz | Adaptación |
+|---|---|---|---|
+| OpenCode | `opencode` | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/` | copia exacta de `AI/.opencode/` |
+| Claude Code | `claude` | `.claude/agents/`, `.claude/commands/`, `.claude/skills/` | agents con `{name,description}` (sin `mode`) |
+| Cursor | `cursor` | `.cursor/commands/`, `.agents/skills/` | commands sin frontmatter (solo cuerpo) |
+| Copilot | `copilot` | `.github/agents/*.agent.md`, `.github/prompts/*.prompt.md`, `.github/skills/` | renombrados a su convención |
+| Aider (y genéricos) | `aider` | nada que generar | usan el `AGENTS.md` raíz |
+
+Flag `--client` en `install.ps1` (`-Client`), `install.sh` y `bin/harness-btp.js`:
+
+- `auto` (defecto): detecta por huellas (`CLAUDE.md`/`.claude`→claude, `.cursor`→cursor, `.github`→copilot, `opencode.json*`/`.opencode`→opencode); sin huellas usa opencode por compatibilidad histórica. Si hay huellas de varios clientes, fusiona los detectados.
+- `all`: fusiona los cuatro árboles.
+- Lista explícita (`-Client claude,cursor` / `--client claude,cursor`): solo esos.
+- Fusión idempotente con mensajes `CREATE:`/`SKIP:` por archivo y `BACKUP` a `<dir>.bak` con fuerza (mismo patrón que `AI/`).
+
 ## Estructura del repo
 
 ```text
@@ -204,18 +260,24 @@ 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
+│   ├── agents/                # CANÓNICO: 11 agentes (única fuente, se edita a mano)
+│   ├── commands/              # CANÓNICO: flow + verify (única fuente)
+│   ├── skills/                # CANÓNICO: 4 skills (única fuente)
+│   ├── clients/               # RENDERIZADO por scripts/render-clients.js (no editar a mano)
 │   ├── opencode.fragment.jsonc# ADAPTER opcional: ejemplo para opencode.jsonc
-│   ├── .opencode/             # ADAPTER opcional: agents + commands + skills de ejemplo
+│   ├── .opencode/             # ADAPTER opcional: se conserva intacto (compatibilidad)
 │   ├── 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
+├── scripts/
+│   └── render-clients.js      # genera AI/clients/ desde el canónico (--check en CI)
 ├── templates/
 │   └── AGENTS.pointer.md      # plantilla del puntero AGENTS.md raíz
 ├── 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.2.5
+└── VERSION                    # 0.3.1
 ```
 
 ## Cómo lo descubre el agente
@@ -237,8 +299,9 @@ Tú no configuras nada: el agente se adapta solo.
 | 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 .` (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.5` |
+| `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.3.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` |
+| Mi cliente no ve los agentes (claude/cursor/copilot) | instalaste sin el `--client` que usa tu proyecto (`auto` no encontró sus huellas) | reinstala sin fuerza con `--client <tu-cliente>` (p. ej. `--client claude`) y verifica la tabla de [Multi-cliente](#multi-cliente): `.claude/`, `.cursor/commands/` + `.agents/skills/`, o `.github/agents\|prompts\|skills` según cliente; si sigue sin verlos, revisa la fusión y no dupliques archivos a mano |
 | No se deja borrar la carpeta del proyecto ("Carpeta en uso") | procesos huérfanos parados dentro (shells/MCPs de una sesión ya cerrada) | resmon → CPU → Identificadores asociados → busca la carpeta y termina solo esos PIDs; nunca fueron del instalador (solo copia archivos y termina) |
 
 ## Compatibilidad
@@ -265,9 +328,12 @@ MIT. Haz lo que quieras con el harness; sin garantía.
 
 ## Changelog
 
+- **v0.3.1** — manual de uso: recorrido 1–7, tabla comando→para qué→cuándo, y señales de que todo va bien, en lenguaje normal.
+- **v0.3.0** — multi-cliente: definición canónica única en `AI/agents/`, `AI/commands/`, `AI/skills/`; render a `AI/clients/<cliente>/` con `scripts/render-clients.js` (opencode byte-idéntico a `AI/.opencode/`, que se conserva intacto); instaladores con flag `--client auto|all|<lista>` (detección por huellas, fusión idempotente con `SKIP`/`BACKUP` por dir); `prompts/setup.md` pregunta el cliente si es ambiguo y verifica adopción por cliente; CI exige `render-clients.js --check` antes de la guardia de versiones.
+
 - **v0.2.5** — fusión a `.opencode/` raíz: el instalador sincroniza `AI/.opencode/` (agents + commands + skills) en `.opencode/` del proyecto para que OpenCode descubra `orchestrator` y `/flow` (SKIP sin fuerza, `.opencode.bak` con fuerza); `prompts/setup.md` verifica adopción y fusiona el fragmento MCP.
 - **v0.2.4** — estilo Neon: una línea que lee `prompts/setup.md` (versionado, siempre al día) en vez de un bloque que caduca.
 - **v0.2.3** — prompt universal todo-en-uno: clona + instala con la versión que indique el README (nunca caduca), verifica AI/VERSION instalado.
 - **v0.2.2** — anti-huérfanos: bloque de agente con regla de cierre limpio (no dejar servidores corriendo, no borrar carpetas con procesos dentro) + troubleshooting de carpeta bloqueada (resmon → Identificadores asociados).
 - **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.
+- **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.2.5
+0.3.1