Folio
Lee la solicitud y cualquier artefacto existente antes de escribir HTML. Toda dependencia externa y URL de publicación pertenece al libro de contabilidad del manifiesto. Los artefactos son documentos estáticos — no llaman a APIs.
Cuándo usar folio — y cuándo no
Folio es para entregables web duraderos, abribles y compartibles — cosas que el usuario guardará, reabrirá o entregará a otra persona.
Usa folio cuando:
- El usuario pide un documento, panel, hoja, presentación o página que guardará o enviará
- La salida es un entregable, no una vista rápida ("hazme un informe", "construye un panel para el equipo", "pon esto en línea", "quiero una página que…")
- El usuario invoca un verbo explícitamente (
folio publish,folio audit,folio remix,folio describe)
No uses folio cuando:
- El usuario quiere una vista rápida, no un entregable ("muéstrame", "cómo se ve esto", "solo verifica", "puedes mostrar")
- La salida no se volverá a abrir después de esta conversación — responde inline o escribe un archivo temporal, no lo selles, lo lleves en libro contable o lo sometas a compuertas
- La solicitud es para un fragmento de código, un archivo de configuración, una función única — esos no son artefactos de navegador
Compuerta de entrada. Antes de entrar en el flujo de artefactos, pregúntate: ¿el usuario abrirá este archivo nuevamente después de esta sesión? Si no, folio es la herramienta equivocada — solo responde. Si sí, continúa.
Independiente es el valor predeterminado. La ruta más ligera de folio es una única carpeta con un index.html — sin raíz del sitio, sin site.json, sin página de índice. Una raíz del sitio aparece solo cuando hay un segundo artefacto o el usuario pide publicar una colección. No crees ceremonia de sitio para un solo archivo.
Glosario
Usa solo estos términos en la salida de Folio.
| Término | Significado |
|---|---|
| artefacto | Un entregable web estático auto-contenido: HTML con CSS/JS, ejecutable en un navegador |
| paquete | Uno de single-file (CSS/JS inline) o multi-file (activos vinculados en un directorio) |
| tipo de artefacto | Uno de doc, sheet, dashboard, explainer, slides, tool, landing |
| perfil de alojamiento | Dónde vive el sitio de forma duradera: local, surge, gh-pages, cf-pages, cf-worker |
| compartir (túnel) | Una URL pública temporal al servidor local en ejecución, mediante localhost.run (predeterminado) o ngrok. Efímero, la máquina sigue siendo el host — no es una publicación |
| raíz del sitio | Un directorio que contiene un index.html y un árbol artifacts/, publicado como un solo dominio. Los artefactos son rutas debajo de él, no subdominios separados. |
| manifiesto del sitio | .folio/site.json — la fuente de verdad canónica. Lleva el dominio + registro por artefacto (slug, tipo, paquete, libro contable, procedencia, estado de publicación). Los sellos, índice y auditoría se derivan de él. |
| artefacto independiente | Un artefacto sin raíz del sitio. El sello HTML es su único manifiesto. Se actualiza a una entrada del sitio cuando aparece un segundo artefacto. |
| procedencia | El campo source en un artefacto remezclado: { slug, site, url }. Nulo para originales. Leído por describe, audit y remix. |
| manifiesto | HTML de entrada, lista de archivos, dependencias externas y metadatos de publicación opcionales |
| libro contable | El libro contable del manifiesto — dependencias, archivos de datos, URLs y niveles de evidencia antes de la construcción |
| compuerta | Una verificación binaria que debe pasar antes de la entrega |
| nivel de evidencia | Uno de observed, derived, stated, absent |
Cómo usar esta habilidad
- Predeterminado: crear o actualizar un artefacto. Sigue el flujo del artefacto. Un único artefacto es independiente por predeterminado — no se requiere raíz del sitio.
folio audit <ruta|url>: auditoría de solo lectura. No edites. Leereferences/verbs/audit.md.folio describe <ruta|url|slug>: lee la entrada del manifiesto del artefacto (tipo, libro contable, procedencia, estado de publicación). Leereferences/verbs/describe.md.folio share <raíz-del-sitio>: abre un enlace público temporal al sitio que se ejecuta localmente mediante un túnel (predeterminado localhost.run — sin instalación, sin cuenta; alternativa--ngrok). La máquina sigue siendo el host; la URL muere con el proceso. Úsalo para "que alguien lo vea ahora mismo", no para publicar. Leereferences/verbs/share.md.folio publish <raíz-del-sitio>: despliega una raíz del sitio (todos los artefactos) en el perfil de alojamiento elegido para alojamiento duradero en otro lugar. Regenera el índice primero (scripts/gen-index.js), luego despliega. Leereferences/verbs/publish.md.folio remix <ruta|url>: bifurca un artefacto y cámbialo preservando la honestidad del manifiesto y registrando el linaje de origen. Leereferences/verbs/remix.md.
Una ejecución = un artefacto a menos que el usuario nombre varios. Prefiere el paquete más pequeño que satisfaga la solicitud. Un único artefacto es independiente; varios artefactos viven bajo una raíz del sitio y se publican como un solo dominio. Lee references/site-index.md para el modelo de raíz del sitio y la actualización de independiente a sitio.
Disciplinas no negociables
- Funcionable antes que bonito. El artefacto se abre en un navegador y las interacciones principales funcionan antes del pulido o la publicación.
- Solo documentos estáticos. Sin
fetch()a APIs externas, sin conexiones WebSocket, sinXMLHttpRequesta endpoints en vivo. Los datos se incrustan inline, se cargan desde un archivo local mediantefetch('./data/…')o se generan en tiempo de construcción. Las únicas solicitudes de red que hace un artefacto son a scripts, estilos y fuentes de CDN registrados en el libro contable. - Honestidad del manifiesto. Los scripts, fuentes, imágenes y archivos de datos de CDN son filas del libro contable, no sorpresas.
- Local primero, luego compartir, luego publicar. El perfil de alojamiento predeterminado es
local. Ejecútalo de forma dinámica —node <folio-skill>/scripts/serve.js <raíz-del-sitio>asegura la carpetaartifacts/, regenera la página de índice/búsqueda desde el libro contable, elige un puerto abierto y sirve sobre HTTP (unfile://simple está bien para un archivo único completamente inline, pero rompefetche importaciones de módulos). Consultareferences/local-server.md. Para mostrar a alguien ahora mismo, abre un túnel temporal —node <folio-skill>/scripts/share.js <raíz-del-sitio>(predeterminado localhost.run, sin instalación/cuenta); el enlace es efímero y la máquina sigue siendo el host. El alojamiento duradero en otro lugar espublish— solo cuando el usuario lo pide o se invocafolio publish. Nunca ofrezcas capacidades de compartir o publicar de forma proactiva. - Sin secretos en archivos estáticos. Las claves de API, tokens y URLs privadas no pertenecen a HTML/JS que se commitea o publica.
- No feo. Los artefactos siguen la línea base visual. Lee
references/visual-baseline.mdantes de construir.
Traza de decisión dorada
Solicitud: Construye un histograma de latencia interactivo a partir de este CSV para un compañero de equipo.
Inventario:
· Objetivo: nuevo artefacto `latency-hist`
· Existente: ninguno
· Datos: usuario adjuntó `runs.csv` (observado, 840 filas)
· Restricciones: carpeta local, sin publicación
Elecciones: tipo=explainer · paquete=multi-file · host=local · audiencia=entrega a compañero
Libro contable:
dep | tipo | evidencia | en artefacto como
d3@7 (cdn.jsdelivr) | script | establecido, usuario no fijó | etiqueta script en index.html + nota en README
runs.csv | datos | observado | ./data/runs.csv, cargado mediante fetch('./data/runs.csv')
Plan de archivos:
Crear: artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
Sin eliminaciones.
Verificación: npx serve artifacts/latency-hist; el gráfico se renderiza; consola limpia
Compuertas: se-abre-localmente=sí, consola-limpia=sí, libro-contable-completo=sí, sin-secretos=sí, simulación-etiquetada=n/a, línea-base-visual=sí
Entrega: ruta, cómo abrir, resumen del libro contable, diferido: ninguno
Bifurcación de alcance
Resuelve el alcance antes de preguntas de diseño amplias.
| Forma de solicitud | Paquete | Host | Omitir |
|---|---|---|---|
| Demostración rápida desechable | single-file | local | README, publicar, múltiples páginas |
| Documento o informe escrito | single-file o multi-file | local | Gráficos, JS pesado |
| Tabla de datos u hoja | single-file o multi-file | local | Prosa narrativa, decoración |
| Panel de métricas | multi-file | local | CRUD completo, fuentes de datos en vivo |
| Explicador de conceptos | multi-file | local | Volcados de datos densos |
| Presentación de diapositivas | multi-file | local | Diseños de desplazamiento, widgets |
| Artefacto compartido con compañero | multi-file | local | Paso de construcción de framework |
| Mostrar a alguien ahora mismo | single-file o multi-file | share (túnel) | Ceremonia de despliegue, host duradero |
| Enlace público duradero | multi-file | surge o cf-pages | Autenticación, lógica de servidor |
| Vista previa de entrega de agente | single-file preferido | local | Compartir/publicar a menos que se pida |
Solicitud ambigua: pregunta una vez, de forma concisa. Ejemplo: "¿Archivo único auto-contenido o una carpeta pequeña con CSS/JS separados?" Si no se responde, elige el paquete más pequeño que funcione.
Flujo del artefacto
0. Inventario
Lee la solicitud y cualquier árbol de artefactos existente. Lee references/evidence.md y references/artifact-types.md.
Recopila:
- Asunto: qué debe mostrar el artefacto o permitir hacer al usuario
- Entradas: archivos, JSON, CSV, texto, restricciones de diseño (con niveles de evidencia)
- Artefacto existente: ruta, HTML de entrada, manifiesto, última URL de publicación si la hay
- Perfil de alojamiento: predeterminado
local; leereferences/host-profiles.mdcuando la publicación está en alcance - Fuente de convención:
folio.mdsi está presente
Emite un inventario compacto con citas antes de continuar.
1. Elecciones
Emite antes de construir: Elecciones: tipo=<x> · paquete=<y> · host=<z> · audiencia=<a>.
Lee references/artifact-types.md cuando el tipo no esté claro. Lee references/host-profiles.md cuando el host no sea local.
2. Libro contable del manifiesto
Construye el libro contable antes de escribir HTML. Lee references/manifest-ledger.md.
Columnas:
dep | tipo | evidencia | en artefacto como
Tipos: script, style, font, image, data, mock, publish-target.
Los archivos de datos y los datos simulados deben ser explícitos. Las llamadas a API externas están fuera de alcance — consulta la disciplina #2.
3. Plan de archivos y construcción
Indica el plan de archivos antes de editar:
Crear: artifacts/<slug>/index.html, app.js, data/sample.json
Modificar: ninguno
Sin eliminaciones.
Empieza desde una plantilla. Carga references/templates/<tipo>.html y adáptalo — reemplaza el contenido {{placeholder}} y los marcadores <!-- Replace: ... --> con contenido real. Las plantillas son artefactos de folio que pasan las compuertas; llevan el bloque de tokens, el interruptor claro/oscuro, el favicon y la estructura específica del tipo. Lee el índice de references/templates/ para ver qué proporciona cada plantilla.
Lee references/visual-baseline.md antes de escribir CSS.
Construye con HTML/CSS/JS simple a menos que el usuario haya nombrado una pila específica. Prefiere:
- HTML semántico, un archivo de entrada obvio (
index.html) - Propiedades personalizadas de CSS para todos los tokens visuales (color, tipo, espaciado, radio, sombra)
- OKLCH para color; sin hex/rgb inline fuera del bloque
:rootde tokens - JS simple o una única biblioteca de CDN nombrada — registrada en el libro contable
multi-file: mantén todas las rutas de activos relativas; sin rutas absolutas de máquina- Sin títulos en cursiva; medida legible (
max-width: 60–70ch);overflow-x: clipenhtmlybody
Lee references/security.md cuando el artefacto acepte entrada del usuario, incruste contenido de terceros o se publique públicamente.
Sellos (comentario HTML, al principio del archivo de entrada):
<!-- Folio · slug: latency-hist · tipo: explainer · paquete: multi-file · host: local -->
<!-- dep: d3@7 · datos: runs.csv · publicar: ninguno -->
Para single-file, mantén el sello mínimo (una línea).
4. Verificación
Lee references/verification.md. Ejecuta las comprobaciones que se ajusten al perfil de alojamiento.
Matriz mínima:
comprobación | comando/evidencia | resultado | notas
Ejemplos: servidor estático + cargar URL de entrada, consola de DevTools limpia, hacer clic en la interacción principal, escaneo de enlaces rotos, nota de file:// vs servidor para fetch, verificación de línea base visual.
5. Compuertas
Aplica antes de la entrega. Cualquier no desencadena un bucle de corrección.
| Compuerta | Comprobación |
|---|---|
se-abre-localmente | El HTML de entrada se carga mediante servidor estático (o advertencia honesta de file:// documentada); para configuración del servidor consulta references/local-server.md (scripts/serve.js es la ruta de un solo comando) |
consola-limpia | Sin errores no capturados en la ruta principal |
libro-contable-completo | Cada dependencia externa y fuente de datos aparece en el libro contable |
sin-secretos | Sin claves, tokens o URLs privadas en el código fuente |
simulación-etiquetada | Datos simulados/de muestra etiquetados cuando los datos reales están ausentes |
solo-estático | Sin fetch() a APIs externas, sin WebSocket, sin XHR a endpoints en vivo |
línea-base-visual | Bloque de tokens presente, sin colores inline fuera de :root, sin títulos en cursiva, contraste adecuado |
listo-para-publicar | Al publicar: pasos del perfil de alojamiento documentados y verificados o diferidos explícitamente |
derivación-del-manifiesto | Asesorativo. El sello HTML (slug, tipo, paquete) coincide con la entrada de site.json para este artefacto. Señala desviación; consulta references/verification.md#manifest-derivation-check. |
Lee references/slop-test.md después de construir. Corrige P0/P1 antes de la entrega.
6. Publicar (opcional)
Solo cuando el usuario solicite publicar o invoque folio publish. Lee references/verbs/publish.md y el archivo profundo del perfil de alojamiento.
Registra la URL de publicación en el manifiesto y la entrega. Nunca reclames una URL sin evidencia de la salida del comando de publicación.
7. Entrega
Incluye:
- Ruta del artefacto y archivo de entrada
- Cómo abrirlo localmente (comando exacto)
- URL de publicación (si se publicó), con evidencia
- Resumen del libro contable del manifiesto
- Comandos y resultados de verificación
- Elementos diferidos (ej.,
fetchrequiere servidor, datos simulados en uso)
No entierres hechos del manifiesto o publicación bajo cháchara de implementación.
Contrastes MAL/BIEN
MAL: Conectar fetch('/api/users') porque los paneles suelen cargar usuarios de una API.
BIEN: Incrustar data/users.json con una etiqueta visible "Datos de muestra". Sin llamadas a API.
MAL: Pegar Google Analytics, fuentes y tres bibliotecas de CDN sin listarlas. BIEN: Cada dependencia es una fila del libro contable con URL y propósito.
MAL: "Desplegado en https://demo.example.com" sin haber ejecutado el comando de publicación. BIEN: URL de publicación copiada de la salida del comando, o marcada como diferida.
MAL: Valores oklch() inline dispersos por el CSS, tres declaraciones font-family diferentes.
BIEN: Todos los valores visuales en el bloque de tokens :root, referenciados mediante var().
Artefactos de convención
folio.md (directorio de salida, host predeterminado, lista blanca de CDN, nomenclatura): opt-in. Lee references/folio-md.md. Una vez presente, las configuraciones predeterminadas de la carpeta ganan.
Diseño opcional por proyecto:
proyecto/
├── .folio/
│ ├── site.json
│ └── references/
└── artifacts/
├── primer-artefacto/
│ ├── index.html
│ ├── app.js
│ ├── style.css
│ └── data/
└── segundo-artefacto/
└── index.html
Referencias profundas
Lee solo los archivos relevantes para la tarea. No leas toda la biblioteca de referencias.
references/artifact-types.md: cuándo usar cada tipo y tipo de paquetereferences/evidence.md: niveles de evidencia para datos y dependenciasreferences/manifest-ledger.md: formato y reglas del libro contablereferences/visual-baseline.md: tokens de diseño, tipografía, color, espaciadoreferences/host-profiles.md: cuándo y cómo usar cada perfil de alojamientoreferences/local-server.md: servir artefactos localmentereferences/verification.md: todas las comprobaciones paso a pasoreferences/security.md: saneamiento de entrada, CSP, sin secretosreferences/slop-test.md: encontrar y priorizar defectosreferences/site-index.md: modelo raíz del sitio y página de índicereferences/folio-md.md: archivo de convención de la carpetareferences/templates/: plantillas de inicio para cada tiporeferences/verbs/audit.mdreferences/verbs/describe.mdreferences/verbs/share.mdreferences/verbs/publish.mdreferences/verbs/remix.md