@kwirthmagnify/kwirth-docs-pinocchio 0.2.31

package/user/02-ui-tour.md

@@ -0,0 +1,96 @@
+# Recorrido por la UI
+
+Pinocchio es un canal, así que se abre como cualquier otro canal de kwirth: eliges el canal **Pinocchio** en
+el selector y lo arrancas. No tiene diálogo de *Setup* — no hay nada que configurar antes de arrancar.
+
+## La pestaña
+
+La pestaña es una única tarjeta con una cabecera y un flujo de mensajes que crece hacia abajo.
+
+![La pestaña de Pinocchio recién arrancada, todavía sin análisis](../images/ui-tab.png)
+
+**Cabecera**
+
+| Elemento     | Qué es                                                                       |
+|--------------|-------------------------------------------------------------------------------|
+| `Events: N`  | Número de entradas en el flujo (análisis + mensajes). No es el número de findings. |
+| `Status`     | `started`, `paused` o `stopped`, según el estado del canal.                    |
+| **Clear**    | Abre el diálogo de limpieza (ver abajo).                                       |
+| **Playground** | Abre el banco de pruebas. Ver [El Playground](06-playground.md).             |
+| **Config**   | Abre el menú de configuración.                                                 |
+
+**Flujo**
+
+El cuerpo hace autoscroll al final mientras estés abajo del todo; si subes a leer algo, deja de seguirte
+hasta que vuelvas al final. Cada análisis se pinta como:
+
+1. Una línea de cabecera con la marca de tiempo, el evento (`ADDED Deployment 'nginx' in namespace 'demo'`),
+   el LLM usado y los tokens consumidos, más un botón **Report**.
+2. Los **findings**, ordenados de `critical` a `low`, cada uno con su etiqueta de severidad.
+3. Una **tira de resumen** con PSS, el recuento por severidad y el riesgo global.
+
+Los findings y la tira de resumen son **clicables** y abren su diálogo de detalle.
+
+## El menú Config
+
+El botón **Config** abre un menú de tres entradas, la primera de ellas un grupo desplegable. El orden no es
+casual: cada una depende de la anterior.
+
+![El menú Config, con el grupo AI desplegado](../images/ui-config-menu.png)
+
+| Entrada           | Se habilita cuando…                    | Qué configura                                   |
+|-------------------|----------------------------------------|--------------------------------------------------|
+| **AI** ▸ **AI providers** | siempre                        | Proveedores de IA (OpenAI, Google, …) y su API key |
+| **AI** ▸ **AI models**    | hay al menos un provider       | Modelos concretos, con temperatura y coste        |
+| **Trigger**       | hay al menos un LLM                    | Los triggers y sus versiones                      |
+| **Import / Export** | siempre                              | Volcado y carga de triggers en JSON                |
+
+**AI** es un grupo plegable —el patrón habitual de kwirth, el mismo que usan Excubitor y Agora— y **arranca
+plegado**: hay que clicarlo para ver *AI providers* y *AI models*. Es lo que menos se toca una vez montado,
+por eso está recogido.
+
+Si abres Pinocchio por primera vez y **Trigger** está en gris, no es un fallo: es que aún no hay un LLM
+configurado. Empieza por **AI ▸ AI providers**. El detalle está en
+[Providers y modelos de IA](../admin/02-ai-config.md).
+
+> Los diálogos de **AI providers** y **AI models** no son de Pinocchio: son los diálogos comunes de IA de
+> kwirth (`AiConfigProvider` / `AiConfigLlm`), los mismos que usan los demás plugins con IA. Lo que configures
+> aquí lo verán también ellos.
+
+## Los diálogos de detalle
+
+**Detalle de un finding** (clic en cualquier finding) — muestra, en dos columnas, todo lo que el modelo
+rellenó: Control ID, categoría, confianza, *risk score*, descripción, evidencia e impacto a la izquierda;
+remediación y referencias a la derecha. Los campos vacíos no se pintan.
+
+**Detalle del análisis** (clic en la tira de resumen) — el recurso analizado (kind, nombre, namespace,
+imágenes), PSS actual y objetivo, riesgo global y recuento por severidad a la izquierda; controles superados,
+lo que el modelo **no pudo ver** y los próximos pasos a la derecha.
+
+**Report** (botón *Report* de la cabecera del análisis) — abre el informe en markdown renderizado. El botón
+está deshabilitado si ese análisis no trajo informe.
+
+## El diálogo Clear
+
+Hay dos limpiezas distintas y conviene no confundirlas, porque una es local y la otra afecta a todo el mundo:
+
+![El diálogo Clear findings](../images/ui-clear-dialog.png)
+
+- **Clear my view** — vacía **tu** pantalla. El backend conserva sus análisis y te los reenviará si
+  reconectas.
+- **Clear back** — borra los análisis guardados **en el canal**. Afecta a todos los fronts conectados y no
+  tiene vuelta atrás.
+
+## Colores de severidad
+
+Los mismos en toda la UI:
+
+| Nivel      | Color    |
+|------------|----------|
+| `critical` | rojo     |
+| `high`     | naranja  |
+| `medium`   | verde    |
+| `low`      | gris     |
+
+> ⚠️ Sí: `medium` se pinta en **verde**. Es el comportamiento actual del plugin y sorprende la primera vez.
+> Guíate por el texto de la etiqueta, no por el color.

