@kwirthmagnify/kwirth-docs-pinocchio 0.2.31

package/_sidebar.md

@@ -0,0 +1,21 @@
+- [Pinocchio](index.md)
+
+- **Conceptos**
+  - [Introducción y modelo mental](user/01-introduction.md)
+  - [Cómo funciona](user/00-how-it-works.md)
+  - [Triggers, versiones y prompts](user/03-concepts.md)
+
+- **Guía de usuario**
+  - [Recorrido por la UI](user/02-ui-tour.md)
+  - [Configurar triggers](user/04-triggers.md)
+  - [Leer los findings](user/05-findings.md)
+  - [El Playground](user/06-playground.md)
+  - [Import / Export de triggers](user/07-import-export.md)
+
+- **Guía de administrador**
+  - [Instalación](admin/01-setup.md)
+  - [Providers y modelos de IA](admin/02-ai-config.md)
+  - [Tools y pasos del agente](admin/03-tools.md)
+  - [Plantillas de prompt](admin/04-prompts.md)
+  - [Permisos y acceso](admin/05-rbac.md)
+  - [Límites conocidos](admin/06-limits.md)

package/admin/01-setup.md

@@ -0,0 +1,98 @@
+# Instalación
+
+Pinocchio es un plugin de tipo **canal**. Se instala como cualquier otro plugin de kwirth, pero tiene una
+dependencia dura y una condición previa que conviene resolver antes de que los usuarios abran el canal.
+
+## Requisitos
+
+| Requisito | Detalle |
+|-----------|---------|
+| Provider `business` | **Obligatorio.** El manifiesto declara `requiresExtension: ["provider:business:0.1.6"]`. kwirth no deja instalar el plugin sin él. |
+| Providers `events` y `metrics` | Los aporta el core. No hay nada que instalar. |
+| Almacenamiento del canal | El canal declara `storage: true`: kwirth le da un almacén donde guarda la clave `pinocchio-config`. |
+| Un provider de IA y un LLM | **No es un requisito de instalación, pero sí de uso.** Sin ellos el canal arranca y no sirve para nada. Ver [Providers y modelos de IA](02-ai-config.md). |
+| Tipo de clúster | El canal declara `sources: [KUBERNETES]`. No funciona sobre orígenes que no sean Kubernetes. |
+
+**Reinicio:** el manifiesto declara `requiresRestart: false`. Instalarlo o actualizarlo no obliga a reiniciar
+el backend de kwirth.
+
+## Instalar en producción
+
+Desde la UI de administración de kwirth, en el gestor de plugins: búscalo en el marketplace, o instálalo
+desde la URL del tarball publicado:
+
+```
+https://registry.npmjs.org/@kwirthmagnify/kwirth-plugin-pinocchio/-/kwirth-plugin-pinocchio-<version>.tgz
+```
+
+Instala **antes** el provider `business`; si no, la instalación del plugin se rechaza por dependencia no
+satisfecha.
+
+## Instalar en desarrollo
+
+En un entorno de desarrollo, el backend carga los plugins desde disco leyendo `back/kwirth-dev.json`:
+
+```json
+{
+  "plugins": {
+    "pinocchio": "../plugins/pinocchio/dist"
+  },
+  "providers": {
+    "business": "../providers/business/dist"
+  },
+  "docs": {
+    "pinocchio": "../plugins/pinocchio/docs/pinocchio.tgz"
+  }
+}
+```
+
+La entrada de `docs` es la que hace que **esta guía** quede accesible desde la propia UI de kwirth.
+
+## Construir desde fuente
+
+```bash
+cd plugins/pinocchio
+npm install
+npm run build     # front.js + back.js + docs/pinocchio.tgz + dist/package.json
+npm run watch     # reconstruye todo en cada cambio, la guía incluida
+npm run docs      # sólo reempaqueta la guía
+```
+
+`build` y `watch` cubren **las tres piezas**: el bundle de front, el de back y el tarball de la guía. No hace
+falta acordarse de empaquetar la documentación por separado.
+
+Con `watch` en marcha:
+
+- un cambio en `src/front/` lo recoge el navegador solo (el front sondea `front.js` cada 2 s);
+- un cambio en `src/back/` **requiere reiniciar el core**, que cachea el módulo de back;
+- un cambio en `docs/guide/` reconstruye el tarball al vuelo, pero el core lo instala al arrancar, así que se
+  ve tras reiniciarlo.
+
+## Qué hace el canal al arrancar
+
+Cada vez que un usuario abre el canal, la instancia del backend:
+
+1. Se suscribe a los providers `metrics`, `business` (espacios `customers.status`, `branches.status`,
+   `launch.immediate`) y `events` (los 11 kinds que vigila).
+2. Lee los **providers de IA** del almacén común (`kwirth-ai-providers`) y construye los modelos.
+3. Lee su propia configuración (`pinocchio-config`) del almacén del canal.
+4. Lee los **LLMs** del almacén común (`kwirth-ai-llms`); si hay alguno, sustituye a los que tuviera guardados.
+
+> ⚠️ **Los puntos 2 y 4 sólo ocurren al arrancar el canal.** Si un administrador crea un provider desde los
+> menús *AI Providers* del core con el canal ya abierto, ese canal no lo verá hasta que se cierre y se vuelva
+> a abrir. Ver [Límites conocidos](06-limits.md).
+
+## Comportamiento del canal
+
+Lo que el canal declara al core, y lo que significa para el usuario:
+
+| Propiedad | Valor | Efecto |
+|-----------|-------|--------|
+| `routable` | `false` | No se puede dirigir a un recurso concreto: siempre es de clúster. |
+| `pauseable` | `true` | Se puede pausar y continuar. |
+| `modifiable` | `false` | No se puede reconfigurar la instancia en caliente. |
+| `reconnectable` | `true` | Sobrevive a una reconexión del websocket. |
+| `resourced` | `false` | No selecciona namespaces ni pods al arrancar. |
+| `cluster` | `true` | Es un canal de ámbito de clúster. |
+
+No tiene diálogo de *Setup*: no hay nada que elegir antes de arrancarlo.

