@kwirthmagnify/kwirth-docs-pinocchio 0.2.31

package/kwirth-dark.css

@@ -0,0 +1,458 @@
+/* Kwirth Dark Theme for Docsify — matches homepage style */
+
+:root {
+  --theme-color: #f5820a;
+  --bg:      #060a12;
+  --bg2:     #0d1420;
+  --bg3:     #111827;
+  --card:    #0f1929;
+  --border:  #1e2d40;
+  --orange:  #f5820a;
+  --orange2: #ff9a2e;
+  --teal:    #2dd4bf;
+  --blue:    #58a6ff;
+  --green:   #3fb950;
+  --yellow:  #e3b341;
+  --red:     #ff7b72;
+  --text:    #e6edf3;
+  --muted:   #8b949e;
+  --font:    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --mono:    'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
+}
+
+/* ── Base ─────────────────────────────────────────────────────── */
+
+body {
+  background: var(--bg) !important;
+  color: var(--text);
+  font-family: var(--font);
+}
+
+/* ── Sidebar ──────────────────────────────────────────────────── */
+
+.sidebar {
+  background: var(--bg2) !important;
+  border-right: 1px solid var(--border) !important;
+  color: var(--text);
+}
+
+.sidebar > h1 {
+  color: var(--orange) !important;
+  font-weight: 700;
+  letter-spacing: -0.3px;
+}
+
+.sidebar > h1 a {
+  color: var(--orange) !important;
+}
+
+.sidebar ul {
+  padding: 0 12px;
+}
+
+.sidebar ul li {
+  list-style: none;
+}
+
+.sidebar ul li a {
+  color: var(--muted) !important;
+  font-size: 0.875rem;
+  padding: 5px 10px;
+  border-radius: 6px;
+  display: block;
+  transition: all 0.2s;
+  text-decoration: none;
+}
+
+.sidebar ul li a:hover,
+.sidebar ul li a.active {
+  color: var(--orange) !important;
+  background: rgba(245, 130, 10, 0.08) !important;
+}
+
+.sidebar ul li ul li a {
+  color: var(--muted) !important;
+  padding-left: 20px;
+}
+
+.sidebar ul li ul li a:hover,
+.sidebar ul li ul li a.active {
+  color: var(--orange) !important;
+  background: rgba(245, 130, 10, 0.08) !important;
+}
+
+.sidebar-toggle {
+  background: var(--bg2) !important;
+  border-right: 1px solid var(--border) !important;
+}
+
+.sidebar-toggle span {
+  background-color: var(--muted) !important;
+}
+
+/* ── App Nav ──────────────────────────────────────────────────── */
+
+nav.app-nav {
+  background: rgba(6, 10, 18, 0.92) !important;
+  backdrop-filter: blur(12px);
+  border-bottom: 1px solid var(--border) !important;
+}
+
+nav.app-nav a {
+  color: var(--muted) !important;
+  font-size: 0.875rem;
+  padding: 6px 12px;
+  border-radius: 6px;
+  transition: all 0.2s;
+  text-decoration: none;
+}
+
+nav.app-nav a:hover {
+  color: var(--text) !important;
+  background: var(--border) !important;
+}
+
+/* ── Content / Markdown ───────────────────────────────────────── */
+
+.content {
+  background: var(--bg) !important;
+}
+
+.markdown-section {
+  color: var(--text) !important;
+  max-width: 860px;
+}
+
+.markdown-section h1 {
+  color: var(--orange) !important;
+  font-weight: 800;
+  letter-spacing: -0.5px;
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 14px;
+}
+
+.markdown-section h2 {
+  color: var(--text) !important;
+  font-weight: 700;
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 10px;
+  letter-spacing: -0.3px;
+}
+
+.markdown-section h3,
+.markdown-section h4,
+.markdown-section h5,
+.markdown-section h6 {
+  color: var(--text) !important;
+  font-weight: 600;
+}
+
+.markdown-section a {
+  color: var(--orange) !important;
+  text-decoration: none;
+  transition: color 0.2s;
+}
+
+.markdown-section a:hover {
+  color: var(--orange2) !important;
+  text-decoration: underline;
+}
+
+.markdown-section strong {
+  color: var(--text);
+}
+
+.markdown-section em {
+  color: var(--muted);
+}
+
+.markdown-section hr {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 32px 0;
+}
+
+/* ── Code Blocks ─────────────────────────────────────────────── */
+
+.markdown-section code {
+  background: var(--bg3) !important;
+  color: var(--teal) !important;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-family: var(--mono);
+  font-size: 0.875em;
+  border: 1px solid var(--border);
+}
+
+.markdown-section pre {
+  background: var(--bg2) !important;
+  border: 1px solid var(--border) !important;
+  border-radius: 10px !important;
+  padding: 20px 24px !important;
+}
+
+.markdown-section pre code {
+  background: transparent !important;
+  border: none !important;
+  color: var(--text) !important;
+  padding: 0 !important;
+  font-size: 0.875rem;
+  line-height: 1.7;
+}
+
+/* ── Blockquotes ─────────────────────────────────────────────── */
+
+.markdown-section blockquote {
+  border-left: 4px solid var(--orange) !important;
+  background: rgba(245, 130, 10, 0.05) !important;
+  color: var(--muted) !important;
+  padding: 14px 20px;
+  border-radius: 0 8px 8px 0;
+  margin: 20px 0;
+}
+
+.markdown-section blockquote p {
+  color: var(--muted) !important;
+}
+
+/* ── Tables ──────────────────────────────────────────────────── */
+
+.markdown-section table {
+  display: table;
+  border-collapse: collapse;
+  width: auto;
+  max-width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.markdown-section table th {
+  background: var(--card) !important;
+  color: var(--text) !important;
+  border: 1px solid var(--border) !important;
+  font-weight: 700;
+  text-align: left;
+  padding: 12px 16px;
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.markdown-section table td {
+  border: 1px solid var(--border) !important;
+  padding: 10px 16px;
+  color: var(--text) !important;
+  font-size: 0.9rem;
+}
+
+.markdown-section table tr {
+  background: var(--bg) !important;
+}
+
+.markdown-section table tr:nth-child(2n) {
+  background: var(--bg2) !important;
+}
+
+.markdown-section table tr:hover {
+  background: var(--card) !important;
+}
+
+/* ── Docsify callouts (!> warn, ?> tip) ──────────────────────── */
+
+.markdown-section .warn,
+.markdown-section .warning,
+.markdown-section blockquote.warn,
+.markdown-section blockquote.warning {
+  background: rgba(245, 130, 10, 0.08) !important;
+  border-left: 4px solid var(--orange) !important;
+  border-radius: 0 8px 8px 0;
+  padding: 14px 20px !important;
+  margin: 20px 0 !important;
+  color: var(--text) !important;
+}
+
+.markdown-section .warn p,
+.markdown-section .warning p {
+  color: var(--text) !important;
+  margin: 0;
+}
+
+.markdown-section .tip,
+.markdown-section blockquote.tip {
+  background: rgba(45, 212, 191, 0.08) !important;
+  border-left: 4px solid var(--teal) !important;
+  border-radius: 0 8px 8px 0;
+  padding: 14px 20px !important;
+  margin: 20px 0 !important;
+  color: var(--text) !important;
+}
+
+.markdown-section .tip p {
+  color: var(--text) !important;
+  margin: 0;
+}
+
+/* ── Lists ───────────────────────────────────────────────────── */
+
+.markdown-section ul li::before {
+  color: var(--orange);
+}
+
+.markdown-section ol li {
+  color: var(--text);
+}
+
+/* ── Search ──────────────────────────────────────────────────── */
+
+.search {
+  border-bottom: 1px solid var(--border) !important;
+  padding: 10px 16px;
+}
+
+.search input {
+  background: var(--card) !important;
+  border: 1px solid var(--border) !important;
+  color: var(--text) !important;
+  border-radius: 6px !important;
+  padding: 8px 12px !important;
+  font-size: 0.875rem;
+  width: 100%;
+  outline: none !important;
+  box-shadow: none !important;
+  transition: border-color 0.2s;
+}
+
+.search input:focus {
+  border-color: var(--orange) !important;
+}
+
+.search input::placeholder {
+  color: var(--muted);
+}
+
+.search .clear-button svg {
+  stroke: var(--muted);
+}
+
+.search .results-panel {
+  background: var(--card) !important;
+  border: 1px solid var(--border) !important;
+  border-radius: 8px !important;
+}
+
+.search .matching-post {
+  border-bottom: 1px solid var(--border) !important;
+  padding: 12px 16px;
+}
+
+.search .matching-post a {
+  color: var(--orange) !important;
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.search .matching-post p {
+  color: var(--muted) !important;
+  font-size: 0.85rem;
+  margin: 4px 0 0;
+}
+
+/* ── Progress bar (NProgress) ────────────────────────────────── */
+
+#nprogress .bar {
+  background: var(--orange) !important;
+  height: 2px !important;
+}
+
+#nprogress .peg {
+  box-shadow: 0 0 10px var(--orange), 0 0 5px var(--orange) !important;
+}
+
+#nprogress .spinner-icon {
+  border-top-color: var(--orange) !important;
+  border-left-color: var(--orange) !important;
+}
+
+/* ── Scrollbar ───────────────────────────────────────────────── */
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--bg);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--orange);
+}
+
+/* ── Screenshots (guide uses plain markdown images) ──────────── */
+
+.markdown-section img {
+  display: block;
+  margin: 16px auto;
+  border: 1px solid var(--border) !important;
+  border-radius: 8px;
+  max-width: 100%;
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4);
+}
+
+/* ── Sidebar section headers (collapsible groups) ────────────── */
+
+/* The bold top-level items ("Using Excubitor", "Administering Excubitor")
+   render as <strong>; style them as clean section headers, not big links. */
+.sidebar-nav > ul > li > strong,
+.sidebar-nav > ul > li > p > strong {
+  display: block;
+  padding: 6px 10px 6px 24px;
+  margin-top: 6px;
+  color: var(--muted) !important;
+  font-size: 0.72rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+  cursor: pointer;
+}
+
+.sidebar-nav > ul > li > strong:hover,
+.sidebar-nav > ul > li > p > strong:hover {
+  color: var(--orange) !important;
+}
+
+/* child links a touch smaller and tighter under a section */
+.sidebar-nav > ul > li > ul > li > a {
+  font-size: 0.85rem;
+  padding: 4px 10px;
+}
+
+/* ── Collapsible sections (custom, driven by .has-children/.open) ─ */
+
+.sidebar-nav > ul > li.has-children > ul { display: none; }
+.sidebar-nav > ul > li.has-children.open > ul { display: block; }
+
+.sidebar-nav > ul > li.has-children > strong::before,
+.sidebar-nav > ul > li.has-children > p > strong::before {
+  content: '\203A';            /* › chevron */
+  display: inline-block;
+  width: 12px;
+  margin-left: -16px;
+  margin-right: 4px;
+  text-align: center;
+  font-size: 0.9rem;
+  color: var(--muted);
+  transition: transform 0.15s ease;
+}
+
+.sidebar-nav > ul > li.has-children.open > strong::before,
+.sidebar-nav > ul > li.has-children.open > p > strong::before {
+  transform: rotate(90deg);
+  color: var(--orange);
+}

