xonecode 0.3.0 → 0.5.0

package/skills/archify/scripts/render-examples.mjs

@@ -0,0 +1,26 @@
+// Re-render every bundled example from its JSON IR. Installed skills keep HTML
+// beside the JSON examples; the development script passes the golden directory.
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const outputRoot = path.resolve(process.argv[2] || path.join(skillRoot, 'examples'));
+
+const TARGETS = [
+  ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+  ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+  ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+  ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+  ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, output] of TARGETS) {
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', input),
+    path.join(outputRoot, output),
+  ], { stdio: 'inherit' });
+}

package/skills/archify/scripts/update-contract.mjs

@@ -0,0 +1,182 @@
+export const SKILL_ID = 'archify';
+export const EXPECTED_REPOSITORY = 'https://github.com/tt-a1i/archify';
+export const DEFAULT_MANIFEST_URL = 'https://tt-a1i.github.io/archify/skill-updates/archify/stable.json';
+
+const CONTROL_OR_BIDI = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u;
+const HEX_40 = /^[a-f0-9]{40}$/;
+const HEX_64 = /^[a-f0-9]{64}$/;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const UTC_SECONDS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+export class UpdateContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UpdateContractError';
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactKeys(value, expected) {
+  return isPlainObject(value)
+    && Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+
+export function parseSemver(value) {
+  if (typeof value !== 'string' || value.length > 128) {
+    throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  }
+  const match = SEMVER.exec(value);
+  if (!match) throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  const prerelease = match[4]?.split('.') ?? null;
+  if (prerelease?.some((identifier) => /^\d+$/.test(identifier)
+    && identifier.length > 1 && identifier.startsWith('0'))) {
+    throw new UpdateContractError(`invalid SemVer: ${JSON.stringify(value)}`);
+  }
+  return {
+    core: match.slice(1, 4),
+    prerelease,
+    build: match[5]?.split('.') ?? null,
+  };
+}
+
+function compareNumericIdentifiers(left, right) {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function comparePrerelease(left, right) {
+  if (left === null && right === null) return 0;
+  if (left === null) return 1;
+  if (right === null) return -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    if (left[index] === right[index]) continue;
+    const leftNumeric = /^\d+$/.test(left[index]);
+    const rightNumeric = /^\d+$/.test(right[index]);
+    if (leftNumeric && rightNumeric) return compareNumericIdentifiers(left[index], right[index]);
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareSemver(leftValue, rightValue) {
+  const left = parseSemver(leftValue);
+  const right = parseSemver(rightValue);
+  for (let index = 0; index < left.core.length; index += 1) {
+    const comparison = compareNumericIdentifiers(left.core[index], right.core[index]);
+    if (comparison !== 0) return comparison;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export function releaseChannelForVersion(value) {
+  return parseSemver(value).prerelease ? 'development' : 'stable';
+}
+
+export function isStableCoreVersion(value) {
+  try {
+    const parsed = parseSemver(value);
+    return parsed.prerelease === null && parsed.build === null;
+  } catch {
+    return false;
+  }
+}
+
+export function validateCanonicalUtcTimestamp(value) {
+  if (typeof value !== 'string' || !UTC_SECONDS.test(value)) {
+    throw new UpdateContractError('publication time must use YYYY-MM-DDTHH:mm:ssZ');
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)
+    || new Date(timestamp).toISOString().replace('.000Z', 'Z') !== value) {
+    throw new UpdateContractError('publication time is not a real UTC calendar instant');
+  }
+  return value;
+}
+
+export function validateLocalRelease(value) {
+  if (!hasExactKeys(value, [
+    'schemaVersion', 'skillId', 'channel', 'version', 'source', 'updateManifestUrl',
+  ])
+    || value.schemaVersion !== 1
+    || value.skillId !== SKILL_ID
+    || !hasExactKeys(value.source, ['repository'])
+    || value.source.repository !== EXPECTED_REPOSITORY
+    || value.updateManifestUrl !== DEFAULT_MANIFEST_URL) {
+    throw new UpdateContractError('invalid local release identity');
+  }
+  const expectedChannel = releaseChannelForVersion(value.version);
+  if (value.channel !== expectedChannel) {
+    throw new UpdateContractError('local release channel does not match its version');
+  }
+  return {
+    schemaVersion: value.schemaVersion,
+    skillId: value.skillId,
+    channel: value.channel,
+    version: value.version,
+    source: { repository: value.source.repository },
+    updateManifestUrl: value.updateManifestUrl,
+  };
+}
+
+export function validateReleaseNotesUrl(value, version) {
+  if (!isStableCoreVersion(version)) {
+    throw new UpdateContractError('release notes require a stable core version');
+  }
+  const expected = `https://github.com/tt-a1i/archify/releases/tag/v${version}`;
+  if (value !== expected) {
+    throw new UpdateContractError('release notes URL is outside the exact trusted release path');
+  }
+  return value;
+}
+
+export function validateStableUpdateManifest(value) {
+  if (!hasExactKeys(value, [
+    'schemaVersion', 'skillId', 'channel', 'version', 'publishedAt', 'source',
+    'artifact', 'summary', 'releaseNotes', 'severity',
+  ])
+    || value.schemaVersion !== 1
+    || value.skillId !== SKILL_ID
+    || value.channel !== 'stable'
+    || !isStableCoreVersion(value.version)
+    || !hasExactKeys(value.source, ['repository', 'ref', 'treeSha'])
+    || value.source.repository !== EXPECTED_REPOSITORY
+    || value.source.ref !== `v${value.version}`
+    || !HEX_40.test(value.source.treeSha)
+    || !hasExactKeys(value.artifact, ['sha256'])
+    || !HEX_64.test(value.artifact.sha256)) {
+    throw new UpdateContractError('invalid immutable stable release identity');
+  }
+  validateCanonicalUtcTimestamp(value.publishedAt);
+  if (typeof value.summary !== 'string' || value.summary.length < 1 || value.summary.length > 160
+    || CONTROL_OR_BIDI.test(value.summary)) {
+    throw new UpdateContractError('invalid release summary');
+  }
+  validateReleaseNotesUrl(value.releaseNotes, value.version);
+  if (!['normal', 'security'].includes(value.severity)) {
+    throw new UpdateContractError('invalid update severity');
+  }
+  return {
+    schemaVersion: value.schemaVersion,
+    skillId: value.skillId,
+    channel: value.channel,
+    version: value.version,
+    publishedAt: value.publishedAt,
+    source: {
+      repository: value.source.repository,
+      ref: value.source.ref,
+      treeSha: value.source.treeSha,
+    },
+    artifact: { sha256: value.artifact.sha256 },
+    summary: value.summary,
+    releaseNotes: value.releaseNotes,
+    severity: value.severity,
+  };
+}

package/skills/archify/skill-release.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "skillId": "archify",
+  "channel": "development",
+  "version": "2.17.0-dev.1",
+  "source": {
+    "repository": "https://github.com/tt-a1i/archify"
+  },
+  "updateManifestUrl": "https://tt-a1i.github.io/archify/skill-updates/archify/stable.json"
+}

package/skills/artifacts-builder/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: artifacts-builder
+description: "Build a self-contained interactive HTML artifact the user can view in the chat: dashboards, interactive charts, flow diagrams, filterable tables, printable reports. Use when a plain text answer would lose information that a visual or interactive piece would keep."
+---
+
+# Artifacts Builder
+
+You write ONE self-contained HTML file. No build step, no npm, no `execute` anywhere this
+skill is mounted — nothing here runs a script.
+
+## Steps
+
+1. **Pick a character and paste the tokens** — `reference/estilo.md`, one table row, whole.
+   This is a STEP and not optional reading, and the reason is measured: while it lived under
+   "read when you need it" the builder **never opened it**, and every panel came out the same —
+   Inter, indigo accent, four different corner radii and zero CSS variables. Five tokens
+   (`--surface --surface-2 --ink --ink-muted --border --accent --radius`) and one row of the
+   character table are the whole decision; the file is 86 lines and it is the short one.
+2. **Write** the HTML with `write_file` **en `/artefactos/<nombre>.html`** — nunca en la raíz
+   del proyecto. Esa carpeta no es del proyecto: no pasa por la aprobación humana, no entra
+   en git y no sube a CloudStudio. Un HTML escrito fuera de ella acaba DENTRO de la app XOne
+   del usuario, que no es lo que nadie pidió. Keep it ONE file: with no `execute` tool
+   anywhere here, there is no bundler to run. Inline local assets (fonts, images) as `data:`
+   URIs directly in the file you write, instead of splitting it and planning to combine the
+   pieces later.
+3. **Entrega, según la tool que TENGAS:**
+   - **Si tienes `publish_artifact`** (el panel): `publish_artifact(path="/artifact.html",
+     title="…")`. Valida al publicar contra el contrato de abajo. Si lo rechaza, te dice
+     exactamente qué arreglar; corrige y reintenta. Para actualizar uno que ya publicaste,
+     pasa su `artifact_id` — el enlace del usuario no cambia.
+   - **Si tienes `renderizar_diagrama` en vez de `publish_artifact`** (el camino de
+     `documentar`): si lo que construiste es un DIAGRAMA (arquitectura, flujo, secuencia,
+     dataflow, lifecycle), no sigas este camino — usa la skill `archify` y llama a
+     `renderizar_diagrama(tipo, spec_json, ruta)`, que valida y coloca el fichero por ti.
+     Para cualquier OTRO artefacto (tabla, dashboard, gráfica que no es un diagrama de
+     archify), ya tienes `write_file`: escríbelo en `/artefactos/` — el contrato de abajo NO
+     aplica en este camino, es del sandbox del panel (ver su nota).
+   - **Si no tienes NINGUNA de las dos** (xonecode): `write_file` en
+     `/artefactos/<nombre>.html` y ya está. No inventes ninguna de las dos tools, y no
+     anuncies capacidades del panel —sandbox, enlace compartible, actualización por
+     `artifact_id`— que en este camino no existen. La entrega ES la escritura: la consola
+     anuncia el artefacto sola.
+   **Cuando la entrega confirme, HAS TERMINADO** — no reescribas el mismo artefacto otra vez.
+
+## The contract — non-negotiable — solo si tienes `publish_artifact`
+
+El artefacto corre en un sandbox cerrado. Esto lo hace cumplir el SERVIDOR de `publish_artifact`,
+no la confianza — y por eso solo es cierto en este camino, no en el de `write_file`:
+
+- **No network.** No `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `sendBeacon`,
+  dynamic `import()`. Bake the data into the HTML as a JS constant.
+- **Libraries only from** `https://cdnjs.cloudflare.com` or `https://cdn.jsdelivr.net`
+  (fonts: `fonts.googleapis.com` + `fonts.gstatic.com`). Pin an exact version.
+- **Images**: `data:` URIs only. An external `<img src>` leaks data through its query string.
+- **No** `<base>`, no external `<iframe>`, no external `<form action>`.
+- **5 MB max.**
+- **`localStorage` THROWS. Wrap every access in `try/catch` — or don't use it.** The widget
+  renders the artifact in an iframe with `sandbox="allow-scripts allow-downloads allow-modals"`
+  and **no `allow-same-origin`**, so the document has an opaque origin and merely *reading*
+  `localStorage` raises:
+
+  ```
+  Failed to read the 'localStorage' property from 'Window':
+  The document is sandboxed and lacks the 'allow-same-origin' flag.
+  ```
+
+  This is measured, not theoretical, and it is the **most expensive mistake in this list**
+  because it fails SILENTLY. A real panel died on `'theme' in localStorage` before
+  `mermaid.initialize(…)` ever ran, and the page looked perfect while the diagram stayed an
+  empty rectangle. `matchMedia('(prefers-color-scheme: dark)')` needs no storage for the theme;
+  if you really want to remember something per viewer, wrap it: `try { localStorage.setItem(k,
+  v) } catch {}`.
+
+## El contrato del OTRO camino, `write_file` en `/artefactos/` (xonecode)
+
+Este párrafo decía que sin `publish_artifact` no había sandbox: «el fichero queda tal cual en el
+proyecto del cliente, sin iframe, sin lista blanca de CDN, `localStorage` no lanza ahí». **Es
+falso desde que la consola los ABRE**, y era el error más caro que se podía dejar escrito: quien
+lo leyera usaría `localStorage` y el diagrama moriría en silencio.
+
+Aquí el sandbox lo impone el VISOR de la consola, no un servidor de publicación — y lo impone
+igual. Medido en el navegador (2026-09-07) sobre un artefacto real, con el iframe en
+`sandbox="allow-scripts"` y **sin** `allow-same-origin`:
+
+- **`localStorage`, `sessionStorage` e `indexedDB` LANZAN `SecurityError`.** Los tres, no solo el
+  primero. Vale entera la advertencia de arriba, incluido por qué es el error más caro de la
+  lista: falla EN SILENCIO, con la página perfecta y el diagrama sin dibujar.
+- **Las CDNs SÍ funcionan, con conexión.** `cdnjs.cloudflare.com` y `fonts.googleapis.com` /
+  `fonts.gstatic.com` contestaron 200 desde dentro del iframe. No hay lista blanca que cumplir
+  ni tope de 5 MB (el visor sirve hasta 20 MB) ni validador que rechace nada: lo que escribas es
+  lo que se verá. Usa esas dos CDNs igualmente.
+- **Al ORIGEN de la consola no se llega.** Un `fetch` a cualquier ruta suya muere en el propio
+  navegador («from origin 'null' has been blocked by CORS»), así que sus tipografías
+  empaquetadas y sus rutas no están a tu alcance: da igual que estén ahí al lado.
+- **Nada bloquea una petición a un tercero**, y justo por eso: no hagas ninguna que no
+  necesites. Hornea los datos dentro del HTML, como en el otro camino — un proyecto XOne puede
+  abrirse offline, y una petición saliente se lleva consigo lo que lleve en la URL.
+
+## What you can use
+
+React 18 (UMD), Tailwind, any chart library, mermaid, via CDN `<script>` tags — no bundler,
+either path. **Con `publish_artifact`**, solo pasan `cdnjs.cloudflare.com` y `cdn.jsdelivr.net`
+(`https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4`, NUNCA `cdn.tailwindcss.com`: no está en
+la lista blanca). **Con `write_file`**, no hay lista blanca que cumplir — igual, usa esas dos
+CDNs por defecto salvo que el proyecto ya traiga otra cosa.
+
+## Read when you need it
+
+- `reference/graficas.md` — interactive charts
+- `reference/diagramas.md` — flow diagrams with mermaid
+- `reference/exportar-pdf.md` — a working PDF export button
+- `reference/estilo.md` — **el sistema visual (paso 1, no opcional)**: tokens, carácter, escala
+
+## Rules of thumb
+
+- Support dark and light: don't hardcode one color scheme.
+- One page, one job. If it needs two unrelated screens, that's two artifacts (or two files).
+- Bake enough data to be useful, not the whole dataset. Con `publish_artifact` el tope de 5 MB
+  lo impone el servidor; con `write_file` no hay tope impuesto, pero un fichero de datos entero
+  sigue siendo mala idea igual.

package/skills/artifacts-builder/reference/diagramas.md

@@ -0,0 +1,123 @@
+# Diagramas de flujo
+
+## Antes de escribir HTML: `archify` decide el diagrama
+
+Si la petición es **solo** un diagrama, esquema, arquitectura, flujo, secuencia, data-flow o
+ciclo de estados, **no uses esta skill**: carga únicamente **`archify`**. Es quien decide el
+tipo de diagrama, qué evidencia del proyecto es relevante y cómo conservar nombres reales.
+
+`artifacts-builder` participa únicamente cuando el usuario pide además un contenedor HTML
+interactivo, dashboard, informe o tabla. En ese caso, espera a que `archify` haya decidido el
+diagrama, crea su SVG y **lo incrusta inline** en el único HTML de este artefacto.
+
+- La salida se guarda en `/artefactos/<nombre>.html`, nunca en la raíz del proyecto —de ahí
+  acabaría dentro de la app XOne del usuario, en git y en CloudStudio— ni en `/skills`, donde
+  viven solo instrucciones y recursos del harness.
+- No inventes `renderizar_diagrama`, `publish_artifact` ni una ejecución de scripts si esas
+  herramientas no figuran en tu contexto. Con `write_file`, entrega el HTML autocontenido.
+- Usa Mermaid únicamente cuando el usuario lo pida expresamente o cuando un SVG manual no aporte
+  claridad. Para el resto, `archify` es la fuente de decisión visual y semántica.
+- Si el resultado combina análisis del proyecto y un diagrama, primero confirma los hechos con
+  el código; no dibujes componentes, rutas ni estados que no estén comprobados.
+
+## Mermaid, solo cuando procede
+
+Mermaid desde cdnjs. Sin red: el diagrama es texto dentro de la página. **Éste es el montaje
+canónico** — copia el bloque entero, no la mitad:
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.0/mermaid.min.js"></script>
+<pre class="mermaid">
+flowchart LR
+  Login["LoginRest (login-coll)"] --> Entry["VisitasClientes_v2 (entry-point)"]
+  Entry --> Q{"¿Cliente nuevo?"}
+  Q -->|"Sí"| Alta["Clientes.xne"]
+  Q -->|"No"| DB[("gestion.db")]
+</pre>
+<style>
+  .mermaid { width: 100%; overflow-x: auto; }
+  .mermaid svg { width: 100%; height: auto; max-width: none; }
+</style>
+<script>
+  mermaid.initialize({
+    startOnLoad: true,
+    theme: "base",                       // el ÚNICO que acepta themeVariables
+    themeVariables: {
+      primaryColor:       "#ffffff",     // relleno del nodo   → --surface
+      primaryTextColor:   "#151a21",     // texto del nodo     → --ink
+      primaryBorderColor: "#d7dee6",     // borde              → --rule
+      lineColor:          "#4e5a68",     // flechas            → --ink-soft
+      secondaryColor:     "#eef2f6",     // fondo de subgrafos → --surface-2
+      tertiaryColor:      "#d9edf4",     // lo acentuado       → --accent-soft
+      fontFamily:         "'IBM Plex Serif', Georgia, serif",
+      fontSize:           "15px",
+    },
+    flowchart: { curve: "basis", nodeSpacing: 40, rankSpacing: 55, padding: 12 },
+  });
+</script>
+```
+
+## Por qué ese bloque y no el de por omisión
+
+Los defectos de mermaid pintan **nodos amarillo pastel con borde marrón, en escuadra y
+apelotonados**: el diagrama parece de otro producto que el panel que lo rodea. Comprobado en un
+navegador con 10.9.0, con el bloque de arriba el relleno del nodo sale `#ffffff`, el borde
+`#d7dee6` y las flechas `#4e5a68` — o sea **los mismos tokens que el panel** (`estilo.md`).
+
+- **`theme: "base"`**: con `default`, `dark` o `neutral`, `themeVariables` **se ignora**.
+- **`curve: "basis"`**: aristas curvas en vez de en escuadra. El cambio de una línea que más
+  aire da.
+- **`nodeSpacing`/`rankSpacing`**: los defectos (15/50) aprietan; 40/55 respira.
+- **Los colores van A MANO, no como `var(--x)`**: mermaid los escribe dentro del SVG y no
+  resuelve variables CSS. Con tema oscuro, pásale el juego oscuro cuando
+  `matchMedia('(prefers-color-scheme: dark)').matches`.
+- **Las dos líneas del `<style>`**: `overflow-x` en el BLOQUE (la página no debe scrollear en
+  horizontal) y `max-width: none` en el SVG, porque mermaid le escribe su tamaño natural y sin
+  eso se queda pequeño y centrado en un panel ancho.
+
+## LO PRIMERO: toda etiqueta con `(` va ENTRE COMILLAS
+
+Un paréntesis sin comillas es un error de SINTAXIS y **se lleva el diagrama entero**: la página
+carga perfecta y en su sitio sale «Syntax error in text». Medido con `mermaid.parse`, y **en
+10.9.0 y en 11.15.0 igual** — no es cosa de la versión:
+
+| lo que escribes | |
+|---|---|
+| `A[Mapeos (mapcol)]` | **ROMPE** |
+| `A["Mapeos (mapcol)"]` | ✓ |
+| `subgraph Vistas (contents)` | **ROMPE** |
+| `subgraph S1 [Vistas (contents)]` | **ROMPE** — los corchetes NO salvan |
+| `subgraph "Vistas (contents)"` | ✓ |
+| `A[(Tabla (usuarios))]` | **ROMPE** · `DB[("Tabla (usuarios)")]` ✓ |
+
+Y lo que **NO** rompe, comprobado igual: almohadillas (`A[Salida ##EXIT##]`), puntos
+(`A[LoginColl.xne]`), acentos, `:`, `@` y texto en las flechas — las almohadillas se han acusado
+en falso DOS veces. En un proyecto XOne los nombres traen paréntesis solos (`(mapcol)`,
+`(contents)`, `(entry-point)`), así que la regla práctica es **comillas siempre**.
+
+## Si el diagrama va en una PESTAÑA, `startOnLoad: true` lo deja en blanco
+
+**Fallo real, medido**: dentro de un contenedor oculto mermaid produce un SVG de **0×0** y no
+vuelve a dibujar al mostrarlo (visible al cargar da 563×427). El usuario ve un hueco y la
+consola no dice nada. Con pestañas, acordeones o `<details>` cerrados: **`startOnLoad: false`, y
+dibujar DESPUÉS de mostrar**.
+
+```js
+const dibujados = new WeakSet();
+async function mostrarPestana(panel) {
+  panel.style.display = 'block';                  // primero VISIBLE
+  for (const nodo of panel.querySelectorAll('.mermaid')) {
+    if (dibujados.has(nodo)) continue;            // una sola vez por nodo
+    dibujados.add(nodo);
+    await mermaid.run({ nodes: [nodo] });         // y AHORA se dibuja
+  }
+}
+```
+
+De `0×0` a `278×105`. Tres detalles: **el orden no es negociable** (`display: block` ANTES de
+`mermaid.run`; al revés vuelve a dar 0×0) · **`run({ nodes: [...] })` y no `run()` a secas**
+(sin `nodes` reprocesa la página entera) · **una sola vez por nodo** (mermaid sustituye el
+`<pre>` por el SVG, así que un segundo pase no tiene texto que parsear).
+
+Diagnóstico rápido: «Syntax error in text» → un paréntesis sin comillas. Hueco en blanco SIN
+error → el contenedor oculto. Nunca las almohadillas.

package/skills/artifacts-builder/reference/estilo.md

@@ -0,0 +1,123 @@
+# El estilo es un SISTEMA: pega los tokens, elige un carácter
+
+Este fichero era una lista de consejos y se incumplía entera. Medido en un panel real
+(2026-09-01): decía «evita Inter» y salió `Inter`; decía «evita los morados» y salieron índigo
+`#6366f1` + púrpura + rosa; decía «una escala» y salieron cuatro radios sueltos; y cero
+variables CSS. **Un consejo no es un sistema**: lo que sigue se pega y se acabó.
+
+## Los tokens, y el tema en TRES bloques
+
+**El de por omisión**, elegido por el usuario el 2026-09-01: fondo casi blanco frío, tinta negra
+azulada, acento azul petróleo y el **cuerpo en SERIF**, que es lo que le quita la cara de
+plantilla. Pega el bloque tal cual y no uses ningún color más.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wght@500;600;700&family=IBM+Plex+Serif:ital,wght@0,400;0,600;1,400&family=IBM+Plex+Mono:wght@400;500&display=swap">
+<style>
+:root {
+  --ground:#f6f8fa; --surface:#ffffff; --surface-2:#eef2f6;  /* página / tarjeta / elevado */
+  --ink:#151a21; --ink-soft:#4e5a68; --rule:#d7dee6;         /* texto / apoyo / separador  */
+  --accent:#0e6c88; --accent-soft:#d9edf4;                   /* SOLO lo que actúa o mide   */
+  --alerta:#8d3b2d; --alerta-soft:#f5e3df;                   /* lo retirado, lo que falla  */
+  --display:'Archivo','Helvetica Neue',Arial,sans-serif;
+  --body:'IBM Plex Serif',Georgia,serif;
+  --mono:'IBM Plex Mono','SF Mono',Menlo,monospace;
+  --radius:6px;
+}
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
+  --ground:#11151a; --surface:#171c23; --surface-2:#1e242c;
+  --ink:#e5e9ef; --ink-soft:#9aa7b6; --rule:#2c343e;
+  --accent:#58b6d2; --accent-soft:#16323d; --alerta:#d98a7b; --alerta-soft:#35211d;
+} }
+:root[data-theme="dark"] { /* las MISMAS seis líneas de arriba, repetidas */ }
+body { background:var(--ground); color:var(--ink); font-family:var(--body);
+       font-size:17px; line-height:1.65; margin:0; }
+</style>
+```
+
+**Los tres bloques son tres ESTADOS y hacen falta los tres**: el visor puede no decir nada (gana
+`prefers-color-scheme`), decir `data-theme="dark"` o decir `data-theme="light"` — y sin el
+`:not([data-theme="light"])` un visor en claro dentro de un sistema oscuro sale oscuro. **Ningún
+color puede tener su única definición dentro de un `@media`.**
+
+Con Tailwind se usan tal cual: `bg-[var(--surface)]`, `text-[var(--ink-soft)]`,
+`border-[var(--rule)]`, `rounded-[var(--radius)]`, `font-[var(--display)]`. Y el diagrama se
+pinta con estos MISMOS tokens: `reference/diagramas.md`, sección del tema.
+
+## El cuerpo en SERIF, los titulares en sans, los identificadores en mono
+
+`IBM Plex Serif` a **17px / 1.65** para leer, `Archivo` para titulares y `IBM Plex Mono` para lo
+que es un identificador (`app.xml`, `MAP_BT_MENU`, nombres de coll). Esa mezcla es lo contrario
+del defecto —todo en Inter a 14px— y es la mitad del carácter.
+
+Otros caracteres, si el contenido pide otra cosa. **Se toma la fila ENTERA:**
+
+| carácter | display / cuerpo / mono | acento | radio |
+|---|---|---|---|
+| **documento** (el de arriba) | Archivo / IBM Plex Serif / IBM Plex Mono | `#0e6c88` petróleo | `6px` |
+| **instrumento** | IBM Plex Sans / IBM Plex Sans / IBM Plex Mono | `#0f766e` teal | `4px` |
+| **cuadro de mando** | Space Grotesk / Public Sans / IBM Plex Mono | `#1d4ed8` tinta | `10px` |
+| **xonecode** (solo si el artefacto habla de la CONSOLA) | IBM Plex Sans / IBM Plex Sans / IBM Plex Mono | `#00a3e0` cian de marca | `6px` |
+
+**Ninguna es Inter y ningún acento es índigo ni púrpura**, que es la otra mitad.
+
+La fila **xonecode** es la excepción con dueño, y tiene su regla: el cian `#00a3e0` es el color
+de marca MEDIDO (`apps/web/estilos/marca.css`, junto al azul `#083b56` de las superficies de
+marca), y se usa **solo cuando el artefacto es sobre xonecode o sobre el harness** — un diagrama
+de sus capas, un panel de su lazo de turno. Para el mockup de una pantalla XOne o para un
+informe del proyecto del cliente, NO: ahí el tema es el de por omisión, y la app tiene su propio
+CSS. Dos cosas que no son negociables en esa fila:
+
+- **El cian es ACENTO y jamás sostiene texto.** Es la misma regla que la consola aplica sobre sí
+  misma: el relleno del botón primario es casi negro y el cian se reserva para la pestaña
+  elegida, el filo de la tarjeta viva, el punto de estado y la fila seleccionada. Un titular
+  cian sobre blanco no tiene contraste y es exactamente el aspecto que esta fila intenta evitar.
+- **La tipografía de la consola —Inter— no está en el menú**, y por dos motivos a la vez: la
+  regla de arriba de este mismo fichero, y que sus fuentes empaquetadas **no se pueden cargar**
+  desde el artefacto (el iframe tiene origen opaco y no llega al origen de la consola; medido).
+  Se usa IBM Plex Sans, que es un instrumento y viene de Google Fonts como el resto.
+
+## El ancho: la PÁGINA no lleva `max-width`
+
+**El artifact se pinta en un panel, no en una ventana de navegador**, y su ancho lo decide quien
+mira — puede ser 1.700 px. Un `max-w-7xl mx-auto` en el contenedor exterior (que es lo que sale
+por defecto) son **1.280 px centrados**: en ese panel deja **460 px de margen muerto** a los
+lados, con el diagrama encogido en medio. Medido sobre un panel real, 2026-09-01.
+
+- **Nada de `max-w-*` ni `mx-auto` en el envoltorio de la página.** Se respira con `padding`
+  (`p-6 md:p-8`), no estrechando.
+- **La MEDIDA se limita solo en la PROSA**, que es donde de verdad importa: `max-w-prose` en los
+  párrafos largos. Una tabla, un diagrama o una rejilla de tarjetas quieren todo el ancho.
+- **Y el SVG de un diagrama tiene que poder CRECER**: mermaid le pone un `max-width` propio que
+  lo deja a su tamaño natural. Ver `reference/diagramas.md`.
+- **Y tiene que sobrevivir al panel ESTRECHO, que es el otro lado de lo mismo.** En la consola de
+  xonecode el artefacto se pinta en la columna central, con la barra lateral (280 px) y la lista
+  de artefactos (260 px) a los lados: en un portátil eso deja el iframe por debajo de 700 px. No
+  es motivo para estrechar la página —sigue sin `max-width`—, sino para que la rejilla ceda:
+  columnas que se apilan, tablas con su propio scroll horizontal, y ninguna medida fija en px
+  para el contenedor.
+
+## Tres reglas duras
+
+1. **UN radio por panel**, el de la fila que hayas elegido. La excepción única es `rounded-full`
+   para pastillas y avatares. Cuatro radios en una página es la firma de que nadie decidió.
+2. **El acento SOLO para lo que actúa o mide**: el botón que se pulsa, la barra que crece, el
+   nodo activo. Si el título, los iconos y las etiquetas van del color de acento, no destaca
+   nada — y ése es el aspecto de plantilla que se intenta evitar.
+3. **El fondo se PINTA, siempre y explícito** (`background: var(--ground)` en `body`). El visor
+   pinta su propio fondo detrás, así que un `body` transparente hereda el tema del anfitrión y
+   el texto puede acabar ilegible.
+
+**Y no pongas un INTERRUPTOR de tema.** Los tres bloques de arriba ya cubren los tres estados,
+así que no hace falta — y recordar la elección pide `localStorage`, que **LANZA** en el sandbox
+del visor y se lleva el bloque `<script>` entero: la página se ve perfecta y el diagrama no
+llega a dibujarse. Con `publish_artifact` lo rechaza además el validador. En la consola de
+xonecode no hay validador que lo pare, así que el único que lo evita eres tú — y ahí está medido
+(2026-09-07) que **los tres** almacenes lanzan `SecurityError`: `localStorage`, `sessionStorage`
+e `indexedDB`. Ver `SKILL.md`, «El contrato del OTRO camino».
+
+## Y lo de siempre
+
+Una jerarquía de TRES tamaños y sostenerla · alineación a la izquierda salvo motivo (centrarlo
+todo es la marca de fábrica) · espaciado 4/8/16/24 y nada entre medias · densidad al servicio
+del dato: una tabla de 40 filas legible vale más que 6 tarjetas enormes con tres cifras.

package/skills/artifacts-builder/reference/exportar-pdf.md

@@ -0,0 +1,56 @@
+# Exportar a PDF
+
+**La vía sencilla y fiable: `window.print()` con CSS de impresión.** No necesita librería, y el
+widget de NappAI pinta el artifact en un iframe con `allow-modals`, que es lo que permite abrir
+el diálogo de impresión desde dentro.
+
+```html
+<button class="no-imprimir" onclick="window.print()">Exportar a PDF</button>
+<style>
+  @media print {
+    .no-imprimir { display: none; }
+    body { background: #fff; color: #000; }
+    .pagina { break-inside: avoid; }
+  }
+  @page { margin: 15mm; }
+</style>
+```
+
+El usuario elige «Guardar como PDF» en el diálogo del navegador.
+
+## Si el artifact tiene varias vistas, exporta SOLO la que se está viendo
+
+Un panel con pestañas no debe imprimir las pestañas ocultas: salen paginas en blanco o, peor,
+contenido que el usuario no estaba mirando. Marca lo imprimible y esconde el resto:
+
+```html
+<section class="vista" data-vista="resumen">…</section>
+<section class="vista" data-vista="detalle" hidden>…</section>
+
+<style>
+  @media print {
+    /* Solo la vista visible llega al PDF. */
+    .vista[hidden] { display: none !important; }
+    nav, .filtros, .no-imprimir { display: none; }
+  }
+</style>
+```
+
+Si una vista **no** tiene sentido en papel —un mapa interactivo, un formulario— dilo en la
+interfaz en vez de imprimirla mal: deshabilita el botón para esa vista, o añade un
+`@media print` que la sustituya por una nota corta.
+
+## Antes de dar el botón por bueno
+
+- **Las gráficas se imprimen desde el canvas ya pintado.** Si la librería redibuja al cambiar el
+  tamaño, escucha `beforeprint` y fuerza un `resize`/`update`; si no, el PDF sale con la gráfica
+  del tamaño anterior.
+- **Los colores de fondo se pierden.** El navegador no imprime fondos por omisión. Para una
+  tabla con filas alternas o un badge de color, usa `print-color-adjust: exact` en ese elemento.
+- **Nada de `position: fixed`** en lo que deba salir: se repite o desaparece.
+
+## Si generas el fichero desde JavaScript
+
+jsPDF o html2pdf desde cdnjs. Ten en cuenta que la descarga dentro del iframe depende de
+`allow-downloads`, que el widget sí pone. Aun así `window.print()` falla en menos sitios y no
+gasta presupuesto del tope de 5 MB en una librería.

package/skills/artifacts-builder/reference/graficas.md

@@ -0,0 +1,22 @@
+# Gráficas interactivas
+
+Chart.js desde cdnjs, versión fijada. Los datos van horneados: no hay red.
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.0/chart.umd.min.js"></script>
+<canvas id="ventas"></canvas>
+<script>
+  const DATOS = [/* horneado en tiempo de generación */];
+  new Chart(document.getElementById('ventas'), {
+    type: 'bar',
+    data: { labels: DATOS.map(d => d.mes), datasets: [{ data: DATOS.map(d => d.total) }] },
+    options: { responsive: true, plugins: { legend: { display: false } } }
+  });
+</script>
+```
+
+**Interactividad sin red:** filtra el array en memoria y llama a `chart.update()`. Todo el
+dataset ya está en la página.
+
+**Tema:** lee `window.matchMedia('(prefers-color-scheme: dark)')` y pásale los colores a
+`options.scales` y `options.plugins.legend.labels.color`.