frida-pi-studio 0.6.1

package/packages/studio/extensions/branding.ts

@@ -0,0 +1,153 @@
+/**
+ * FRIDA-STUDIO branding — reemplaza el header nativo de pi (logo +
+ * hints) por el banner FRIDA-STUDIO. API oficial: ctx.ui.setHeader().
+ *
+ * ⚠️ El arte NO se edita a mano — se regenera y verifica con:
+ *   npx figlet -f "ANSI Shadow" -w 140 "FRIDA-STUDIO"
+ * (lección SOSIP4: dibujado a mano salió "SOSIP4"; y re-sucia si el
+ * bloque se re-escribe entero — editar SIN tocar LOGO).
+ * KIT_VERSION la sincroniza scripts/sync-kit.mjs desde package.json.
+ *
+ * Banner responsivo (#26): render(width) adapta — ancho completo
+ * muestra el arte; terminal estrecha recibe banner compacto que
+ * AVISA (nunca se rompe en silencio ni se trunca el arte).
+ * /frida (#25): panel de identidad del kit (versión, theme, modelo).
+ * Banner personalizable (#31): ${PI_CODING_AGENT_DIR:-~/.pi/agent}/
+ * frida/banner.txt del usuario reemplaza el arte (subtítulo y hints
+ * se conservan); el arte default sigue verificado con figlet.
+ */
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+
+export const KIT_VERSION = "0.6.0";
+
+const LOGO = [
+  "███████╗██████╗ ██╗██████╗  █████╗       ███████╗████████╗██╗   ██╗██████╗ ██╗ ██████╗ ",
+  "██╔════╝██╔══██╗██║██╔══██╗██╔══██╗      ██╔════╝╚══██╔══╝██║   ██║██╔══██╗██║██╔═══██╗",
+  "█████╗  ██████╔╝██║██║  ██║███████║█████╗███████╗   ██║   ██║   ██║██║  ██║██║██║   ██║",
+  "██╔══╝  ██╔══██╗██║██║  ██║██╔══██║╚════╝╚════██║   ██║   ██║   ██║██║  ██║██║██║   ██║",
+  "██║     ██║  ██║██║██████╔╝██║  ██║      ███████║   ██║   ╚██████╔╝██████╔╝██║╚██████╔╝",
+  "╚═╝     ╚═╝  ╚═╝╚═╝╚═════╝ ╚═╝  ╚═╝      ╚══════╝   ╚═╝    ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ",
+];
+
+const HINTS =
+  "   / comandos · ! bash · Ctrl+P modelos · Ctrl+T thinking · ? ayuda de pi";
+
+// #31: banner del usuario (cacheado por sesión). null = usar LOGO.
+let bannerCache: string[] | null | undefined;
+function userBanner(): string[] | null {
+  if (bannerCache !== undefined) return bannerCache;
+  const dir =
+    process.env.PI_CODING_AGENT_DIR ?? join(os.homedir(), ".pi", "agent");
+  try {
+    const txt = readFileSync(join(dir, "frida", "banner.txt"), "utf8");
+    const lines = txt.split("\n").filter((l) => l.trim().length > 0);
+    bannerCache = lines.length > 0 ? lines : null;
+  } catch {
+    bannerCache = null;
+  }
+  return bannerCache;
+}
+
+function setFridaHeader(
+  ctx: { ui: { setHeader: Function } },
+  subtitle: string,
+): void {
+  ctx.ui.setHeader((_tui: unknown, theme: Theme) => ({
+    render(width: number): string[] {
+      const banner = userBanner() ?? LOGO;
+      const need = Math.max(...banner.map((l) => l.length));
+      if (width >= need) {
+        // Layout completo: arte (default verificado o banner del
+        // usuario) + subtítulo + hints.
+        const art = banner.map((line) => theme.fg("accent", line));
+        const hints = theme.fg("dim", HINTS);
+        return [...art, subtitle, hints];
+      }
+      // Terminal estrecha: banner compacto que AVISA (patrón pi-kaush —
+      // degradar honestamente; el arte jamás se trunca ni se edita).
+      const compact = theme.fg("accent", `FRIDA-STUDIO v${KIT_VERSION}`);
+      const note = theme.fg(
+        "dim",
+        `arte completo requiere ${need} columnas (terminal: ${width}) — /frida identidad del kit`,
+      );
+      return [compact, note];
+    },
+    invalidate() {},
+  }));
+}
+
+function activeThemeName(): string {
+  const candidates = [
+    join(os.homedir(), ".pi", "agent", "settings.json"),
+    join(process.cwd(), ".pi", "settings.json"),
+  ];
+  for (const p of candidates) {
+    try {
+      const theme = JSON.parse(readFileSync(p, "utf8")).theme;
+      if (typeof theme === "string" && theme) return theme;
+    } catch {
+      /* sin settings o ilegible — probar siguiente */
+    }
+  }
+  return "default de pi";
+}
+
+function fridaPanel(ctx: Record<string, unknown>, theme?: Theme): string[] {
+  const dim = (s: string) => (theme ? theme.fg("dim", s) : s);
+  const accent = (s: string) => (theme ? theme.fg("accent", s) : s);
+  const model =
+    typeof ctx.model === "string"
+      ? ctx.model
+      : (ctx.model as { id?: string } | undefined)?.id;
+  return [
+    accent(`FRIDA-STUDIO v${KIT_VERSION} — identidad del kit`),
+    dim(`theme activo: ${activeThemeName()}`),
+    dim(`modelo: ${model ?? "(no disponible aún)"}`),
+    dim("footer: FRIDA footer con marca y telemetría (extensión propia)"),
+    dim("actualizar: pi update --extensions · docs: docs/feature-catalog.md"),
+    dim("(/frida de nuevo para refrescar)"),
+  ];
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    const subtitle =
+      (ctx as { theme?: Theme }).theme?.fg("muted", "   FRIDA STUDIO") ??
+      "   FRIDA STUDIO";
+    setFridaHeader(ctx as never, `${subtitle} v${KIT_VERSION} · powered by pi`);
+  });
+
+  pi.registerCommand("header-frida", {
+    description: "Restaurar el header FRIDA-STUDIO",
+    handler: async (_args, ctx) => {
+      setFridaHeader(
+        ctx as never,
+        `   FRIDA STUDIO v${KIT_VERSION} · powered by pi`,
+      );
+      ctx.ui.notify("Header FRIDA-STUDIO restaurado", "info");
+    },
+  });
+
+  pi.registerCommand("header-pi", {
+    description: "Restaurar el header nativo de pi",
+    handler: async (_args, ctx) => {
+      ctx.ui.setHeader(undefined);
+      ctx.ui.notify("Header nativo de pi restaurado", "info");
+    },
+  });
+
+  pi.registerCommand("frida", {
+    description: "Identidad del kit: versión, theme, modelo y cómo actualizar",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      ctx.ui.setWidget(
+        "frida",
+        fridaPanel(ctx as never, (ctx as { theme?: Theme }).theme),
+      );
+    },
+  });
+}