package/package.json

@@ -0,0 +1,9 @@
+{
+  "extensionType": "docs",
+  "targetType": "plugin",
+  "id": "pinocchio",
+  "name": "@kwirthmagnify/kwirth-docs-pinocchio",
+  "displayName": "kwirth Pinocchio — Guide",
+  "version": "0.2.31",
+  "description": "User and administrator guide for the kwirth Pinocchio plugin"
+}

package/serve.cmd

@@ -0,0 +1 @@
+node serve.mjs 4000

package/serve.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import http from 'http'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dir = path.dirname(fileURLToPath(import.meta.url))
+
+// Usage: node serve.mjs [port] [path]  or  node serve.mjs [path] [port]
+// Accepts port (number) and path (string) in any order after the script name.
+let PORT = 4000
+let ROOT = __dir
+
+for (const arg of process.argv.slice(2)) {
+  const n = parseInt(arg, 10)
+  if (!isNaN(n) && String(n) === arg.trim()) {
+    PORT = n
+  } else {
+    ROOT = path.isAbsolute(arg) ? arg : path.resolve(__dir, arg)
+  }
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css':  'text/css',
+  '.js':   'text/javascript',
+  '.mjs':  'text/javascript',
+  '.json': 'application/json',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2':'font/woff2',
+  '.md':   'text/plain; charset=utf-8',
+}
+
+const server = http.createServer((req, res) => {
+  let urlPath = decodeURIComponent(req.url.split('?')[0])
+  if (urlPath === '/') urlPath = '/index.html'
+
+  let filePath = path.join(ROOT, urlPath)
+
+  // If no extension and no trailing slash, try .html then directory index
+  if (!path.extname(filePath)) {
+    if (fs.existsSync(filePath + '.html')) {
+      filePath = filePath + '.html'
+    } else if (fs.existsSync(path.join(filePath, 'index.html'))) {
+      filePath = path.join(filePath, 'index.html')
+    }
+  }
+
+  if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+    const idx = path.join(filePath.replace(/\/$/, ''), 'index.html')
+    if (fs.existsSync(idx)) {
+      filePath = idx
+    } else {
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end(`404 Not Found: ${urlPath}`)
+      return
+    }
+  }
+
+  const ext = path.extname(filePath).toLowerCase()
+  const mime = MIME[ext] || 'application/octet-stream'
+
+  try {
+    const data = fs.readFileSync(filePath)
+    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'no-cache' })
+    res.end(data)
+    console.log(`  200  ${urlPath}`)
+  } catch {
+    res.writeHead(500, { 'Content-Type': 'text/plain' })
+    res.end('500 Internal Server Error')
+  }
+})
+
+server.listen(PORT, () => {
+  console.log(`\n  pinocchio docs  →  http://localhost:${PORT}`)
+  console.log(`  serving        →  ${ROOT}\n`)
+  console.log('  Press Ctrl+C to stop.\n')
+})