package/admin/02-ai-config.md

@@ -0,0 +1,125 @@
+# Providers y modelos de IA
+
+Esta es la configuración que hay que resolver **antes** de que Pinocchio sirva para algo. Y lo primero que
+hay que entender es que **no es configuración de Pinocchio**.
+
+## La configuración de IA es de kwirth, no del plugin
+
+Pinocchio no guarda sus propios providers ni sus propios modelos. Los lee del **almacén común de kwirth**,
+compartido con todos los demás plugins que usan IA:
+
+| Qué | Clave | Dónde |
+|-----|-------|-------|
+| Providers (con las API keys) | `kwirth-ai-providers` | **Secret** de Kubernetes |
+| LLMs | `kwirth-ai-llms` | **ConfigMap** de Kubernetes |
+
+Las consecuencias prácticas son tres:
+
+1. Si ya configuraste un provider para otro plugin, **Pinocchio lo ve**. No hay que repetir nada.
+2. Si lo configuras desde Pinocchio, **lo verán los demás**. Los diálogos del grupo *AI* del menú Config
+   (*AI providers* / *AI models*) son literalmente los mismos componentes comunes
+   (`AiConfigProvider` / `AiConfigLlm`) que usa el core en sus menús *AI Providers* / *AI Models*.
+3. Las claves viven en un **Secret**, no en un ConfigMap. Quien tenga permiso de lectura sobre los Secrets del
+   namespace de kwirth puede leerlas.
+
+## Provider
+
+Un *provider* es una cuenta contra un proveedor de IA: el adaptador y la clave.
+
+| Campo | Qué es |
+|-------|--------|
+| `Name` | Identificador libre de **esta** instancia de provider (`openai-prod`, `huawei-maas`). Es lo que referencian los LLMs. |
+| `Type` | El adaptador de SDK. Lista cerrada: `google`, `openai`, `openrouter`, `mistral`, `groq`, `deepseek`, `anthropic`, `openai-compat`. |
+| `API Key / Token` | La credencial. Campo de contraseña con botón de ojo para revelarla. |
+| `Base URL` | **Sólo para `openai-compat`.** La URL base de la API compatible con OpenAI (Huawei MaaS, vLLM, LM Studio…). Debe apuntar a la raíz; el adaptador añade `/v1` si falta. |
+
+![El diálogo de providers, con el contador de modelos cargados por provider](../images/admin-ai-provider.png)
+
+Al elegir un `Type`, si el nombre está vacío se rellena solo con el tipo. **Déjalo así salvo que tengas una
+razón** — ver la advertencia del final de la página.
+
+**Load models** consulta al proveedor el catálogo de modelos disponibles y lo cachea en el provider. La
+llamada la hace el **core** de kwirth (`POST /core/aiconfig/loadmodels`), no el plugin, porque es el core
+quien tiene los adaptadores de cada SDK. Si el botón no aparece o falla, revisa que la clave sea válida.
+
+Sin modelos cargados, el provider aparece **deshabilitado** en el desplegable del diálogo de LLM.
+
+> ⚠️ El botón **Export** de este diálogo descarga `kwirth-providers.json` **con las API keys en claro**.
+> Trátalo como un secreto: no lo subas a un repositorio ni lo mandes por correo.
+
+## LLM
+
+Un *LLM* es un modelo concreto de un provider concreto, con sus parámetros. Es lo que referencian los
+triggers, por su `LLM ID`.
+
+| Campo | Qué es |
+|-------|--------|
+| `LLM ID` | El identificador que usarán los triggers. **Elígelo con cuidado**: es lo que viaja en un export de triggers. |
+| `Provider` | Uno de los providers configurados. Sólo se pueden elegir los que tienen modelos cargados. |
+| `Model` | Desplegable con los modelos cargados del provider; si el provider no tiene catálogo, se convierte en una caja de texto libre. |
+| `Model temperature` | Temperatura. ⚠️ Pinocchio la **recorta al rango 0–1** antes de llamar al modelo. |
+| `Input / Output cost / M tokens` | Coste informativo por millón de tokens. No lo usa el motor: es para que puedas calcular la factura. |
+| `Use provider API Key` | Si está marcado, usa la clave del provider. Si no, puedes darle una clave específica a este LLM. |
+
+![El diálogo de LLMs; cada entrada lista su id y el provider del que cuelga](../images/admin-ai-llm.png)
+
+Para análisis de seguridad, **temperatura baja** (0 – 0.2). Lo que quieres es un auditor consistente, no uno
+creativo.
+
+## Salida estructurada: no todos los modelos valen
+
+Los triggers de tipo `artifact` exigen al modelo una respuesta que cumpla un esquema JSON estricto. Un modelo
+pequeño o antiguo que no soporte *structured output* fallará sistemáticamente, y lo verás como un análisis con
+dos findings `critical` y el error del proveedor.
+
+Pinocchio añade opciones específicas por proveedor para que esto funcione:
+
+| Proveedor | Opciones que envía |
+|-----------|--------------------|
+| `google` | `{ google: { structuredOutputs: true } }` |
+| `groq` | `{ groq: { structuredOutputs: true } }` |
+| `mistral` | `{ mistral: { strictJsonSchema: true, structuredOutputs: true } }` |
+| cualquier otro | `{ openai: {} }` |
+
+> ⚠️ **Gotcha importante.** Esa tabla se elige por el **`Name`** del provider, no por su `Type`. El modelo
+> sí se construye correctamente por el tipo, pero las opciones de salida estructurada no.
+>
+> Es decir: un provider de tipo `google` llamado `google` funciona; el **mismo** provider llamado
+> `gemini-prod` construye el modelo bien pero **pierde** el `structuredOutputs: true`, y los triggers
+> `artifact` pueden empezar a fallar sin motivo aparente.
+>
+> **Recomendación: deja el `Name` del provider igual que su `Type`** mientras no tengas que crear dos cuentas
+> del mismo proveedor. Si necesitas varias, usa una con el nombre canónico para Pinocchio. Está recogido en
+> [Límites conocidos](06-limits.md).
+
+## El orden importa
+
+El menú Config va habilitando entradas conforme cumples los requisitos:
+
+```
+AI ▸ AI providers   (siempre)
+   |
+   v  con >= 1 provider
+AI ▸ AI models
+   |
+   v  con >= 1 LLM
+Trigger
+```
+
+Si un usuario te dice que "Trigger está en gris", no es un fallo del plugin: falta el LLM.
+
+## Cuándo lee el canal esta configuración
+
+**Sólo al arrancar la instancia del canal.** Si creas un provider o un LLM desde los menús *AI Providers* /
+*AI Models* del core mientras un usuario tiene el canal abierto, ese usuario no lo verá hasta cerrar y
+reabrir el canal.
+
+En cambio, si lo creas **desde el propio menú Config de Pinocchio**, el canal sí se entera al momento: el
+plugin manda un `PROVIDERSSET`/`CONFIGSET` que reescribe el almacén y recarga los modelos.
+
+## Multi-clúster
+
+La configuración de IA **no viaja entre clústeres**. Los menús del core escriben en el backend **local**,
+pero un canal abierto contra otro kwirth lee el almacén de **ese** clúster. Si operas una federación, tienes
+que configurar providers y LLMs en cada clúster, y con los **mismos ids de LLM** si quieres poder mover
+triggers entre ellos. Ver [Límites conocidos](06-limits.md).

