¿Qué hace syokan?
syokan (召喚, "invocar") es un verbo — los LLMs invocan interfaces de usuario enriquecidas. Cuando el usuario dice "syokan X" (JA: 「Xを syokan»), es una solicitud para invocar esos datos en una vista. Internamente es una capa de vista basada en esquemas: en lugar de escribir JSX, pronuncias una invocación JSON — un árbol de componentes del catálogo — y syokan lo renderiza con componentes predefinidos. Tu trabajo es ensamblar los datos en un sobre y hacer POST a syokan. En prosa, usa syokan como verbo transitivo directo (nunca "hacer syokan" / nunca 「syokan する」 — syokan se sostiene por sí solo).
Si syokan aún no está instalado (syokan --help falla), o el usuario dice "onboarding", "configurarlo" o "primera vez que lo uso", guíalo a través de references/onboarding.md hasta su primera instantánea. No ejecutes operaciones que modifiquen el entorno de forma silenciosa, como instalaciones: informa que no está instalado y obtén la aprobación del usuario antes de ejecutar (nunca instales por tu cuenta).
No negociables
- Las instantáneas son efímeras: una instantánea publicada no tiene garantía de persistencia. Solo coloca allí datos reconstruibles y transitorios (RSS de hoy, una revisión en curso, etc.). Para diseños que reutilices, guarda una plantilla para reproducirlos (las plantillas persisten — ver "Plantillas para reproducibilidad" más abajo).
- Solo JSON: el servidor no acepta nada más que un sobre JSON. Markdown sin formato o texto plano son rechazados. Para mostrar prosa, envuélvela en un nodo
MarkdownDocoPlainText. - Esquema estricto: las props se validan estrictamente. Las claves que no están en el esquema son rechazadas — no inventes claves adicionales.
- Las hojas no pueden tener hijos: solo
StackyCardaceptan hijos. Adjuntar hijos a un nodo hoja es rechazado al ingerir.
Desde la composición hasta la visualización
- Verifica los tipos y props disponibles con
syokan catalog(ver "Catálogo" más abajo). - Mapea los datos que quieres mostrar a esos componentes. El nivel superior suele ser un contenedor (
Stack, etc.) apilando elementos verticalmente. - Conviértelo en un sobre JSON (ver "Forma del sobre" más abajo). Solo
rootes obligatorio. - Publícalo con la CLI (ver "Publicación" más abajo). Si tiene éxito, se imprime la URL de la vista.
Si ya has construido una vista similar antes, no empieces desde cero — baséate en una plantilla guardada (ver "Plantillas para reproducibilidad" más abajo).
Forma del sobre
Solo lo siguiente puede ir en el cuerpo del POST.
Nunca incluyas id, createdAt o url — el servidor los asigna.
{
"root": { "type": "Stack", "props": {}, "children": [ /* nodos del catálogo; ejemplos completos en references/examples.md */ ] }, // obligatorio. el árbol de la vista
"title": "RSS de hoy", // opcional. se muestra en la lista y en el encabezado de la vista
"metadata": { "source": { "label": "daily-rss" } }, // opcional. etiqueta de procedencia
"schemaVersion": 1, // opcional. el servidor lo completa
"idempotencyKey": "rss-2026-06-28" // opcional. nombra esta vista para que pueda actualizarse más tarde en lugar de duplicarse
}
metadata.source admite claves adicionales además de label; puedes agregar url o fetchedAt (ej.: { "label": "gh-review", "url": "https://example.com/..." }).
Para vistas diarias o recurrentes, incluye algo como la fecha en el idempotencyKey. La CLI de syokan maneja el resto: primero apunta a esa clave, y solo crea una nueva vista si ninguna existe aún — así la primera publicación crea la vista y cada publicación posterior con la misma clave actualiza esa misma vista en su lugar en lugar de duplicarla. No necesitas rastrear si es la primera publicación tú mismo. (Si llamas a la API HTTP directamente en lugar de a la CLI: POST /api/snapshots siempre crea y etiqueta la clave; PUT /api/snapshots apunta a una clave existente y devuelve 404 si aún no está — no hay un endpoint que cree si no existe, por eso la CLI primero intenta PUT y recurre a POST si recibe un 404.)
Catálogo
Obtén los types disponibles y sus definiciones de props desde syokan catalog (nunca los transcribas a md — obténlos de aquí cada vez).
La salida es { "items": [{ "type", "props", "childrenTypes" }] }.
props: las props del tipo como JSON Schema. Cumple conrequired/enum/format(httpUrl esuri,Time.datetimeesdate-time) /additionalProperties:false(las claves desconocidas son rechazadas) exactamente como se indica.childrenTypes:nullsignifica que es un contenedor que acepta hijos,[]significa que es una hoja que no acepta ninguno,[..]significa que solo los tipos listados pueden ser hijos.
Para ejemplos completos que combinan los componentes, consulta references/examples.md.
Publicación
Pasa el sobre ensamblado como archivo o mediante stdin; si tiene éxito, la URL de la vista se imprime en stdout (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).
Para todo lo demás — comandos, subcomandos, variables de entorno, códigos de salida — consulta syokan --help --json; para tipos y props, syokan catalog.
Vista previa de archivos locales
Para un archivo local, syokan <ruta> es la ruta más corta — invocas el archivo mismo. El JSON del sobre se publica tal cual; cualquier otra cosa (markdown / log / txt / json, ...) se envuelve automáticamente en un FileDoc en vivo. La CLI lo resuelve a una ruta absoluta y se la entrega al servidor, que lee el contenido e infiere el formato a partir de la extensión (.md/.markdown → markdown, .json → código, todo lo demás → texto). Mientras la vista está abierta, sigue los cambios del archivo (sin necesidad de volver a publicar).
syokan notas.md # renderiza markdown; la vista se actualiza en cada guardado
syokan app.log # muestra un log creciente en monoespaciado
Para combinar varios archivos en una sola vista, o mezclarlos con Heading y otros nodos, coloca tú mismo los nodos FileDoc (props: path, solo rutas absolutas; FileDoc maneja la lectura y el seguimiento de cambios).
Por el contrario, para mostrar el contenido de un archivo congelado estáticamente (sin necesidad de seguimiento, o si estás transformando el contenido), coloca el cuerpo en un nodo MarkdownDoc / PlainText / Code. jq --rawfile lo introduce sin preocuparse por el escape JSON.
jq -n --rawfile body README.md \
'{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
| syokan
Plantillas para reproducibilidad
No reconstruyas una vista favorita desde cero cada vez — guárdala como plantilla en syokan y reutilízala.
Una plantilla es "el sobre guardado en sí mismo". Puedes colocar marcadores como {{...}} en el esqueleto y completarlos tú mismo.
Si existe una plantilla que coincida, no construyas desde cero: encuentra el id en la lista → obténla → intercambia los datos → publica. Cuando produzcas una nueva vista que valga la pena conservar, guárdala y reprodúcela la próxima vez. Para la sintaxis de subcomandos (templates list|add|get|rm), consulta syokan --help --json.