package/user/03-concepts.md

@@ -0,0 +1,160 @@
+# Triggers, versiones y prompts
+
+Toda la configuración de Pinocchio se reduce a una lista de **triggers**. Esta página explica el modelo de
+datos y, sobre todo, **qué hace realmente el backend con cada campo**, que no siempre es lo que el nombre
+sugiere.
+
+## Trigger
+
+Un trigger define **cuándo** se dispara el análisis:
+
+| Campo       | Aplica a    | Qué hace                                                                       |
+|-------------|-------------|--------------------------------------------------------------------------------|
+| `id`        | ambos       | Identificador libre. Es lo que ves en la lista y lo que se usa al importar/exportar. |
+| `trigger`   | ambos       | `artifact` (objeto de Kubernetes) o `business` (JSON externo).                   |
+| `kind`      | `artifact`  | El kind de Kubernetes a vigilar. Debe coincidir **exactamente** con `obj.kind`.  |
+| `k8sEvent`  | `artifact`  | `ADDED`, `MODIFIED`, `DELETED` — o vacío (*Any*) para no filtrar por evento.     |
+| `versions`  | ambos       | Lista de versiones. Ver abajo.                                                  |
+
+El matching de un evento de Kubernetes es literal:
+
+```
+trigger.trigger === 'artifact'
+  && trigger.kind === evento.obj.kind
+  && (!trigger.k8sEvent || trigger.k8sEvent === evento.type)
+```
+
+Los triggers de tipo `business` **no filtran por espacio ni por tipo en el matching**: cualquier evento de
+negocio que llegue al canal dispara **todos** los triggers `business` que tengan una versión activa. El campo
+*Spaces* de la versión no se usa para filtrar (ver más abajo).
+
+## Versión
+
+Una versión es **el contenido del análisis**: qué se le pregunta al modelo y con qué medios.
+
+| Campo         | Qué hace                                                                                    |
+|---------------|---------------------------------------------------------------------------------------------|
+| `id`          | Identificador dentro del trigger. Único por trigger.                                          |
+| `description` | Texto libre; se ve bajo el id en la lista de versiones.                                       |
+| `enabled`     | Si está activa. **Sólo una versión por trigger puede estar activa a la vez.**                 |
+| `llm`         | El id del LLM configurado que se va a usar.                                                   |
+| `system`      | El *system prompt*. ⚠️ **Se ignora en los triggers `business`** (ver abajo).                  |
+| `promptType`  | `jinja` o `artifact`. Determina cómo se construye el prompt.                                  |
+| `prompt`      | La plantilla del prompt. Deshabilitada cuando `promptType` es `artifact`.                     |
+| `steps`       | Máximo de pasos del agente. Si es 0 o vacío, el backend usa **15**.                            |
+| `tools`       | Lista de tools que el modelo puede llamar.                                                     |
+| `autoTools`   | Si está marcado, se le entrega **todo el catálogo** de tools.                                  |
+| `spaces`      | Lista `space.type`. Hoy **no filtra nada**; ver [Límites](../admin/06-limits.md).              |
+| `action`      | `inform` / `cancel` / `repair`. **Hoy el backend no lo lee**: todo se comporta como `inform`.  |
+
+### Por qué "versiones" y no simplemente "triggers"
+
+Porque afinar un prompt es un proceso iterativo y **quieres conservar el que funcionaba**. El patrón previsto
+es: clonas la versión activa, retocas el prompt en la copia, la activas (lo que desactiva la anterior
+automáticamente) y comparas resultados. Si empeora, reactivas la vieja con un clic del interruptor.
+
+Al clonar una versión, la copia nace **desactivada** a propósito, para que no te cambie el comportamiento sin
+querer.
+
+## Cómo se construye el prompt
+
+Este es el punto donde más gente se equivoca. Depende de la combinación tipo de trigger × `promptType`:
+
+### `artifact` + `promptType: jinja`
+
+El `prompt` se renderiza con **nunjucks** usando el objeto de Kubernetes como contexto:
+
+```
+prompt = nunjucks.renderString(version.prompt, evento.obj)
+```
+
+Es decir, las variables disponibles son los campos del propio objeto:
+
+```jinja
+Audita este {{ kind }} llamado {{ metadata.name }} del namespace {{ metadata.namespace }}.
+
+Imágenes:
+{% for c in spec.template.spec.containers %}- {{ c.image }}
+{% endfor %}
+```
+
+El `system` **sí se usa**. Si está vacío, el backend cae a `'You are a very polite AI system'`.
+
+> ⚠️ **El objeto es el contexto de la plantilla, no un adjunto.** El modelo recibe **únicamente el texto
+> renderizado**: lo que tu plantilla no interpole, el modelo no lo ve. Un prompt como
+> `Audita el Deployment {{ metadata.name }} del namespace {{ metadata.namespace }}.` le llega al modelo como
+> `Audita el Deployment api-gateway del namespace demo.` — sin manifiesto, sin imágenes, sin
+> `securityContext`. Y el modelo contesta lo único que puede contestar:
+>
+> ![El modelo pide el manifiesto que la plantilla no le pasó](../images/playground-out.png)
+>
+> Si quieres que audite el recurso, **mete el recurso en la plantilla** (`{{ spec | dump(2) }}`) o usa
+> `promptType: artifact`, que le pasa el objeto entero.
+
+### `artifact` + `promptType: artifact`
+
+El prompt es, literalmente, **el objeto entero serializado**:
+
+```
+prompt = JSON.stringify(evento.obj)
+```
+
+El campo `prompt` se ignora por completo (y la UI lo deshabilita). Toda la instrucción tiene que estar en el
+`system`. Es la opción cómoda cuando el system ya dice "eres un auditor de PSS, analiza el manifiesto que te
+paso".
+
+### `business` (cualquier `promptType`)
+
+```
+prompt = nunjucks.renderString(version.prompt, {})
+```
+
+⚠️ Dos cosas importantes, ambas comprobables en el código del backend:
+
+1. **El contexto de renderizado está vacío.** Aunque pongas espacios en el campo *Spaces*, los datos del
+   evento **no se pasan a la plantilla**. Cualquier `{{ variable }}` que escribas se renderiza como cadena
+   vacía. En la práctica, un prompt `business` es texto fijo.
+2. **El `system` de la versión se ignora.** El backend usa un system fijo:
+   *"Use the tools provided to find information, and once you have the data, format your final response
+   strictly as a JSON object according to the schema."*
+
+Por eso un trigger `business` sólo tiene sentido si su valor está en las **tools**: el prompt fijo plantea la
+pregunta ("¿está el clúster saturado?") y el modelo la resuelve consultando el clúster.
+
+Ambos comportamientos están recogidos en [Límites conocidos](../admin/06-limits.md).
+
+## Qué devuelve cada tipo
+
+| Tipo       | Esquema de salida                                                                                     |
+|------------|--------------------------------------------------------------------------------------------------------|
+| `artifact` | Objeto completo: `resource`, `pss_current`, `pss_target`, `score_summary`, `global_risk`, `controls_passed`, `not_visible`, `next_steps`, `report`, `findings[]`, `hardened_yaml`. |
+| `business` | Sólo `{ response: string }`, que se muestra como un mensaje de texto en la pestaña.                     |
+
+El detalle de cada campo está en [Leer los findings](05-findings.md).
+
+## Un trigger de ejemplo, entero
+
+```json
+{
+  "id": "pss-deployments",
+  "trigger": "artifact",
+  "kind": "Deployment",
+  "k8sEvent": "ADDED",
+  "versions": [
+    {
+      "id": "v2",
+      "description": "PSS restricted + contexto de eventos",
+      "enabled": true,
+      "llm": "gemini-flash",
+      "promptType": "jinja",
+      "system": "Eres un auditor de seguridad de Kubernetes. Evalúa contra los Pod Security Standards y devuelve findings accionables.",
+      "prompt": "Audita el Deployment {{ metadata.name }} en {{ metadata.namespace }}.\n\nManifiesto:\n{{ spec | dump(2) }}",
+      "action": "inform",
+      "steps": 8,
+      "tools": ["get_deployment_yaml", "get_object_events", "get_workload_config_refs"],
+      "autoTools": false,
+      "spaces": []
+    }
+  ]
+}
+```