package/user/00-how-it-works.md

@@ -0,0 +1,88 @@
+# Cómo funciona
+
+Pinocchio es un **canal** de kwirth. Cuando lo abres, el backend arranca una instancia del canal que se
+**suscribe a tres providers** y se queda escuchando. Cada evento que llega se compara con tus **triggers**;
+si encaja, se construye una llamada al LLM y el resultado vuelve a tu pantalla.
+
+## El bucle completo
+
+```
+   +---------------------+
+   |  events (k8s)       |--- ADDED / MODIFIED / DELETED de Pod, Deployment, ...
+   +---------------------+
+   |  business (HTTP)    |--- POST /provider/business  {space, type, data}
+   +---------------------+
+   |  metrics            |--- NO dispara nada: alimenta el contexto de las tools
+   +---------------------+
+              |
+              v
+   +---------------------+     ¿hay un trigger cuyo tipo, kind y evento
+   |  match de triggers  |     encajen? ¿tiene una version enabled?
+   +---------------------+
+              |  si
+              v
+   +---------------------+     system  = version.system
+   |  render del prompt  |     prompt  = nunjucks(version.prompt, objeto)
+   +---------------------+              o  JSON.stringify(objeto)
+              |
+              v
+   +---------------------+     el modelo puede llamar a tools (list_namespaces,
+   |  LLM + tools        |     get_pod_logs, get_rollout_history, ...) hasta
+   +---------------------+     agotar `steps`
+              |
+              v
+   +---------------------+     findings[] + resource + PSS + score_summary +
+   |  salida estructurada|     global_risk + next_steps + report
+   +---------------------+
+              |
+              v
+   +---------------------+
+   |  tu pestaña         |     y se guarda en el back (ultimos 50 analisis)
+   +---------------------+
+```
+
+## Los tres providers
+
+Al arrancar el canal, Pinocchio se suscribe a:
+
+| Provider   | Para qué lo usa                                                                  |
+|------------|----------------------------------------------------------------------------------|
+| `events`   | **Dispara** los triggers de tipo `artifact`. Escucha los kinds de la lista de abajo. |
+| `business` | **Dispara** los triggers de tipo `business`, y es también el canal por el que el Playground inyecta eventos. |
+| `metrics`  | **No dispara nada.** Se guarda un buffer de las últimas 100 lecturas que se pasa como contexto a las tools de uso (`get_cluster_usage`, `get_prev_node_usage`, …). |
+
+Los kinds que escucha el provider `events` están fijados en el plugin:
+
+`Pod`, `Deployment`, `DaemonSet`, `StatefulSet`, `ReplicaSet`, `Job`, `CronJob`,
+`ReplicationController`, `Service`, `Ingress`, `HTTPRoute`
+
+De la suscripción a `business`, el canal sólo pide tres pares espacio/tipo:
+`customers.status`, `branches.status` y `launch.immediate`. Esto importa y se explica en
+[El Playground](06-playground.md).
+
+## Qué NO se analiza al arrancar
+
+Cuando abres el canal, Kubernetes reemite como `ADDED` **todos** los objetos que ya existen. Si Pinocchio
+los analizase, una sola apertura del canal costaría cientos de llamadas al modelo.
+
+Para evitarlo, ante un `ADDED` el canal compara el `metadata.creationTimestamp` del objeto con la hora de
+arranque del canal: si el objeto es **anterior**, lo descarta y deja una traza de aviso en el log del
+backend. Sólo se analiza lo que nace **después** de que el canal esté escuchando.
+
+> Consecuencia práctica: si quieres analizar algo que ya existe, no te vale con abrir el canal. Recrea el
+> recurso, provoca un `MODIFIED`, o usa el [Playground](06-playground.md) pegando su YAML/JSON a mano.
+
+## Dónde vive el estado
+
+| Qué                          | Dónde                                                                |
+|------------------------------|----------------------------------------------------------------------|
+| Triggers y estado del Playground | Almacén del canal, clave `pinocchio-config`                       |
+| Providers de IA (con las API keys) | Almacén **común** de kwirth, `kwirth-ai-providers` (Secret)     |
+| LLMs                         | Almacén **común** de kwirth, `kwirth-ai-llms` (ConfigMap)             |
+| Análisis producidos          | Sólo en **memoria** del canal, los últimos 50                        |
+
+Los dos almacenes comunes los comparte Pinocchio con el resto de plugins de kwirth que usan IA: no son
+suyos. Ver [Providers y modelos de IA](../admin/02-ai-config.md).
+
+Los análisis **no se persisten**. Al reconectar, el back te reenvía de golpe los que tenga en memoria; si el
+backend se reinicia, se pierden.

