@kwirthmagnify/kwirth-docs-pinocchio 0.2.31

package/admin/06-limits.md

@@ -0,0 +1,113 @@
+# Límites conocidos
+
+Lista honesta de lo que Pinocchio **no** hace, o hace de forma distinta a la que su UI sugiere. Todo lo de
+esta página está verificado contra el código del plugin, no supuesto. Si algo te está pasando y aparece
+aquí, no es tu configuración.
+
+## Configuración de IA
+
+**La config de IA sólo se lee al arrancar el canal.** Los providers y los LLMs se cargan del almacén común en
+el arranque de la instancia. 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 reabra.
+*Workaround:* configúralo desde el propio menú **Config** de Pinocchio, que sí notifica al canal, o reabre el
+canal.
+
+**La config de IA no viaja entre clústeres.** Los menús *AI Providers* / *AI Models* del core escriben en el
+backend **local**, pero un canal abierto contra otro kwirth lee el almacén de **ese** clúster. En una
+federación hay que configurar providers y LLMs en cada clúster.
+
+**Las opciones de salida estructurada se eligen por el `Name` del provider, no por su `Type`.** El modelo se
+construye bien (por tipo), pero los `providerOptions` (`structuredOutputs`, `strictJsonSchema`) se deciden con
+un `switch` sobre el nombre. Un provider de tipo `google` llamado `gemini-prod` pierde el
+`structuredOutputs: true` y sus triggers `artifact` pueden empezar a fallar.
+*Workaround:* deja el `Name` del provider igual que su `Type`.
+
+## Triggers
+
+**El campo `Action` no está implementado.** El selector ofrece `inform`, `cancel` y `repair`, y el valor se
+guarda en la configuración, pero el backend **nunca lo lee**. Todo se comporta como `inform`: se analiza y se
+informa. Pinocchio no bloquea ni repara nada.
+
+**El campo `Spaces` no filtra nada.** En un trigger `business` puedes escribir `orders.created`, pero el
+matching no lo usa: **todos** los triggers `business` con una versión activa se disparan con **cualquier**
+evento de negocio que llegue al canal. El único filtrado real es el de la suscripción del canal, que está
+fijada en el código a `customers.status`, `branches.status` y `launch.immediate`.
+
+**Los prompts `business` se renderizan con contexto vacío.** El backend calcula un objeto con los datos de los
+espacios declarados… y luego llama a `nunjucks.renderString(prompt, {})`. Los datos del evento **no llegan a
+la plantilla**: cualquier `{{ variable }}` sale como cadena vacía.
+
+**Los triggers `business` ignoran el `system` de la versión.** El backend usa un system fijo
+(*"Use the tools provided to find information…"*). El `system` que escribas en el editor se guarda pero no se
+envía al modelo.
+
+## Playground
+
+**`Export → New trigger` pierde el `Kind` y el `K8s Event`.** El trigger nuevo se crea con el tipo y la
+versión, pero sin `kind` ni `k8sEvent`. Un trigger `artifact` recién exportado **no casa con ningún evento**.
+*Workaround:* abre **Config → Trigger** justo después y ponle el kind a mano.
+
+**El selector `K8s Event` del Playground no hace nada.** El objeto que inyectas siempre se le entrega al
+modelo como un evento `ADDED`. El valor se guarda con el estado del Playground, pero no cambia la simulación.
+
+**En modo Artifact, el `Prompt type` que elijas no siempre manda.** El backend lo deriva de si el campo Prompt
+tiene texto: con prompt, `jinja`; vacío, `artifact`.
+*Workaround:* para probar `artifact` puro, vacía el campo Prompt.
+
+**En modo Business, el payload es el prompt.** El backend descarta el campo `Prompt` y usa el contenido del
+textarea de evento como prompt.
+
+**En modo Business, cambiar `Space`/`Type` desvía el disparo.** Sólo un evento con `launch`/`immediate` se
+redirige al Playground. Con otros valores, el evento pasa a evaluarse contra los triggers de negocio
+**reales**, y si además el par no es uno de los tres a los que el canal está suscrito, no llega a ninguna
+parte y no verás nada.
+
+**El Playground nunca produce findings.** Usa `generateText` sin esquema de salida: devuelve texto libre. El
+formato estructurado sólo aparece cuando el trigger se dispara de verdad.
+
+## Salida y persistencia
+
+**`hardened_yaml` se genera pero no se ve.** El esquema de salida pide al modelo un manifiesto endurecido, el
+backend lo guarda en el análisis… y **ninguna pantalla lo muestra**. Se paga en tokens y no se aprovecha.
+*Workaround parcial:* pide en el `system` que el YAML corregido vaya también dentro del `report`, que sí se
+renderiza.
+
+**Los análisis no se persisten.** Viven en memoria del canal, con un tope de **50**; a partir de ahí se
+descarta el más antiguo. Un reinicio del backend los pierde todos. Si necesitas conservar un hallazgo,
+expórtalo tú (copia el informe).
+
+**El buffer de métricas es de 100 lecturas.** Las tools de histórico (`get_prev_*`) no pueden mirar más atrás
+de eso, y arrancan vacías al abrir el canal.
+
+## Alcance y seguridad
+
+**No hay filtro de sólo-lectura en las tools.** El interruptor `Auto` de un trigger entrega el catálogo
+**completo**, incluidas `delete_pod`, `restart_deployment`, `add_node`, `remove_node` y el escalado. Se
+ejecutan con el service account del backend, no con los permisos del usuario. Ver
+[Permisos y acceso](05-rbac.md).
+
+**No hay permisos granulares.** El canal sólo admite los scopes `none` y `cluster`, y cualquiera de los dos
+da acceso completo: leer y borrar los análisis de todos, y editar los providers de IA compartidos, claves
+incluidas.
+
+**Los objetos preexistentes no se analizan.** Ante un `ADDED`, si el `creationTimestamp` del objeto es
+anterior al arranque del canal, se descarta. Es intencionado —evita analizar el clúster entero cada vez que
+alguien abre el canal— pero significa que no puedes auditar lo que ya existe sin recrearlo o pasarlo por el
+Playground.
+
+**Los kinds vigilados están fijados en el código.** `Pod`, `Deployment`, `DaemonSet`, `StatefulSet`,
+`ReplicaSet`, `Job`, `CronJob`, `ReplicationController`, `Service`, `Ingress`, `HTTPRoute`. No hay CRDs y no
+es configurable desde la UI.
+
+## Cosméticos
+
+**`medium` se pinta en verde.** El código de colores es `critical`=rojo, `high`=naranja, `medium`=verde,
+`low`=gris. Guíate por el texto de la etiqueta.
+
+**El formateo de la descripción de un finding es mínimo.** Un fragmento entre ` **` y `** ` se pinta en
+negrita y subrayado, y sólo el primero de la cadena. No es markdown. El markdown de verdad está en el
+**Report**.
+
+---
+
+El backlog de desarrollo con el estado de estos puntos está en `plans/pinocchio/PLAN.md`.