package/user/04-triggers.md

@@ -0,0 +1,96 @@
+# Configurar triggers
+
+**Config → Trigger** abre el editor. Es un diálogo a dos paneles: a la izquierda la lista de triggers y, bajo
+ella, las versiones del trigger seleccionado; a la derecha el editor de la versión.
+
+![El editor de triggers, con un trigger `artifact` sobre Deployment/ADDED](../images/triggers-dialog.png)
+
+## Panel izquierdo
+
+**Triggers.** Cada fila muestra el id y, debajo, el tipo y el kind (`artifact · Deployment`). Al final de la
+fila hay dos iconos que aparecen al pasar el ratón: **clonar** y **borrar**.
+
+Para crear uno, escribe un id en la caja de abajo y pulsa **+** (o Enter). Si la dejas vacía, se genera
+`trigger-N`. El trigger nace como `artifact` sin kind y sin versiones.
+
+Clonar un trigger copia **todo**, versiones incluidas, con el id sufijado `-copy`. Borrar pide confirmación.
+
+**Versions.** Debajo, las versiones del trigger seleccionado. Cada una tiene un **interruptor**:
+
+> ⚠️ Los interruptores son **excluyentes**. Al activar una versión, el resto se desactivan solas. Es
+> intencionado: un trigger sólo puede tener un comportamiento activo.
+
+Al clonar una versión, la copia nace **desactivada**, para que clonar nunca cambie lo que está pasando en
+producción.
+
+## Panel derecho: el editor de la versión
+
+Los campos de la fila superior se dividen en dos grupos y **no se guardan igual**:
+
+**Campos del trigger** — `Trigger ID`, `Trigger type`, `Kind`, `K8s Event`. Se aplican **según los tocas**,
+sin necesidad de pulsar nada más.
+
+**Campos de la versión** — todo lo demás. Sólo se guardan al pulsar **Add** / **Update**.
+
+| Campo         | Notas                                                                                       |
+|---------------|----------------------------------------------------------------------------------------------|
+| `Kind`        | Sólo si el tipo es `artifact`. Lista cerrada con los kinds que escucha el canal.               |
+| `K8s Event`   | Sólo si el tipo es `artifact`. *Any* deja pasar `ADDED`, `MODIFIED` y `DELETED`.               |
+| `Spaces`      | Sólo si el tipo es `business`. Formato `space.type,space.type`. Hoy no filtra nada.            |
+| `Version ID`  | Obligatorio: el botón de guardar está deshabilitado sin él. No puede repetirse en el trigger.  |
+| `Description` | Texto libre que aparece bajo el id en la lista.                                                |
+| `Action`      | `inform` / `cancel` / `repair`. Hoy sólo se comporta como `inform`.                             |
+| `LLM`         | Uno de los LLMs configurados. Sin LLMs no llegas ni a abrir este diálogo.                       |
+| `Steps`       | Máximo de pasos del agente. **0 o vacío ⇒ el backend usa 15**, no 0.                            |
+| Tool selector | Las tools disponibles, con la casilla *auto*. Ver [Tools y pasos](../admin/03-tools.md).        |
+| `System`      | El system prompt. Ignorado en triggers `business`.                                              |
+| `Prompt`      | La plantilla. Deshabilitada cuando el tipo de prompt es `artifact`.                              |
+
+## Botones
+
+| Botón      | Qué hace                                                                  |
+|------------|----------------------------------------------------------------------------|
+| **New**    | Vacía el editor para escribir una versión nueva.                            |
+| **Clone**  | Duplica la versión seleccionada, desactivada, con el id sufijado `-copy`.   |
+| **Remove** | Borra la versión seleccionada, con confirmación.                            |
+| **Add** / **Update** | Guarda. Dice *Add* si estás creando y *Update* si estás editando. |
+| **OK**     | Cierra el diálogo y **envía la configuración al backend**.                   |
+| **Cancel** | Descarta **todo** lo hecho en el diálogo.                                    |
+
+> ⚠️ **Add/Update no persiste nada por sí solo.** Trabajas sobre una copia local de la configuración; hasta
+> que no pulses **OK**, el backend no se entera. Si haces cinco cambios y cierras con **Cancel**, pierdes los
+> cinco.
+
+## Receta: auditar cada Deployment nuevo
+
+1. **Config → Trigger**, escribe `pss-deployments` en la caja de la izquierda y pulsa **+**.
+2. Con el trigger seleccionado: `Trigger type` = `artifact`, `Kind` = `Deployment`, `K8s Event` = `ADDED`.
+3. `Version ID` = `v1`. `LLM` = el que tengas. `Steps` = 5.
+4. Tools: marca `get_deployment_yaml` y `get_object_events`.
+5. `System`:
+   ```
+   Eres un auditor de seguridad de Kubernetes. Evalúa el recurso contra los Pod Security
+   Standards (baseline y restricted). Devuelve findings accionables, con evidencia concreta
+   tomada del manifiesto. No inventes controles que no puedas justificar.
+   ```
+6. Tipo de prompt `jinja`, `Prompt`:
+   ```jinja
+   Audita el Deployment {{ metadata.name }} del namespace {{ metadata.namespace }}.
+
+   Manifiesto:
+   {{ spec | dump(2) }}
+   ```
+   ⚠️ Las dos últimas líneas no son decorativas: **son las que le pasan el recurso al modelo**. Sin ellas
+   el modelo sólo recibe el nombre y el namespace, y te contestará pidiéndote el manifiesto. Ver
+   [Triggers, versiones y prompts](03-concepts.md).
+7. **Add** → activa el interruptor de `v1` → **OK**.
+8. Despliega algo y míralo aparecer en la pestaña.
+
+> Antes de activar un trigger sobre un kind con mucho movimiento (`Pod` + `MODIFIED` es el caso extremo),
+> pásate por [Tools y pasos del agente](../admin/03-tools.md): ahí está la cuenta de lo que eso cuesta.
+
+## Cómo probar sin activar nada
+
+No hace falta desplegar recursos de mentira para afinar un prompt. El
+[Playground](06-playground.md) ejecuta exactamente la misma tubería contra un payload que pegas a mano, y
+cuando el resultado te convence lo exporta a un trigger real.

