Folio
Leia a solicitação e qualquer artefato existente antes de escrever HTML. Cada dependência externa e URL de publicação pertence ao ledger do manifesto. Artefatos são documentos estáticos — eles não chamam APIs.
Quando usar folio — e quando não usar
Folio é para entregáveis web duráveis, abríveis e compartilháveis — coisas que o usuário guardará, reabrirá ou entregará a outra pessoa.
Use folio quando:
- O usuário solicitar um doc, dashboard, planilha, deck ou página que ele salvará ou enviará
- A saída é um entregável, não uma olhada rápida ("faça um relatório para mim", "construa um dashboard para o time", "coloque isso online", "eu quero uma página que…")
- O usuário invocar um verbo explicitamente (
folio publish,folio audit,folio remix,folio describe)
Não use folio quando:
- O usuário quiser uma olhada rápida, não um entregável ("mostre-me", "como isso fica", "só verifique", "você pode exibir")
- A saída não será aberta novamente após esta conversa — responda inline ou escreva um arquivo de rascunho, não carimbe, registre ou gateie
- A solicitação for para um trecho de código, arquivo de configuração, uma única função — esses não são artefatos de navegador
Portão de entrada. Antes de entrar no fluxo de artefato, pergunte: o usuário abrirá este arquivo novamente após esta sessão? Se não, folio é a ferramenta errada — apenas responda. Se sim, prossiga.
Autônomo é o padrão. O caminho mais leve do folio é uma única pasta com um index.html — sem raiz de site, sem site.json, sem página de índice. Uma raiz de site aparece apenas quando há um segundo artefato ou o usuário pede para publicar uma coleção. Não crie cerimônia de site para um arquivo.
Glossário
Use apenas estes termos na saída do Folio.
| Termo | Significado |
|---|---|
| artefato | Um entregável web estático autocontido: HTML com CSS/JS, executável em um navegador |
| pacote | Um de single-file (CSS/JS inline) ou multi-file (assets vinculados em um diretório) |
| tipo de artefato | Um de doc, planilha, dashboard, explicador, slides, ferramenta, landing |
| perfil de host | Onde o site vive de forma durável: local, surge, gh-pages, cf-pages, cf-worker |
| compartilhar (túnel) | Uma URL pública temporária para o servidor local em execução, via localhost.run (padrão) ou ngrok. Efêmera, a máquina continua sendo o host — não uma publicação |
| raiz de site | Um diretório contendo um index.html e uma árvore artifacts/, publicado como um domínio. Artefatos são caminhos sob ele, não subdomínios separados. |
| manifesto do site | .folio/site.json — a fonte canônica da verdade. Carrega domínio + registro por artefato (slug, tipo, pacote, ledger, proveniência, estado de publicação). Carimbos, índice e auditoria derivam dele. |
| artefato autônomo | Um artefato sem raiz de site. O carimbo HTML é seu único manifesto. Atualiza para uma entrada de site quando um segundo artefato aparece. |
| proveniência | O campo source em um artefato remixado: { slug, site, url }. Nulo para originais. Lido por describe, audit e remix. |
| manifesto | HTML de entrada, lista de arquivos, deps externos e metadados opcionais de publicação |
| ledger | O ledger do manifesto — deps, arquivos de dados, URLs e níveis de evidência antes da construção |
| gate | Uma verificação binária que deve passar antes da entrega |
| nível de evidência | Um de observed (observado), derived (derivado), stated (declarado), absent (ausente) |
Como usar esta habilidade
- Padrão: criar ou atualizar um artefato. Siga o fluxo de artefato. Um único artefato é autônomo por padrão — nenhuma raiz de site necessária.
folio audit <caminho|url>: auditoria somente leitura. Não edite. Leiareferences/verbs/audit.md.folio describe <caminho|url|slug>: leia a entrada do manifesto de um artefato (tipo, ledger, proveniência, estado de publicação). Leiareferences/verbs/describe.md.folio share <raiz-do-site>: abra um link temporário público para o site em execução local via um túnel (padrão localhost.run — sem instalação, sem conta; alternativa--ngrok). A máquina continua sendo o host; a URL morre com o processo. Use isso para "deixar alguém ver agora", não para publicar. Leiareferences/verbs/share.md.folio publish <raiz-do-site>: implante uma raiz de site (todos os artefatos) no perfil de host escolhido para hospedagem durável em outro lugar. Regere o índice primeiro (scripts/gen-index.js), depois implante. Leiareferences/verbs/publish.md.folio remix <caminho|url>: bifurque um artefato e mude-o enquanto preserva a honestidade do manifesto e registra a linhagem da fonte. Leiareferences/verbs/remix.md.
Uma execução = um artefato a menos que o usuário nomeie vários. Prefira o menor pacote que atenda à solicitação. Um único artefato é autônomo; vários artefatos vivem sob uma raiz de site e publicam como um domínio. Leia references/site-index.md para o modelo de raiz de site e atualização de autônomo para site.
Disciplinas inegociáveis
- Funcionável antes de bonito. O artefato abre em um navegador e as interações principais funcionam antes de polir ou publicar.
- Apenas documentos estáticos. Sem
fetch()para APIs externas, sem conexões WebSocket, semXMLHttpRequestpara endpoints ativos. Dados são embutidos inline, carregados de um arquivo local viafetch('./data/…'), ou gerados em tempo de construção. As únicas requisições de rede que um artefato faz são para scripts, estilos e fontes de CDN registrados no ledger. - Honestidade do manifesto. Scripts, fontes, imagens e arquivos de dados de CDN são linhas do ledger, não surpresas.
- Local primeiro, depois compartilhar, depois publicar. Perfil de host padrão é
local. Execute da maneira dinâmica —node <folio-skill>/scripts/serve.js <raiz-do-site>garante a pastaartifacts/, regera a página de índice/pesquisa a partir do ledger, escolhe uma porta disponível e serve sobre HTTP (file://simples é suficiente para um único arquivo totalmente inline, mas quebrafetche imports de módulo). Leiareferences/local-server.md. Para mostrar a alguém agora, abra um túnel temporário —node <folio-skill>/scripts/share.js <raiz-do-site>(padrão localhost.run, sem instalação/conta); o link é efêmero e a máquina continua sendo o host. Hospedagem durável em outro lugar épublish— apenas quando o usuário solicitar oufolio publishfor invocado. Nunca anuncie capacidades de compartilhamento ou publicação proativamente. - Sem segredos em arquivos estáticos. Chaves de API, tokens e URLs privados não pertencem a HTML/JS commitados ou publicados.
- Não feio. Artefatos seguem a linha de base visual. Leia
references/visual-baseline.mdantes da construção.
Rastreamento de decisão de ouro
Solicitação: Construa um histograma de latência interativo a partir deste CSV para um colega de equipe.
Inventário:
· Alvo: novo artefato `latency-hist`
· Existente: nenhum
· Dados: usuário anexou `runs.csv` (observado, 840 linhas)
· Restrições: pasta local, sem publicação
Escolhas: tipo=explicador · pacote=multi-file · host=local · público=colega entrega
Ledger:
dep | tipo | evidência | no artefato como
d3@7 (cdn.jsdelivr) | script | declarado, usuário não fixou | tag script em index.html + nota no README
runs.csv | dado | observado | ./data/runs.csv, carregado via fetch('./data/runs.csv')
Plano de arquivos:
Criar: artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
Sem exclusões.
Verificação: npx serve artifacts/latency-hist; gráfico renderiza; console limpo
Gates: opens-locally=sim, console-clean=sim, ledger-complete=sim, no-secrets=sim, mock-labeled=n/a, visual-baseline=sim
Entrega: caminho, como abrir, resumo do ledger, adiado: nenhum
Bifurcação de escopo
Resolva o escopo antes de perguntas amplas de design.
| Forma da solicitação | Pacote | Host | Pular |
|---|---|---|---|
| Demonstração rápida descartável | single-file | local | README, publicação, múltiplas páginas |
| Documento ou relatório escrito | single-file ou multi-file | local | Gráficos, JS pesado |
| Tabela de dados ou planilha | single-file ou multi-file | local | Prosa narrativa, decoração |
| Dashboard de métricas | multi-file | local | CRUD completo, feeds de dados ao vivo |
| Explicador de conceito | multi-file | local | Despejos densos de dados brutos |
| Deck de slides | multi-file | local | Layouts de rolagem, widgets |
| Artefato compartilhado com colega | multi-file | local | Etapa de construção de framework |
| Mostrar a alguém agora | single-file ou multi-file | share (túnel) | Cerimônia de implantação, host durável |
| Link público durável | multi-file | surge ou cf-pages | Autenticação, lógica de servidor |
| Pré-visualização de entrega para agente | single-file preferido | local | Compartilhar/publicar a menos que solicitado |
Solicitação ambígua: pergunte uma vez, de forma concisa. Exemplo: "Arquivo único autocontido ou uma pequena pasta com CSS/JS separados?" Se não respondido, escolha o menor pacote que funcione.
Fluxo de artefato
0. Inventário
Leia a solicitação e qualquer árvore de artefato existente. Leia references/evidence.md e references/artifact-types.md.
Colete:
- Assunto: o que o artefato deve mostrar ou permitir que o usuário faça
- Entradas: arquivos, JSON, CSV, cópia, restrições de design (com níveis de evidência)
- Artefato existente: caminho, HTML de entrada, manifesto, última URL de publicação (se houver)
- Perfil de host: padrão
local; leiareferences/host-profiles.mdquando publicação estiver no escopo - Fonte de convenção:
folio.mdse presente
Emita um inventário compacto com citações antes de prosseguir.
1. Escolhas
Emita antes de construir: Escolhas: tipo=<x> · pacote=<y> · host=<z> · público=<a>.
Leia references/artifact-types.md quando o tipo não estiver claro. Leia references/host-profiles.md quando o host não for local.
2. Ledger do manifesto
Construa o ledger antes de escrever HTML. Leia references/manifest-ledger.md.
Colunas:
dep | tipo | evidência | no artefato como
Tipos: script, style, font, image, data, mock, publish-target.
Arquivos de dados e dados mock devem ser explícitos. Chamadas de API externas estão fora de escopo — veja disciplina #2.
3. Plano de arquivos e construção
Declare o plano de arquivos antes de editar:
Criar: artifacts/<slug>/index.html, app.js, data/sample.json
Modificar: nenhum
Sem exclusões.
Comece a partir de um template. Carregue references/templates/<tipo>.html e adapte-o — substitua o conteúdo {{placeholder}} e os marcadores <!-- Replace: ... --> por conteúdo real. Templates são artefatos folio que passam por gates; eles carregam o bloco de token, o alternador claro/escuro, o favicon e a estrutura específica do tipo. Leia o índice references/templates/ para saber o que cada template oferece.
Leia references/visual-baseline.md antes de escrever CSS.
Construa com HTML/CSS/JS puro a menos que o usuário tenha nomeado uma pilha específica. Prefira:
- HTML semântico, um arquivo de entrada óbvio (
index.html) - Propriedades customizadas CSS para todos os tokens visuais (cor, tipo, espaçamento, raio, sombra)
- OKLCH para cor; sem hex/rgb inline fora do bloco de token
:root - JS vanilla ou uma única biblioteca de CDN nomeada — registrada no ledger
multi-file: mantenha todos os caminhos de assets relativos; sem caminhos de máquina absolutos- Sem títulos em itálico; medida legível (
max-width: 60–70ch);overflow-x: clipemhtmlebody
Leia references/security.md quando o artefato aceitar entrada do usuário, incorporar conteúdo de terceiros ou publicar publicamente.
Carimbos (comentário HTML, no topo do arquivo de entrada):
<!-- Folio · slug: latency-hist · tipo: explicador · pacote: multi-file · host: local -->
<!-- deps: d3@7 · dados: runs.csv · publicação: nenhum -->
Para single-file, mantenha o carimbo mínimo (uma linha).
4. Verificação
Leia references/verification.md. Execute verificações que se ajustem ao perfil de host.
Matriz mínima:
verificação | comando/evidência | resultado | notas
Exemplos: servidor estático + carregar URL de entrada, console DevTools limpo, clique na interação primária, varredura de links quebrados, nota file:// vs servidor para fetch, verificação pontual de visual-baseline.
5. Gates
Aplique antes da entrega. Qualquer não aciona um loop de correção.
| Gate | Verificação |
|---|---|
opens-locally | HTML de entrada carrega via servidor estático (ou ressalva honesta file:// documentada); para configuração do servidor veja references/local-server.md (scripts/serve.js é o caminho de um comando) |
console-clean | Sem erros não capturados no caminho primário |
ledger-complete | Cada dep externo e fonte de dados aparece no ledger |
no-secrets | Sem chaves, tokens ou URLs privados no código fonte |
mock-labeled | Dados mock/de amostra rotulados quando dados reais estão ausentes |
static-only | Sem fetch() para APIs externas, sem WebSocket, sem XHR para endpoints ativos |
visual-baseline | Bloco de token presente, sem cores inline fora de :root, sem títulos em itálico, contraste adequado |
publish-ready | Ao publicar: etapas do perfil de host documentadas e verificadas ou explicitamente adiadas |
manifest-derivation | Aviso. Carimbo HTML (slug, tipo, pacote) corresponde à entrada site.json para este artefato. Sinaliza desvio; veja references/verification.md#manifest-derivation-check. |
Leia references/slop-test.md após construir. Corrija P0/P1 antes da entrega.
6. Publicação (opcional)
Apenas quando o usuário solicitar publicação ou invocar folio publish. Leia references/verbs/publish.md e o arquivo profundo do perfil de host.
Registre a URL de publicação no manifesto e na entrega. Nunca reivindique uma URL sem evidência da saída do comando de publicação.
7. Entrega
Inclua:
- Caminho do artefato e arquivo de entrada
- Como abrir localmente (comando exato)
- URL de publicação (se publicada), com evidência
- Resumo do ledger do manifesto
- Comandos e resultados de verificação
- Itens adiados (ex.:
fetchrequer servidor, dados mock em uso)
Não enterre fatos do manifesto ou publicação sob conversa fiada de implementação.
Contrastes RUIM/BOM
RUIM: Conectar fetch('/api/users') porque dashboards geralmente carregam usuários de uma API.
BOM: Embutir data/users.json com um rótulo visível "Dados de amostra". Sem chamadas de API.
RUIM: Colar Google Analytics, fontes e três libs de CDN sem listá-las. BOM: Cada dep é uma linha do ledger com URL e propósito.
RUIM: "Implantado em https://demo.example.com" sem executar o comando de publicação. BOM: URL de publicação copiada da saída do comando, ou marcada como adiada.
RUIM: Valores oklch() inline espalhados pelo CSS, três declarações diferentes de font-family.
BOM: Todos os valores visuais no bloco de token :root, referenciados via var().
Artefatos de convenção
folio.md (diretório de saída, host padrão, lista de permissão CDN, nomeação): opt-in. Leia references/folio-md.md. Uma vez presente, os padrões da casa vencem.
Layout opcional por projeto:
artifacts/
<slug>/
index.html
...
.folio/
site.json
...
O conteúdo completo do SKILL.md continua com referências detalhadas, exemplos e guias de solução de problemas. Consulte os arquivos de referência para informações aprofundadas.