package/admin/03-tools.md

@@ -0,0 +1,131 @@
+# Tools y pasos del agente
+
+Las **tools** son lo que separa a Pinocchio de un chat al que le pegas un YAML. Son funciones reales,
+ejecutadas dentro del clúster, que el modelo puede invocar por su cuenta mientras razona. Esta página
+explica el catálogo, cómo se controla el gasto y —lo más importante— **por qué `Auto` es peligroso**.
+
+## Cómo funciona la ejecución con tools
+
+Cuando un trigger se dispara, el backend construye una llamada al modelo con:
+
+- el `system` y el `prompt`,
+- el subconjunto de tools que la versión declara,
+- un tope de pasos: `stopWhen(stepCountIs(steps))`.
+
+El modelo decide si necesita datos. Si los necesita, llama a una tool; el backend la ejecuta, le devuelve el
+resultado, y eso cuenta como **un paso**. El ciclo se repite hasta que el modelo responde o se agotan los
+pasos. Cada paso es una llamada de pago, con todo el contexto acumulado en la entrada.
+
+> Si `steps` es 0 o está vacío, el backend **no usa 0**: usa **15**. Es el error de configuración más caro
+> que se puede cometer en este plugin.
+
+Todas las llamadas y respuestas de tools se registran como trazas en el log del backend
+(`[pinocchio] tool <nombre> ...`), así que se puede auditar qué consultó el modelo.
+
+## El catálogo
+
+El catálogo lo aporta `kwirth-common-ai` y es el mismo para todos los plugins de IA de kwirth. El canal se lo
+envía al front al arrancar, así que el selector siempre muestra lo que el backend soporta de verdad.
+
+![El selector de tools, con la descripción de cada una](../images/tool-selector.png)
+
+### Lectura — inventario y configuración
+
+| Tool | Para qué |
+|------|----------|
+| `list_namespaces` | Namespaces con estado y etiquetas. |
+| `get_cluster_data` | Nombre, sabor (AKS/EKS/GKE/k3s/k3d), vCPUs, memoria, nodos. |
+| `get_node_data` | Configuración de los nodos (nombre, IP). |
+| `get_workload_data` | Todos los workloads del clúster; filtrable por namespace. |
+| `get_space_data` | Todo lo que hay en un namespace. |
+| `list_services` / `get_service_yaml` | Services del clúster / manifiesto completo de uno. |
+| `list_ingresses` / `get_ingress_yaml` | Ingresses / manifiesto completo de uno. |
+| `get_pod_yaml` / `get_deployment_yaml` | Manifiesto completo de un Pod o Deployment. |
+
+### Lectura — diagnóstico
+
+| Tool | Para qué |
+|------|----------|
+| `describe_pod` | Equivalente a `kubectl describe pod`: motivo de espera/terminación, exitCode (OOMKilled, CrashLoop…), reinicios, probes. |
+| `get_pod_logs` | Logs del contenedor. Con `previous:true`, los de la instancia que petó — la causa raíz de un CrashLoopBackOff. |
+| `get_cluster_events` / `get_object_events` | Eventos de Kubernetes del clúster o de un objeto concreto. |
+| `get_rollout_history` | Revisiones de un Deployment: qué imagen y qué env tenía cada una. Para ver **qué cambió** justo antes de romperse. |
+| `get_configmap` / `get_secret` | Datos de un ConfigMap / claves de un Secret (**valores redactados**). Un cambio de valor no genera revisión de rollout: por eso hay que mirarlos aparte. |
+| `get_workload_config_refs` | Qué ConfigMaps y Secrets consume un Deployment, con su fecha de última modificación. |
+| `get_source_file` | Trae un fichero de un repo Git (GitHub/GitLab) en una ref, para seguir un stack trace hasta el fichero:línea culpable. |
+| `get_certificate_info` | Detalles del certificado TLS de un host: emisor, validez, SANs, huella. |
+
+### Lectura — uso de recursos
+
+`get_cluster_usage`, `get_node_usage`, `get_deployment_usage` y sus versiones históricas
+`get_prev_cluster_usage`, `get_prev_node_usage`, `get_prev_deployment_usage`, `get_prev_space_data`.
+
+Estas tools se alimentan del **buffer de métricas** del canal: las últimas 100 lecturas del provider
+`metrics`. Si acabas de abrir el canal, el histórico estará casi vacío.
+
+### Escritura — ⚠️ modifican el clúster
+
+| Tool | Qué hace |
+|------|----------|
+| `add_replica` / `remove_replica` | Escala un Deployment arriba o abajo (mínimo 1 réplica). |
+| `restart_deployment` | Rollout-restart de un Deployment. |
+| `delete_pod` | Borra un pod; su controlador lo recrea. |
+| `add_node` / `remove_node` | Añade o quita un nodo del clúster (en k3d, vía `k3d node create/delete`). |
+| `start_node` / `stop_node` | Arranca o para un nodo. |
+
+### De prueba
+
+`times_two` y `father_of` son tools de juguete para verificar que la cadena de tool-calling funciona. No las
+pongas en un trigger real.
+
+## El interruptor `Auto`: léelo antes de usarlo
+
+El selector de tools tiene un interruptor **Auto**. Lo que hace **depende de dónde estés**, y la diferencia
+es importante:
+
+**En un trigger real** — `Auto` entrega al modelo el **catálogo completo, sin filtrar**. Sin selección previa
+y, sobre todo, **sin quitar las tools de escritura**.
+
+> ⚠️ **Un trigger con `Auto` activado puede escalar, reiniciar, borrar pods y quitar nodos.** El plugin no
+> aplica ningún filtro de sólo-lectura. Si el modelo decide que la forma de arreglar lo que ve es reiniciar
+> el Deployment, tiene la herramienta para hacerlo.
+>
+> **Recomendación: no uses `Auto` en triggers.** Marca a mano las tools de lectura que el análisis necesite.
+> Es más trabajo una vez y te ahorra una sorpresa en producción.
+
+**En el Playground** — `Auto` hace una **llamada previa** al modelo pidiéndole que elija qué tools necesita, y
+sólo le pasa esas. Es más barato en tokens de contexto pero más caro en llamadas, y te muestra la elección
+como `[Auto tools] selected: ...`. Sigue sin filtrar las de escritura.
+
+## El coste, con números
+
+El gasto de un trigger es, aproximadamente:
+
+```
+coste ≈ (nº de disparos) × (nº de pasos) × (tokens de contexto acumulados)
+```
+
+Los tres factores se multiplican, y el primero es el que se dispara sin que te des cuenta:
+
+| Trigger | Disparos al día en un clúster mediano |
+|---------|----------------------------------------|
+| `Deployment` + `ADDED` | decenas |
+| `Deployment` + `MODIFIED` | cientos |
+| `Pod` + `ADDED` | cientos |
+| `Pod` + `MODIFIED` | **miles** — cada cambio de estado, cada probe, cada reinicio |
+| `Pod` + *Any* | lo anterior, por tres |
+
+Reglas prácticas:
+
+1. **Empieza siempre por `ADDED`**, nunca por *Any*. Analiza lo que nace, no lo que respira.
+2. **Evita `Pod`.** Analiza el `Deployment`, que es donde está la decisión de diseño; los pods sólo la
+   ejecutan, y hay muchos más.
+3. **`steps` bajo para empezar** (3–5). Súbelo sólo si el campo `not_visible` de los análisis te dice que al
+   modelo le faltó información.
+4. **Mira los tokens** en la línea de cabecera de cada análisis (`IN:`/`OUT:`). Es la medida real, no una
+   estimación.
+5. **Prueba en el Playground.** Un prompt mal calibrado que hace 15 llamadas a tools se detecta gratis ahí,
+   no en producción.
+
+Los campos `Input / Output cost per M tokens` del diálogo de LLM existen justo para que puedas traducir esos
+tokens a dinero.