package/packages/studio/extensions/frida-eval.ts

@@ -0,0 +1,135 @@
+/**
+ * FRIDA eval (#21 v1) — kernel JS persistente para el agente: lo que
+ * se define en una llamada (variables, funciones) vive en la
+ * siguiente, dentro de la misma sesión de pi. Casos: munging de JSON,
+ * cálculos, transformación de datos — sin salir del chat.
+ *
+ * Alcance v1 (veredicto en #21): JS vía node:vm (in-process, contexto
+ * aislado del host de pi, timeout 10s). Python persistente y el
+ * re-entry directo a las tools del agente dependen de upstream pi
+ * (stock no expone invocar tools desde código de extensión) —
+ * documentado, no intentado aquí.
+ *
+ * Seguridad: mismo modelo que la tool bash — ejecuta código a
+ * petición del agente en la máquina del usuario; vm aísla del proceso
+ * de pi (sin require/process/Buffer en el sandbox).
+ */
+// @ts-ignore — builtin de node provisto por pi en runtime; el shim de
+// de types.d.ts tipa para tsc. ts-ignore (NO expect-error, ver
+// biome.json noTsIgnore:off): el LSP sin tsconfig lo marca, tsc no.
+import * as vm from "node:vm";
+import { Type } from "typebox";
+
+const TIMEOUT_MS = 10_000;
+
+interface EvalToolResult {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+}
+
+interface EvalExtensionAPI {
+  registerTool: (def: {
+    name: string;
+    label: string;
+    description: string;
+    promptGuidelines?: string[];
+    parameters: unknown;
+    execute: (
+      toolCallId: string,
+      params: { code: string; reset?: boolean },
+      signal: unknown,
+      onUpdate: unknown,
+      ctx: unknown,
+    ) => Promise<EvalToolResult>;
+  }) => void;
+}
+
+function fmt(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "undefined";
+  if (typeof value === "function") {
+    return `[Function: ${(value as { name?: string }).name || "anónima"}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    try {
+      return JSON.stringify(value, null, 2) ?? String(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+export default function (pi: EvalExtensionAPI): void {
+  let context: vm.Context | undefined;
+
+  function ensureContext(reset: boolean): vm.Context {
+    if (!reset && context) return context;
+    const logs: string[] = [];
+    const sandbox = {
+      console: {
+        log: (...a: unknown[]) => logs.push(a.map((x) => fmt(x)).join(" ")),
+        error: (...a: unknown[]) =>
+          logs.push(`✗ ${a.map((x) => fmt(x)).join(" ")}`),
+      },
+      __logs: logs,
+    };
+    context = vm.createContext(sandbox);
+    return context;
+  }
+
+  pi.registerTool({
+    name: "eval_js",
+    label: "Eval JS (kernel persistente)",
+    description:
+      "Ejecuta JavaScript en un kernel PERSISTENTE por sesión: las" +
+      " variables y funciones definidas en una llamada están" +
+      " disponibles en la siguiente. Para munging de datos, cálculos" +
+      " y transformaciones sin salir del chat. Usa `reset: true` para" +
+      " empezar de cero.",
+    promptGuidelines: [
+      "Usa eval_js para cálculos, transformación de JSON y munging de" +
+        " datos — el estado persiste entre llamadas (declara helpers" +
+        " una vez y reúsalos).",
+    ],
+    parameters: Type.Object({
+      code: Type.String({ description: "Código JS a ejecutar" }),
+      reset: Type.Optional(
+        Type.Boolean({ description: "Reiniciar el kernel (default false)" }),
+      ),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      let logs: string[] = [];
+      try {
+        const ctx = ensureContext(params.reset === true);
+        // SAFETY: __logs está garantizado en el contexto porque lo
+        // inyectamos nosostros en ensureContext (única fábrica de
+        // contextos); TypeScript no puede verlo porque vm.Context es
+        // opaco por diseño del shim.
+        logs = (ctx as unknown as { __logs?: string[] }).__logs ?? [];
+        logs.length = 0;
+        const value = new vm.Script(params.code, {
+          filename: "eval_js",
+        }).runInContext(ctx, { timeout: TIMEOUT_MS });
+        const parts: string[] = [];
+        if (logs.length > 0) parts.push(logs.join("\n"));
+        if (value !== undefined) parts.push(`⇒ ${fmt(value)}`);
+        if (parts.length === 0) parts.push("(sin salida — ¿retornar algo?)");
+        return {
+          content: [{ type: "text", text: parts.join("\n") }],
+          details: { kernel: "js", persisted: params.reset !== true },
+        };
+      } catch (e) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✗ ${e instanceof Error ? `${e.name}: ${e.message}` : String(e)}`,
+            },
+          ],
+          details: { kernel: "js", error: true },
+        };
+      }
+    },
+  });
+}

