O que syokan faz?
syokan (召喚, "invocar") é um verbo — LLMs invocam UI rica. Quando o usuário diz "syokan X" (JA: 「Xを syokan」), isso é um pedido para invocar esses dados em uma visualização. Por baixo dos panos, é uma camada de visualização orientada por esquema: em vez de escrever JSX, você profere uma invocação JSON — uma árvore de componentes do catálogo — e o syokan a renderiza com componentes predefinidos. Seu trabalho é montar os dados em um envelope e fazer POST para o syokan. Em prosa, use syokan como um verbo transitivo nu (nunca "faça syokan" / nunca 「syokan する」 — syokan se sustenta sozinho).
Se o syokan ainda não estiver instalado (syokan --help falhar), ou o usuário disser "onboarding", "configurar" ou "primeira vez usando", guie-o por references/onboarding.md até o primeiro snapshot. Não execute operações que alterem o ambiente silenciosamente, como instalações: relate que não está instalado e obtenha a aprovação do usuário antes de executar (nunca instale por conta própria).
Inegociáveis
- Snapshots são efêmeros: um snapshot enviado não tem garantia de persistência. Coloque apenas dados reconstruíveis e transitórios lá (RSS de hoje, uma revisão em andamento, etc.). Para layouts que você reutiliza, salve um template para reproduzi-los (templates persistem — veja "Templates para reprodutibilidade" abaixo).
- Apenas JSON: o servidor aceita nada além de um envelope JSON. Markdown bruto ou texto simples é rejeitado. Para mostrar prosa, envolva-a em um nó
MarkdownDocouPlainText. - Esquema estrito: as props são validadas rigorosamente. Chaves que não estão no esquema são rejeitadas — não invente chaves extras.
- Folhas não podem ter filhos: apenas
StackeCardaceitam filhos. Anexar filhos a um nó folha é rejeitado na ingestão.
Da composição à visualização
- Verifique os tipos e props disponíveis com
syokan catalog(veja "Catálogo" abaixo). - Mapeie os dados que você quer mostrar para esses componentes. O nível superior geralmente é um contêiner (
Stacketc.) empilhando itens verticalmente. - Transforme-o em um envelope JSON (veja "Forma do envelope" abaixo). Apenas
rooté obrigatório. - Envie-o com a CLI (veja "Envio" abaixo). Em caso de sucesso, a URL da visualização é impressa.
Se você já construiu uma visualização semelhante antes, não comece do zero — baseie-se em um template salvo (veja "Templates para reprodutibilidade" abaixo).
Forma do envelope
Apenas o seguinte pode ir no corpo do POST.
Nunca inclua id, createdAt ou url — o servidor os atribui.
{
"root": { "type": "Stack", "props": {}, "children": [ /* nós do catálogo; exemplos completos em references/examples.md */ ] }, // obrigatório. a árvore de visualização
"title": "RSS de hoje", // opcional. mostrado na lista e no cabeçalho da visualização
"metadata": { "source": { "label": "daily-rss" } }, // opcional. rótulo de proveniência
"schemaVersion": 1, // opcional. o servidor o preenche
"idempotencyKey": "rss-2026-06-28" // opcional. nomeia esta visualização para que possa ser atualizada depois em vez de duplicada
}
metadata.source aceita chaves extras além de label; você pode adicionar url ou fetchedAt (ex.: { "label": "gh-review", "url": "https://exemplo.com/..." }).
Para visualizações diárias ou recorrentes, inclua algo como a data no idempotencyKey. A CLI do syokan cuida do resto: ela primeiro tenta essa chave, e só cria uma nova visualização se nenhuma existir ainda — então a primeira postagem cria a visualização e toda postagem posterior com a mesma chave atualiza essa mesma visualização no lugar, em vez de duplicá-la. Você não precisa rastrear se é a primeira postagem. (Se você chamar a API HTTP diretamente em vez da CLI: POST /api/snapshots sempre cria e marca a chave; PUT /api/snapshots atinge uma chave existente e retorna 404 se ela ainda não estiver lá — não há endpoint create-on-miss, e por isso a CLI tenta PUT primeiro e recai para POST em caso de 404.)
Catálogo
Obtenha os types disponíveis e suas definições de props a partir de syokan catalog (nunca os transcreva para md — extraia-os daqui toda vez).
A saída é { "items": [{ "type", "props", "childrenTypes" }] }.
props: as props do tipo como JSON Schema. Satisfaçarequired/enum/format(httpUrl éuri,Time.datetimeédate-time) /additionalProperties:false(chaves desconhecidas são rejeitadas) exatamente como fornecido.childrenTypes:nullsignifica um contêiner que aceita filhos,[]significa uma folha que não aceita nenhum,[..]significa que apenas os tipos listados podem ser filhos.
Para exemplos completos combinando os componentes, veja references/examples.md.
Envio
Passe o envelope montado como um arquivo ou via stdin; em caso de sucesso, a URL da visualização é impressa no stdout (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).
Para todo o resto — comandos, subcomandos, variáveis de ambiente, códigos de saída — consulte syokan --help --json; para tipos e props, syokan catalog.
Visualizando arquivos locais
Para um arquivo local, syokan <caminho> é o caminho mais curto — você invoca o próprio arquivo. O envelope JSON é enviado como está; qualquer outra coisa (markdown / log / txt / json, ...) é automaticamente encapsulada em um FileDoc ao vivo. A CLI o resolve para um caminho absoluto e o entrega ao servidor, que lê o conteúdo e infere o formato a partir da extensão (.md/.markdown → markdown, .json → código, todo o resto → texto). Enquanto a visualização estiver aberta, ela segue as edições no arquivo (sem necessidade de reenvio).
syokan notas.md # renderiza markdown; a visualização é atualizada a cada salvamento
syokan app.log # mostra um log crescente em monoespaçada
Para combinar vários arquivos em uma única visualização, ou misturá-los com Heading e outros nós, coloque nós FileDoc você mesmo (props: path, apenas caminhos absolutos; FileDoc lida com leitura e rastreamento de alterações).
Por outro lado, para mostrar o conteúdo de um arquivo congelado estaticamente (sem necessidade de acompanhamento, ou você está transformando o conteúdo), coloque o corpo em um nó MarkdownDoc / PlainText / Code. O jq --rawfile o insere sem se preocupar com escaping JSON.
jq -n --rawfile corpo README.md \
'{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$corpo}}]}}' \
| syokan
Templates para reprodutibilidade
Não reconstrua uma visualização favorita do zero toda vez — salve-a como um template no syokan e reutilize-a.
Um template é "o próprio envelope salvo". Você pode colocar marcadores como {{...}} no esqueleto e preenchê-los você mesmo.
Se um template correspondente existir, não construa do zero: encontre o id na lista → busque-o → substitua os dados → envie. Quando você produzir uma nova visualização que vale a pena manter, salve-a e reproduza-a na próxima vez. Para a sintaxe dos subcomandos (templates list|add|get|rm), consulte syokan --help --json.