package/admin/04-prompts.md

@@ -0,0 +1,147 @@
+# Plantillas de prompt
+
+Pinocchio renderiza los prompts con **[nunjucks](https://mozilla.github.io/nunjucks/)** (la implementación
+JavaScript de Jinja2), con `autoescape` activado. Esta página recoge qué variables hay disponibles en cada
+ruta y cómo escribir un system que produzca findings útiles en vez de generalidades.
+
+## Qué contexto recibe la plantilla
+
+Esto es lo que más confusión genera, así que va primero y en tabla:
+
+| Tipo de trigger | `promptType` | Contexto de render | El `system` |
+|-----------------|--------------|--------------------|-------------|
+| `artifact` | `jinja` | **El objeto de Kubernetes entero** | Se usa |
+| `artifact` | `artifact` | *(no hay render: el prompt es `JSON.stringify(objeto)`)* | Se usa |
+| `business` | cualquiera | **Vacío `{}`** | **Se ignora** |
+
+El caso `business` merece repetirse: aunque rellenes el campo *Spaces*, **los datos del evento no llegan a la
+plantilla**. Cualquier `{{ variable }}` se renderiza como cadena vacía. Un prompt `business` es, en la
+práctica, texto fijo, y su valor está en las tools que le des al modelo, no en los datos que le pases.
+
+## Variables disponibles en `artifact` + `jinja`
+
+> ⚠️ **Antes de nada: el objeto es el contexto, no un adjunto.** El modelo recibe **sólo el texto
+> renderizado**. Lo que la plantilla no interpole, no llega. Es el error más caro de esta página: escribes
+> `Audita el Deployment {{ metadata.name }}`, el modelo recibe `Audita el Deployment api-gateway`, y te
+> contesta que le pases el YAML. Si quieres que audite el recurso, **vuelca el recurso en la plantilla**
+> (`{{ spec | dump(2) }}`) o usa `promptType: artifact`.
+
+El contexto **es el objeto de Kubernetes tal cual**. No hay envoltorio ni prefijo: escribes las rutas del
+manifiesto directamente.
+
+```jinja
+{{ kind }}                                    → "Deployment"
+{{ apiVersion }}                              → "apps/v1"
+{{ metadata.name }}                           → "api-gateway"
+{{ metadata.namespace }}                      → "prod"
+{{ metadata.labels.app }}                     → "gateway"
+{{ metadata.creationTimestamp }}              → "2026-09-08T10:14:21Z"
+{{ spec.replicas }}                           → 3
+{{ spec.template.spec.serviceAccountName }}   → "gateway-sa"
+{{ status.readyReplicas }}                    → 2
+```
+
+La estructura cambia según el kind: en un `Pod` los contenedores están en `spec.containers`, mientras que en
+un `Deployment` o un `StatefulSet` están en `spec.template.spec.containers`. Escribe la plantilla para el
+kind concreto del trigger.
+
+Bucles y condicionales funcionan como en Jinja2:
+
+```jinja
+Contenedores del {{ kind }} {{ metadata.name }}:
+{% for c in spec.template.spec.containers %}
+- {{ c.name }} → {{ c.image }}
+  {% if c.securityContext %}securityContext: {{ c.securityContext | dump }}{% else %}sin securityContext{% endif %}
+  {% if not c.resources.limits %}⚠ sin resource limits{% endif %}
+{% endfor %}
+```
+
+El filtro `| dump` serializa un subobjeto a JSON, y acepta un argumento de indentación (`{{ spec | dump(2) }}`).
+Es la forma corta de meter un bloque entero del manifiesto en el prompt sin recorrerlo campo a campo — y,
+como se explica arriba, **es lo que hace que el modelo vea de verdad el recurso**.
+
+> ⚠️ `autoescape` está **activado**. Los caracteres `<`, `>`, `&`, `'` y `"` de los valores salen escapados
+> como entidades HTML. Rara vez importa en un manifiesto de Kubernetes, pero si un valor te llega como
+> `&quot;` en el prompt, esta es la razón. El filtro `| safe` lo desactiva para una expresión concreta.
+
+## `artifact` puro: cuando no necesitas plantilla
+
+Si lo que quieres es "toma el manifiesto entero y audítalo", no escribas plantilla: pon `promptType` en
+`artifact`, deja el prompt vacío y mete toda la instrucción en el `system`. El prompt será el objeto
+serializado completo.
+
+Es más robusto que una plantilla —no se te olvida ningún campo, y funciona igual para cualquier kind— a
+cambio de gastar más tokens de entrada.
+
+## Escribir un buen `system`
+
+El `system` es donde de verdad se decide la calidad del análisis. Cuatro cosas que funcionan:
+
+**1. Dale un rol y un marco de referencia concreto.**
+
+```
+Eres un auditor de seguridad de Kubernetes. Evalúas recursos contra los Pod Security
+Standards (baseline y restricted) y contra el CIS Kubernetes Benchmark.
+```
+
+**2. Exige evidencia, y prohíbe explícitamente inventar.**
+
+```
+Cada finding debe citar en `evidence` el fragmento literal del manifiesto que lo demuestra.
+Si no puedes citar evidencia, NO emitas el finding: añádelo a `not_visible` en su lugar.
+```
+
+Esta instrucción es la que más reduce las alucinaciones. `not_visible` existe justo para darle al modelo una
+salida honesta cuando no sabe algo.
+
+**3. Dile qué hacer con las tools, no sólo que las tiene.**
+
+```
+Antes de concluir, usa `get_object_events` para comprobar si el recurso ya está fallando,
+y `get_workload_config_refs` para ver qué ConfigMaps y Secrets consume.
+```
+
+Un modelo con tools y sin instrucciones sobre cuándo usarlas tiende a no usarlas, o a usarlas todas.
+
+**4. Calibra la severidad, o te llegará todo como `critical`.**
+
+```
+critical = explotable ahora mismo para escapar del contenedor o acceder a datos de otros tenants.
+high     = incumple `restricted` y amplía la superficie de ataque de forma significativa.
+medium   = mala práctica con impacto acotado.
+low      = higiene, sin impacto directo de seguridad.
+```
+
+## Un system completo, listo para copiar
+
+```
+Eres un auditor de seguridad de Kubernetes. Analizas un único recurso y devuelves un
+informe estructurado.
+
+REGLAS
+- Evalúa contra los Pod Security Standards (baseline y restricted).
+- Cada finding DEBE citar en `evidence` el fragmento literal del manifiesto que lo prueba.
+- Si no puedes probar algo con evidencia, no lo afirmes: añádelo a `not_visible`.
+- Lista en `controls_passed` los controles que el recurso SÍ cumple.
+- Sé específico en `remediation`: el fragmento de YAML corregido, no un consejo genérico.
+
+SEVERIDAD
+- critical: explotable ahora para escapar del contenedor o alcanzar otros tenants.
+- high: incumple `restricted` y amplía la superficie de ataque de forma significativa.
+- medium: mala práctica con impacto acotado.
+- low: higiene, sin impacto directo.
+
+INFORME
+En `report`, redacta en markdown un resumen para el equipo propietario del recurso:
+qué es, qué riesgo tiene, qué hacer primero. Español, tono directo, sin relleno.
+```
+
+## Probar antes de activar
+
+No afines prompts en producción. El [Playground](../user/06-playground.md) ejecuta la misma tubería contra un
+payload pegado a mano y te enseña, en la pestaña **IN**, el prompt **ya renderizado** que recibió el modelo.
+Es la forma más rápida de descubrir que `{{ spec.containers }}` estaba vacío porque el kind era un
+`Deployment`.
+
+Recuerda las dos diferencias del Playground al probar plantillas: en modo Business el **payload es el
+prompt**, y en modo Artifact el `promptType` se deriva de si el campo Prompt está vacío o no.