package/user/01-introduction.md

@@ -0,0 +1,60 @@
+# Introducción y modelo mental
+
+## Qué problema resuelve
+
+Un clúster de Kubernetes acepta prácticamente cualquier cosa que le mandes. Un `Deployment` con
+`privileged: true`, sin `resources`, con `latest` como tag y montando el socket de Docker se despliega sin
+una sola queja. Los controles que lo evitarían —Pod Security Standards, políticas de admisión, un repaso
+manual del YAML— o no están, o están en modo aviso, o nadie los lee.
+
+Pinocchio ataca ese hueco por otro lado: **pone un modelo de lenguaje a leer cada recurso que nace o cambia**,
+con las instrucciones que tú le has escrito, y con capacidad de **consultar el clúster** para contrastar lo
+que ve.
+
+## El modelo mental en una frase
+
+> Un **trigger** es una regla del tipo *"cuando pase ESTO, pregúntale ESTO al modelo, dándole ESTAS
+> herramientas"*.
+
+Todo lo demás en Pinocchio existe para servir a esa frase:
+
+- **Cuando pase ESTO** → el tipo de trigger (`artifact` o `business`), el `kind` y el evento de Kubernetes.
+- **Pregúntale ESTO** → el *system* y el *prompt*, que es una plantilla jinja sobre el objeto que llegó.
+- **Con ESTAS herramientas** → las *tools*, funciones reales que consultan el clúster, y los *steps*, cuántas
+  veces puede encadenarlas antes de tener que responder.
+
+## En qué se parece y en qué no a un chat de IA
+
+|                       | Chat de IA                             | Pinocchio                                              |
+|-----------------------|----------------------------------------|--------------------------------------------------------|
+| Quién inicia          | Tú, escribiendo                        | Un evento del clúster o de negocio                      |
+| Qué ve el modelo      | Lo que pegues en la ventana            | El objeto real + lo que consulte con sus tools          |
+| Formato de salida     | Texto libre                            | JSON estructurado: findings, PSS, riesgo, informe       |
+| Cuándo ocurre         | Cuando te acuerdas                     | Siempre, mientras el canal esté abierto                 |
+
+La tercera fila es la que más cambia el resultado. Pinocchio no le pide al modelo "dime qué te parece":
+le **impone un esquema de respuesta** con findings clasificados por severidad, categoría y confianza, un
+nivel PSS actual y objetivo, un recuento por severidad y un informe en markdown. El modelo tiene que
+rellenar esos campos, y por eso la salida se puede pintar, ordenar y comparar en vez de leerse a mano.
+
+## Los dos tipos de trigger
+
+**`artifact`** — el evento es un **objeto de Kubernetes**. Es el caso principal y el único que produce la
+salida estructurada completa (findings, PSS, informe). Ejemplo: *"cada vez que se cree un Deployment,
+audítalo contra los Pod Security Standards"*.
+
+**`business`** — el evento es un **JSON arbitrario** que un sistema externo ha enviado por HTTP al provider
+`business`. La salida es sólo un texto de respuesta. Ejemplo: *"cuando llegue un aviso de pico de pedidos,
+mira las métricas del clúster y dime si aguantamos"*.
+
+Los dos se configuran en el mismo diálogo y se prueban en el mismo Playground, pero se comportan de forma
+bastante distinta. La diferencia está detallada en [Triggers, versiones y prompts](03-concepts.md).
+
+## Qué NO es Pinocchio
+
+- **No es un escáner de vulnerabilidades.** No mira CVEs de las imágenes. Para eso está el provider `trivy`.
+- **No bloquea nada.** Los triggers tienen un campo *Action* con valores `inform`/`cancel`/`repair`, pero
+  hoy sólo se comporta como `inform`: analiza y te lo cuenta. Ver [Límites conocidos](../admin/06-limits.md).
+- **No recuerda.** Cada análisis es una llamada independiente. El modelo no ve los análisis anteriores.
+- **No es gratis.** Cada disparo es una llamada de pago a tu proveedor de IA, y con tools activadas puede
+  ser una cadena de varias. Ver [Tools y pasos del agente](../admin/03-tools.md).