package/index.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Pinocchio — Guide</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Pinocchio — user & administration guide">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="../../docsify/vue.css">
+  <link rel="stylesheet" href="kwirth-dark.css">
+  <style>
+    .sidebar { width: 320px; }
+    .content { left: 320px; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    // Colapsable de secciones propio (sin plugin): togglea con el chevron, abre por defecto,
+    // mantiene abierta la seccion de la pagina activa y NO se contrae al navegar.
+    var sectionState = {}
+    window.$docsify = {
+      homepage: 'index.md',
+      relativePath: false,
+      loadSidebar: true,
+      auto2top: true,
+      name: 'Pinocchio',
+      subMaxLevel: 0,
+      search: {
+        paths: 'auto',
+        placeholder: 'Search...',
+        noData: 'No results',
+        depth: 4
+      },
+      plugins: [
+        function (hook) {
+          hook.doneEach(function () {
+            var secs = document.querySelectorAll('.sidebar-nav > ul > li')
+            secs.forEach(function (li) {
+              var sub = li.querySelector(':scope > ul')
+              var head = li.querySelector(':scope > strong, :scope > p > strong')
+              if (!sub || !head) return
+              li.classList.add('has-children')
+              var key = head.textContent.trim()
+              if (sectionState[key] === undefined) sectionState[key] = true   // abierto por defecto
+              var active = !!li.querySelector('a.active')
+              li.classList.toggle('open', sectionState[key] || active)        // la activa siempre abierta
+              head.style.cursor = 'pointer'
+              head.onclick = function (e) {
+                e.preventDefault(); e.stopPropagation()
+                sectionState[key] = !li.classList.contains('open')
+                li.classList.toggle('open', sectionState[key])
+              }
+            })
+          })
+        }
+      ]
+    }
+  </script>
+  <script src="../../docsify/docsify.min.js"></script>
+  <script src="../../docsify/search.min.js"></script>
+  <script src="../../docsify/docsify-copy-code.min.js"></script>
+</body>
+</html>

package/index.md

@@ -0,0 +1,42 @@
+# Pinocchio — análisis agéntico de tu clúster
+
+**Pinocchio** es un plugin de kwirth que pone un **LLM a mirar lo que pasa en tu clúster**. No es un chat:
+es un canal que **escucha eventos** —altas y cambios de recursos de Kubernetes, o eventos de negocio que le
+manda un sistema externo— y, cuando uno encaja con un **trigger** que tú has definido, invoca al modelo con
+tu prompt y tus *tools*, y devuelve **findings** estructurados y un **informe**.
+
+La diferencia con "pegar un YAML en un chat" es que Pinocchio **vive dentro del clúster**: el modelo puede
+llamar a herramientas que consultan namespaces, workloads, métricas, logs, eventos, ConfigMaps o el
+histórico de rollouts. Analiza el recurso *y su contexto real*, no un fragmento fuera de sitio.
+
+![El editor de triggers: cuándo se dispara, qué se le pregunta al modelo y con qué herramientas](images/triggers-dialog.png)
+
+## Qué encontrarás en esta guía
+
+**Guía de usuario** — entender, configurar y explotar el canal:
+
+- [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)
+- [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** — instalar, conectar el LLM y gobernar el acceso:
+
+- [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)
+
+## Empieza aquí
+
+1. Lee [Cómo funciona](user/00-how-it-works.md) para tener el bucle completo en la cabeza: evento → trigger →
+   prompt → modelo (+ tools) → findings.
+2. Pide a tu administrador que configure un **provider** y un **LLM** ([Providers y modelos](admin/02-ai-config.md)).
+   Sin eso el menú *Config* no te deja crear triggers.
+3. Abre el **Playground** ([El Playground](user/06-playground.md)) y afina un prompt contra un artefacto de
+   ejemplo, **sin tocar producción**.
+4. Cuando funcione, expórtalo a un trigger real desde el propio Playground y actívalo.
+
+> ⚠️ Pinocchio **gasta tokens de tu proveedor de IA**. Un trigger sobre `Pod`/`MODIFIED` en un clúster vivo
+> puede dispararse cientos de veces al día. Lee [Tools y pasos del agente](admin/03-tools.md) antes de
+> activar nada en un entorno grande.