package/user/05-findings.md

@@ -0,0 +1,108 @@
+# Leer los findings
+
+Un análisis de tipo `artifact` no devuelve texto libre: devuelve un **objeto con un esquema fijo** que el
+modelo está obligado a rellenar. Esta página explica qué significa cada campo y —más importante— **cuánto
+te puedes fiar de él**.
+
+## La línea de cabecera
+
+```
+2026-09-08T10:14:22.145Z  ADDED Deployment 'api-gateway' in namespace 'prod'
+                          [LLM:google/gemini-2.0-flash, IN:4821, OUT:1103]
+```
+
+- El evento que disparó el análisis.
+- El **provider y el modelo** que lo produjeron. Útil cuando comparas versiones de un trigger.
+- **IN / OUT** — tokens de entrada y de salida. Es tu factura. Si un trigger te sorprende en el coste, aquí
+  está la respuesta.
+
+## Los findings
+
+Cada finding es un hallazgo concreto. En la lista sólo se ven la severidad y la descripción; el resto está a
+un clic.
+
+| Campo          | Valores                                                                                | Qué es |
+|----------------|-----------------------------------------------------------------------------------------|--------|
+| `level`        | `critical` · `high` · `medium` · `low`                                                    | Severidad. Ordena la lista. |
+| `control_id`   | texto                                                                                     | Identificador del control que se incumple. |
+| `control_name` | texto                                                                                     | Nombre legible del control. Es el título del diálogo de detalle. |
+| `category`     | `privileges` · `identity` · `network` · `filesystem` · `supply_chain` · `resources` · `secrets` · `general` · `platform` | Familia del hallazgo. |
+| `confidence`   | `low` · `medium` · `high`                                                                 | Cuánta seguridad dice tener **el modelo**. |
+| `evidence`     | texto                                                                                     | El fragmento concreto que lo demuestra. |
+| `impact`       | texto                                                                                     | Qué puede pasar si no se arregla. |
+| `remediation`  | texto                                                                                     | Cómo arreglarlo. |
+| `references`   | lista                                                                                     | Enlaces o identificadores de referencia. |
+| `risk_score`   | número                                                                                    | Puntuación numérica que asigna el modelo. |
+
+> **El campo que hay que mirar siempre es `evidence`.** Un finding con evidencia concreta ("el contenedor
+> `api` declara `securityContext.privileged: true`") es verificable en dos segundos. Un finding sin
+> evidencia, o con evidencia genérica, es una alucinación candidata. Cruza `confidence` con `evidence`
+> antes de abrir un ticket.
+
+En la lista, si la descripción contiene un fragmento entre ` **` y `** `, se pinta en negrita y subrayado.
+Es un pequeño formateo heredado; no es markdown completo.
+
+## La tira de resumen
+
+Bajo los findings aparece una tira con el resumen del análisis. Se puede clicar para ver el detalle completo.
+
+**PSS: `baseline` → `restricted`**
+
+Los [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) de
+Kubernetes. `pss_current` es el nivel que el modelo considera que cumple el recurso **tal como está**;
+`pss_target` es al que podría llegar aplicando las remediaciones. Los valores posibles son `privileged`,
+`baseline`, `restricted` y `undefined`.
+
+`privileged` es el nivel **más permisivo** (sin restricciones) y `restricted` el **más estricto**. Si ves
+`pss_current: privileged`, es una mala noticia, no una buena.
+
+**critical:0 high:2 medium:5 low:1**
+
+El `score_summary`: recuento de findings por severidad, tal como lo cuenta el modelo.
+
+**Riesgo global**
+
+`global_risk`, la valoración de conjunto: `low`, `medium`, `high` o `critical`.
+
+## El detalle del análisis
+
+Al clicar la tira se abren tres cosas que no caben en la línea de resumen:
+
+- **Controls passed** — los controles que el recurso **sí** cumple. Sirve para ver que el modelo ha hecho el
+  repaso completo y no sólo ha buscado fallos.
+- **Not visible** — los controles que el modelo **no ha podido evaluar** con la información que tenía. Este
+  campo es oro: te dice dónde el análisis es incompleto y qué tool deberías haberle dado. Si `not_visible`
+  está lleno, sube los `steps` o añade tools.
+- **Next steps** — la lista de acciones recomendadas, en orden.
+
+También muestra el **recurso** analizado (kind, nombre, namespace e imágenes) tal como lo identificó el
+modelo. Compáralo con la línea de cabecera: si no coinciden, el modelo se ha confundido de objeto y el
+análisis entero es sospechoso.
+
+## El informe
+
+El botón **Report** abre el campo `report`: un informe **en markdown** redactado por el modelo, pensado para
+leerse como documento y no como lista. Se renderiza con el visor de markdown de kwirth.
+
+Es la salida que puedes pegar en un ticket o en un correo. Los findings son para triar; el informe es para
+explicar.
+
+## Cuando algo falla
+
+Si la llamada al modelo revienta, Pinocchio **no se calla**: publica un análisis con dos findings de nivel
+`critical`, uno con el mensaje de error legible y otro con el error serializado entero. Verás algo como:
+
+```
+critical   Pinocchio analysis ended in error while processing 'events' when
+           analyzing 'api-gateway' in namespace 'prod' [Kind:Deployment]
+critical   {"name":"AI_APICallError","message":"...
+```
+
+Las causas más habituales: API key caducada, cuota agotada en el proveedor, o el modelo elegido no soporta
+salida estructurada. El segundo finding, aunque sea feo, suele traer el mensaje exacto del proveedor.
+
+## Análisis de triggers `business`
+
+Los triggers de negocio **no producen findings**. Su salida es un único campo de texto que aparece en el
+flujo como un mensaje normal, precedido de otro mensaje con el evento recibido. Nada de PSS, ni severidades,
+ni informe.

package/user/06-playground.md

@@ -0,0 +1,134 @@
+# El Playground
+
+El Playground es el banco de pruebas: te deja **ejecutar la tubería completa** —prompt, modelo, tools— contra
+un payload que pegas a mano, sin crear ningún trigger y sin tocar el clúster. Es donde se afinan los prompts.
+
+Se abre con el botón **Playground** de la cabecera de la pestaña.
+
+## El ciclo de trabajo
+
+```
+   Pestaña LLM          Pestaña Call             Pestaña IN / OUT
+   -----------          ------------             ----------------
+   elige modelo   -->   escribe system    -->    Apply Config  -->  Fire  -->  mira la traza
+   pega el payload      y prompt, tools           (sube al back)     (inyecta
+                                                                     el evento)
+```
+
+Dos botones, en este orden obligatorio:
+
+1. **Apply Config** — sube al backend el modelo, los pasos, las tools, el system y el prompt. Mientras no lo
+   pulses, **Fire** está deshabilitado. El botón se pone verde y dice *Config applied*.
+2. **Fire** — inyecta el evento. Cualquier cambio en el modelo, los pasos, las tools, el system o el prompt
+   **vuelve a marcar la config como sucia** y tendrás que aplicarla otra vez.
+
+## Pestaña LLM — el evento de entrada
+
+| Campo         | Qué es                                                                |
+|---------------|-----------------------------------------------------------------------|
+| `LLM`         | Uno de los LLMs configurados.                                          |
+| `Max steps`   | Tope de pasos del agente para esta prueba.                             |
+| Business / Artifact | El tipo de evento que vas a simular.                             |
+| `Artifact Kind` | Sólo en modo Artifact. Se inyecta como `kind` si el payload no lo trae. |
+| `K8s Event`   | Sólo en modo Artifact. ⚠️ Ver la advertencia de más abajo.              |
+| `Space` / `Type` | Sólo en modo Business. ⚠️ Ver la advertencia de más abajo.           |
+| El textarea grande | El payload: el JSON del artefacto, o el evento de negocio.        |
+
+![La pestaña LLM del Playground, con un Deployment de ejemplo](../images/playground-llm.png)
+
+El iconito de reloj junto a las cajas abre el **historial**: los últimos 25 valores que has usado en ese
+campo, con una papelera para borrar los que sobren. Se guardan al pulsar **Save** y sobreviven al cierre del
+diálogo.
+
+## Pestaña Call — la llamada
+
+`Prompt type`, el selector de tools, y los dos textareas de `System` y `Prompt`, con sus historiales. Es el
+mismo juego de campos que el editor de triggers, más los dos botones **Apply Config** y **Fire**.
+
+![La pestaña Call del Playground; Fire está deshabilitado hasta aplicar la config](../images/playground-call.png)
+
+## Pestañas IN y OUT
+
+El Playground **no reutiliza el flujo de la pestaña principal**: cuenta sólo los mensajes producidos desde
+que lo abriste, y los reparte en dos vistas.
+
+- **IN** — la traza de entrada: qué recibió el backend y qué le mandó al modelo. Verás
+  `[Playground] type/llm/system/prompt/tools`, cada `[Tool call]` con sus argumentos y cada `[Tool result]`
+  con lo que devolvió. Es la vista que usas para entender **por qué** el modelo contestó lo que contestó.
+
+  ![La pestaña IN, con el prompt YA RENDERIZADO que recibió el modelo](../images/playground-in.png)
+
+  Fíjate en la línea `prompt:`: es la plantilla **ya renderizada**. Ahí se ve que `{{ metadata.name }}` se
+  convirtió en `api-gateway`… y también que el manifiesto **no** viaja con ella. Es la comprobación más
+  rápida de que tu plantilla dice lo que crees que dice.
+
+- **OUT** — la respuesta: `[Playground] response` y el recuento de tokens y pasos.
+
+  ![La pestaña OUT, con la respuesta del modelo y el gasto de tokens](../images/playground-out.png)
+
+Al cerrar el diálogo, estos mensajes **se retiran del flujo principal**: no ensucian la pestaña.
+
+## Advertencias importantes
+
+El Playground no ejecuta exactamente el mismo camino que un trigger real. Estas cuatro diferencias son las
+que más tiempo hacen perder:
+
+### 1. En modo Business, el payload ES el prompt
+
+En modo Business el backend **descarta el `Prompt` de la pestaña Call** y usa el contenido del textarea de
+evento como prompt, renderizado con jinja sobre un contexto vacío. Si estás probando un trigger de negocio,
+escribe la pregunta en el textarea del evento, no en el campo Prompt.
+
+### 2. En modo Business, cambiar Space/Type rompe la prueba
+
+El backend sólo redirige un evento al Playground si llega con **`space: launch` y `type: immediate`** —los
+valores por defecto—. Si los cambias, el evento deja de ir al Playground y pasa a evaluarse contra tus
+triggers de negocio **reales**. Y si además el par que has escrito no es uno de los tres a los que el canal
+está suscrito (`customers.status`, `branches.status`, `launch.immediate`), no llegará a ninguna parte y no
+verás absolutamente nada.
+
+En modo Artifact el problema no existe: el `Fire` usa `launch`/`immediate` sin preguntar.
+
+### 3. El `Prompt type` que elijas no siempre manda
+
+En modo Artifact, el backend decide el tipo de prompt **según tengas o no texto en el campo Prompt**: si hay
+prompt lo trata como `jinja`, y si está vacío como `artifact`. El selector `Prompt type` de la pestaña Call
+no se respeta en esta ruta. Para probar el modo `artifact` puro, **vacía el campo Prompt**.
+
+### 4. El evento simulado siempre es `ADDED`
+
+El objeto que inyectas se le entrega al modelo como un evento `ADDED`, sea cual sea el `K8s Event` que
+selecciones. Ese selector se guarda con el estado del Playground, pero no cambia la simulación.
+
+## Diferencias de motor con un trigger real
+
+| | Trigger real | Playground |
+|---|---|---|
+| Salida | Estructurada (findings, PSS, informe) | **Texto libre** |
+| `autoTools` | Entrega el catálogo entero al modelo | Hace una **llamada previa** al modelo para que elija las tools, y sólo le pasa esas |
+| Si el modelo no responde texto | Es un error | Hace una **segunda llamada** resumiendo los resultados de las tools |
+
+La primera diferencia es la que importa: en el Playground **nunca vas a ver un finding**. Sirve para validar
+que el prompt lleva al modelo por el camino correcto y que las tools devuelven lo que esperas; el formato
+estructurado sólo lo verás cuando lo exportes a un trigger y lo dispares de verdad.
+
+La segunda explica por qué `autoTools` sale más caro en el Playground que en producción: hay una llamada
+extra, cuya elección de tools se te muestra como `[Auto tools] selected: ...`.
+
+## Llevarse el resultado
+
+Los cuatro botones de abajo a la izquierda:
+
+| Botón        | Qué hace                                                                          |
+|--------------|------------------------------------------------------------------------------------|
+| **Import**   | Carga en el Playground la configuración de **un trigger existente**, eligiendo trigger y versión. Sobrescribe lo que tengas. |
+| **Export**   | Convierte el Playground en un trigger: **New trigger** (nuevo, con la versión `v1` activada) o **Add version** (añade una versión desactivada a un trigger existente). Cierra el diálogo. |
+| **Upload**   | Carga la configuración desde un fichero JSON local.                                 |
+| **Download** | Guarda la configuración actual en `pinocchio-playground-AAAA-MM-DD.json`.           |
+
+Y a la derecha, **Save** (persiste el estado y los historiales) y **Cancel** (cierra sin guardar).
+
+> ⚠️ **Export → New trigger no se lleva el Kind ni el K8s Event.** El trigger nuevo se crea con el tipo
+> (`artifact` o `business`) y la versión, pero sin `kind` y sin `k8sEvent`, así que un trigger `artifact`
+> recién exportado **no casará con ningún evento** hasta que lo abras en **Config → Trigger** y le pongas el
+> kind a mano. Está recogido en [Límites conocidos](../admin/06-limits.md).