package/packages/studio/extensions/frida-footer.ts

@@ -0,0 +1,98 @@
+/**
+ * FRIDA footer (#8) — status bar con marca + telemetría básica:
+ * FRIDA-STUDIO vX · modelo · % de contexto · rama git. Extensión
+ * PROPIA (regla de vehículos: el footer necesita marca FRIDA);
+ * reemplaza a pi-powerline-footer en el bundle para no pelear por
+ * el único slot del footer (quien prefiera powerline puede
+ * instalarlo aparte: pi install npm:pi-powerline-footer).
+ *
+ * API: ctx.ui.setStatus(id, text) — refresco cada 30s y al arrancar
+ * (patrón monopi custom-footer). KIT_VERSION se importa de
+ * branding.ts (fuente única que sincroniza sync-kit.mjs).
+ */
+import { KIT_VERSION } from "./branding";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const REFRESH_MS = 30_000;
+
+declare const process: { cwd(): string };
+
+// Tipos estructurales locales (el repo no instala los peers de pi en
+// node_modules — regla de aislamiento; el loader de pi los provee en
+// runtime y los tipos de aquí solo documentan la superficie usada).
+interface FooterCtx {
+  mode?: string;
+  cwd?: string;
+  model?: string | { id?: string };
+  getContextUsage?: () => unknown;
+  ui?: { setStatus?: (id: string, text: string) => void };
+}
+interface FooterExtensionAPI {
+  on: (
+    event: "session_start",
+    cb: (event: unknown, ctx: FooterCtx) => void | Promise<void>,
+  ) => void;
+}
+
+function gitBranch(cwd: string): string {
+  try {
+    const head = readFileSync(join(cwd, ".git", "HEAD"), "utf8").trim();
+    const m = head.match(/^ref: refs\/heads\/(.+)$/);
+    if (m) return m[1];
+    if (head.length === 40) return `(detached ${head.slice(0, 7)})`;
+  } catch {
+    /* no es un repo git — sin rama */
+  }
+  return "";
+}
+
+function contextPct(ctx: FooterCtx): string {
+  try {
+    const usage = (ctx.getContextUsage as () => unknown)();
+    if (typeof usage === "number") return `${Math.round(usage)}%`;
+    if (usage && typeof usage === "object") {
+      const u = usage as Record<string, unknown>;
+      for (const k of ["usedPct", "percent", "pct", "usedPercent"]) {
+        if (typeof u[k] === "number") return `${Math.round(u[k] as number)}%`;
+      }
+    }
+  } catch {
+    /* API distinta entre versiones de pi — omitir sin romper */
+  }
+  return "";
+}
+
+function renderFooter(ctx: FooterCtx): string {
+  const parts = [`FRIDA-STUDIO v${KIT_VERSION}`];
+  const model = typeof ctx.model === "string" ? ctx.model : ctx.model?.id;
+  if (model) parts.push(model);
+  const pct = contextPct(ctx);
+  if (pct) parts.push(`ctx ${pct}`);
+  const branch = gitBranch(
+    typeof ctx.cwd === "string" ? ctx.cwd : process.cwd(),
+  );
+  if (branch) parts.push(branch);
+  return parts.join(" · ");
+}
+
+export default function (pi: FooterExtensionAPI): void {
+  const tick = (ctx: FooterCtx) => {
+    try {
+      ctx.ui?.setStatus?.("frida-footer", renderFooter(ctx));
+    } catch {
+      /* sin UI o API distinta — silent */
+    }
+  };
+
+  pi.on("session_start", async (_event: unknown, ctx: FooterCtx) => {
+    if (ctx.mode !== "tui") return;
+    tick(ctx);
+    // SAFETY: en runtime (node) setInterval devuelve un Timeout con
+    // unref(); el tipo number viene de la lib DOM del linter, que no
+    // conoce los timers de node (repo sin @types/node por aislamiento).
+    const timer = setInterval(() => tick(ctx), REFRESH_MS) as unknown as {
+      unref: () => void;
+    };
+    timer.unref();
+  });
+}