package/admin/05-rbac.md

@@ -0,0 +1,89 @@
+# Permisos y acceso
+
+## Los scopes del canal
+
+Pinocchio declara al core sólo **dos** scopes válidos para su canal, en este orden de menor a mayor:
+
+| Scope | Nivel | Significado |
+|-------|-------|-------------|
+| `none` | 1 | Nivel mínimo. Suficiente para abrir el canal. |
+| `cluster` | 2 | Nivel de administración. Cubre todo lo anterior. |
+
+Una clave de acceso concede permiso sobre el canal `pinocchio` con uno de esos dos valores. El canal pide
+como scope de instancia `NONE`, así que **cualquiera de los dos basta para abrirlo y usarlo entero**.
+
+Cualquier otro literal en el scope (`view`, `restart`, `filter`, …) es **inválido para este canal**: el core
+lo rechaza con un aviso muy visible en el log de autorización:
+
+```
+***************** Inexistent scope 'view' on channel 'pinocchio' *****************
+```
+
+Si un usuario no consigue abrir el canal, ese log es el primer sitio donde mirar.
+
+## Lo que hay que entender antes de repartir claves
+
+Pinocchio **no tiene permisos granulares**. No hay un scope para "sólo leer los findings" y otro para
+"editar triggers". Quien puede abrir el canal, puede hacerlo todo. Esto es lo que "todo" incluye:
+
+**1. Leer los análisis de todos los demás.** Los análisis se guardan en el canal, no por usuario. Cualquiera
+que abra el canal recibe de golpe los últimos 50, con los manifiestos y los findings que contengan. Si un
+trigger analiza recursos de un namespace sensible, esos datos son visibles para todos los que tengan acceso
+al canal.
+
+**2. Borrar los análisis de todos los demás.** El botón **Clear back** vacía la memoria del canal para todo
+el mundo, sin confirmación adicional más allá del propio diálogo.
+
+**3. Editar la configuración de IA compartida.** Los diálogos *Provider* y *LLM* escriben en el almacén
+**común** de kwirth. Un usuario de Pinocchio puede añadir, modificar o **borrar** los providers y modelos que
+usan los demás plugins de IA del clúster.
+
+**4. Ver y cambiar las API keys.** El diálogo de provider tiene un botón de ojo que revela la clave, y un
+botón **Export** que descarga todos los providers **con las claves en claro**.
+
+**5. Crear triggers que ejecutan acciones de escritura.** Ver el apartado siguiente.
+
+> **Conclusión operativa: trata el acceso al canal `pinocchio` como un permiso de administración.** No es un
+> visor de logs. Concédelo al equipo que gobierna la plataforma, no a los usuarios de aplicación.
+
+## Las tools de escritura y el service account del backend
+
+Este es el punto que más atención merece.
+
+El catálogo de tools incluye acciones que **modifican el clúster**: `add_replica`, `remove_replica`,
+`restart_deployment`, `delete_pod`, `add_node`, `remove_node`, `start_node`, `stop_node`. Pinocchio **no
+filtra las tools de escritura**: si una versión de trigger las tiene marcadas —o tiene el interruptor
+**`Auto`** activado, que entrega el catálogo entero— el modelo puede invocarlas.
+
+Y cuando las invoca, se ejecutan con el **service account del backend de kwirth**, no con los permisos del
+usuario que configuró el trigger. Un usuario con el scope mínimo puede, a través de un trigger, provocar
+acciones que su propio nivel de acceso no le permitiría hacer directamente.
+
+Tres medidas concretas:
+
+1. **Prohíbe `Auto` en triggers** como norma de equipo. Que las tools se marquen a mano, una a una.
+2. **Revisa los triggers como revisarías código.** El diálogo *Import / Export* permite volcarlos a JSON:
+   ese fichero se puede versionar y revisar en un pull request.
+3. **Ajusta el RBAC del service account del backend** a lo que de verdad necesites. Si en tu instalación
+   Pinocchio sólo tiene que auditar, el backend no debería poder escalar deployments ni borrar pods. Ésa es
+   la barrera que de verdad detiene el problema, y está fuera del plugin: es el RBAC de kwirth en el clúster.
+
+## Auditoría
+
+Todas las invocaciones de tools quedan como trazas en el log del backend:
+
+```
+[pinocchio] tool get_pod_logs {"namespace":"prod","name":"api-gateway-7d9f"}
+[pinocchio] tool get_pod_logs response: {...}
+```
+
+Además, cada análisis muestra en su cabecera qué LLM lo produjo y cuántos tokens costó, y la traza completa
+de la conversación con las tools es visible en las pestañas **IN**/**OUT** del Playground cuando se ejecuta
+desde allí.
+
+## Superficie de red
+
+El Playground dispara sus eventos con un `POST {clusterUrl}/provider/business`, autenticado con la clave de
+acceso del usuario. Es el mismo endpoint por el que los sistemas externos inyectan eventos de negocio: quien
+tenga una clave válida para ese provider puede inyectar eventos y, por tanto, disparar los triggers
+`business`. Ténlo en cuenta al repartir claves con acceso al provider `business`.