package/packages/studio/extensions/frida-uris.ts

@@ -0,0 +1,148 @@
+/**
+ * FRIDA URIs (#19) — recursos del equipo como si fueran archivos:
+ * `pr://N`, `issue://N`, `diff://N` — una sola interfaz para el
+ * modelo en vez de N flags de gh que aprender (idea de producto
+ * tomada de omp, adaptada al kit sobre pi stock).
+ *
+ * v1: GitHub del repo actual vía `gh` (el equipo ya viene
+ * autenticado). Follow-up documentado: `agent://<id>/...` vía el
+ * event bus/RPC de pi-subagents.
+ */
+// @ts-ignore — módulo builtin de node provisto por pi en runtime;
+// resuelve vía el shim de types.d.ts para tsc (ver tsconfig studio).
+// ts-ignore (no expect-error): el LSP sin tsconfig lo marca, tsc no.
+import { spawnSync } from "node:child_process";
+import { Type } from "typebox";
+
+const MAX_OUT = 50_000;
+
+interface ToolResult {
+  content: { type: "text"; text: string }[];
+  details: Record<string, string>;
+}
+
+interface UriToolCtx {
+  cwd?: string;
+}
+
+interface UriExtensionAPI {
+  registerTool: (def: {
+    name: string;
+    label: string;
+    description: string;
+    promptGuidelines?: string[];
+    parameters: unknown;
+    execute: (
+      toolCallId: string,
+      params: { uri: string },
+      signal: unknown,
+      onUpdate: unknown,
+      ctx: UriToolCtx,
+    ) => Promise<ToolResult>;
+  }) => void;
+}
+
+function ghField(o: Record<string, unknown>, key: string): string {
+  const v = o[key];
+  if (v == null) return "";
+  if (typeof v === "object") {
+    const login = (v as { login?: string }).login;
+    if (login) return login;
+    return JSON.stringify(v);
+  }
+  return String(v);
+}
+
+function prettyJson(json: string, kind: "pr" | "issue"): string {
+  try {
+    const o = JSON.parse(json) as Record<string, unknown>;
+    const head =
+      kind === "pr"
+        ? `# PR #${ghField(o, "number")}: ${ghField(o, "title")}`
+        : `# Issue #${ghField(o, "number")}: ${ghField(o, "title")}`;
+    const state = `**estado:** ${ghField(o, "state")} · **autor:** ${ghField(o, "author")}`;
+    const extra =
+      kind === "pr"
+        ? ` · +${ghField(o, "additions")}/-${ghField(o, "deletions")} · ${ghField(o, "changedFiles")} archivos`
+        : "";
+    const body = ghField(o, "body") || "(sin cuerpo)";
+    return `${head}\n\n${state}${extra}\n\n---\n\n${body}`;
+  } catch {
+    return json;
+  }
+}
+
+export default function (pi: UriExtensionAPI): void {
+  pi.registerTool({
+    name: "read_uri",
+    label: "Leer URI del equipo",
+    description:
+      "Lee recursos del equipo como si fueran archivos: pr://N (pull" +
+      " request), issue://N (issue), diff://N (diff del PR). Una sola" +
+      " interfaz en vez de aprender comandos gh.",
+    promptGuidelines: [
+      "Usa read_uri (pr://N, issue://N, diff://N) para leer pull" +
+        " requests, issues y diffs del repo actual, en vez de llamar" +
+        " gh directo.",
+    ],
+    parameters: Type.Object({
+      uri: Type.String({
+        description: "pr://N | issue://N | diff://N (N = número)",
+      }),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const m = /^(pr|issue|diff):\/\/(\d+)$/.exec(params.uri.trim());
+      if (!m) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✗ URI no válida: "${params.uri}" — esperar pr://N, issue://N o diff://N`,
+            },
+          ],
+          details: { uri: params.uri, error: "bad-uri" },
+        };
+      }
+      const [, scheme, n] = m;
+      const cwd = ctx?.cwd ?? process.cwd();
+      const args =
+        scheme === "pr"
+          ? [
+              "pr",
+              "view",
+              n,
+              "--json",
+              "number,title,state,author,body,additions,deletions,changedFiles",
+            ]
+          : scheme === "issue"
+            ? [
+                "issue",
+                "view",
+                n,
+                "--json",
+                "number,title,state,author,body,labels",
+              ]
+            : ["pr", "diff", n];
+      const r = spawnSync("gh", args, { encoding: "utf8", cwd });
+      if (r.status !== 0 || !r.stdout) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✗ gh exit ${r.status}: ${(r.stderr ?? "").slice(0, 500)}`,
+            },
+          ],
+          details: { uri: params.uri, error: "gh-failed" },
+        };
+      }
+      const out =
+        scheme === "diff"
+          ? r.stdout
+          : prettyJson(r.stdout, scheme === "pr" ? "pr" : "issue");
+      return {
+        content: [{ type: "text", text: out.slice(0, MAX_OUT) }],
+        details: { uri: params.uri },
+      };
+    },
+  });
+}

package/packages/studio/prompts/rol-datos-ia.md

@@ -0,0 +1,19 @@
+---
+description: Rol datos/IA — pipelines de datos y ML reproducibles
+---
+
+Actúa como **ingeniero de datos/IA** para esta tarea/sesión.
+
+## Contrato
+
+- Reproducibilidad primero: seeds fijas, versiones pinneadas, pasos deterministas documentados.
+- Datos crudos inmutables; toda transformación es un paso explícito y re-ejecutable.
+- Valida supuestos de los datos (nulos, duplicados, rangos, drift) antes de modelar nada.
+- Experimentos con hipótesis y métrica declaradas ANTES de correr; sin p-hacking.
+- Un artefacto de modelo sin métricas de evaluación y datos de prueba no es un entregable.
+- Costo/latencia estimados para anything que vaya a producción.
+
+## Defaults
+
+- Notebooks para explorar, scripts para producir; nada crítico vive solo en un notebook.
+- Logs estructurados por paso del pipeline (qué, cuánto, cuándo, resultado).

package/packages/studio/prompts/rol-dev.md

@@ -0,0 +1,20 @@
+---
+description: Rol desarrollador general — defaults seguros para trabajo diario
+---
+
+Actúa como **desarrollador general del equipo** para esta tarea/sesión.
+
+## Contrato
+
+- Lee antes de editar: entiende el contexto del archivo y sus tests.
+- Cambios mínimos y quirúrgicos; nada de reformatteo ajeno al cambio.
+- Cada afirmación sobre el código se verifica leyéndolo, no de memoria.
+- Si un cambio toca más archivos de lo esperado, para y repórtalo antes de seguir.
+- Corre los tests/verificaciones del repo después de cada cambio que afirmen algo.
+- No marques nada como hecho si queda implementación parcial o errores.
+
+## Defaults
+
+- Sigue los AGENTS.md del camino raíz→archivo (contratos vinculantes).
+- Commits atómicos con mensaje estructurado cuando se pida.
+- Ante ambigüedad: pregunta con opciones concretas en vez de asumir.

package/packages/studio/prompts/rol-fullstack.md

@@ -0,0 +1,20 @@
+---
+description: Rol fullstack — arquitectura y calidad de punta a punta
+---
+
+Actúa como **desarrollador fullstack** para esta tarea/sesión.
+
+## Contrato
+
+- Piensa en el stack completo: datos → API → UI → despliegue.
+- Antes de proponer, nombra las alternativas viables (máx. 3) y por qué descartas las otras.
+- Cada decisión de arquitectura queda documentada: qué, por qué, trade-offs.
+- Interfaces profundas y módulos con una sola responsabilidad; evita superficies anchas.
+- Validación en capas: tipos/tests del backend, render/tests del frontend, humo del flujo completo.
+- Backwards compatibility: un cambio de contrato se migra, no se rompe.
+
+## Defaults
+
+- Errores de usuario y de sistema por separado; nunca un `catch` vacío.
+- Estado del servidor como fuente de verdad; el cliente es una vista.
+- Migraciones y seeds versionados con el código.

package/packages/studio/prompts/rol-seguridad.md

@@ -0,0 +1,19 @@
+---
+description: Rol seguridad — auditoría y análisis de vulnerabilidades
+---
+
+Actúa como **investigador de seguridad** para esta tarea/sesión.
+
+## Contrato
+
+- Solo en sistemas/alcance autorizados explícitamente; si no está autorizado, no se toca.
+- Hallazgos con evidencia: archivo:línea, vector, impacto, repro/POC cuando aplique.
+- Severidad honesta (crítica/alta/media/baja) con justificación, sin inflar.
+- Distingue siempre riesgo real vs teórico vs defense-in-depth.
+- Remediación accionable por hallazgo, ordenada por costo/beneficio.
+- Secretos y credenciales jamás a logs, issues ni output — referencia, no valor.
+
+## Defaults
+
+- Empieza por la superficie expuesta (input handling, auth, deserialización, inyección, secretos en repo).
+- False positives verificados antes de reportarse; cada claim se comprueba contra el código.

package/packages/studio/skills/gh-quoting/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: gh-quoting
+description: Construir comandos gh (issue/pr/release) con bodies o comentarios dinámicos sin que el shell ejecute backticks o $ del contenido. Usar siempre que se genere markdown con código como argumento de gh CLI.
+---
+
+# gh-quoting — argumentos seguros para gh CLI
+
+Los bodies de issues/comentarios llevan markdown con backticks y `$` —
+pasarlos como argumento de shell entre comillas dobles los EJECUTA
+(sustitución de comando/variable) y el contenido queda mocho. El fallo
+es **silencioso**: gh sale 0 con el texto corrupto. (Nacida de lecciones
+reales del equipo vía learn-review — issue #33.)
+
+## Cuándo usar
+
+- Cualquier `gh` con contenido dinámico: `--body`, `--comment`,
+  `--title`, notas de release.
+- Especialmente si el texto contiene backticks (código), `$(...)` o `$`.
+
+## Procedimiento
+
+1. NUNCA `--body "..."` con comillas dobles si el texto puede traer
+   backticks o `$` — el shell los ejecuta.
+2. SIEMPRE heredoc quoted por stdin:
+
+   ```bash
+   gh issue create --body-file - <<'EOF'
+   ...contenido con `backticks` y $vars intactos...
+   EOF
+   ```
+
+   El quoting de `'EOF'` desactiva toda sustitución dentro del bloque.
+
+3. Si el comando no acepta stdin: archivo temporal +
+   `--body-file /tmp/x.md`.
+4. Tras publicar, releer el resultado (`gh issue view`) cuando el
+   contenido tenía backticks o `$`.
+
+## Trampas
+
+- Comillas simples anidadas dentro de `--body '...'` también rompen —
+  heredoc.
+- `$(...)` en el contenido se ejecuta igual que los backticks.
+- gh exit 0 con el texto mocho: no confiar en el exit code solo.
+
+## Verificación
+
+- El issue/comentario publicado conserva backticks y `$` intactos
+  (releído con `gh issue view`).