n3wth/skills

Canvas

canvas.n3wth.com oferece Markdown interativo com uma pré-visualização renderizada, identificado por um slug público. Visualizações abertas no link de compartilhamento são atualizadas quando a fonte é escrita.

Esta skill se comunica com a API do agente HTTP autenticado. Sem navegador. Sem segredos neste arquivo — o chamador fornece CANVAS_AGENT_TOKEN e a URL base do site Convex a partir de seu próprio ambiente.

Quando usar

• Criar uma superfície de trabalho conjunta que outro humano ou agente possa abrir
• Enviar Markdown e devolver um link estável
• Atualizar um canvas existente no local para que abas abertas sejam re-renderizadas
• Ler a fonte atual antes de editar

Variáveis de ambiente que o chamador deve ter

Variável	Significado
CANVAS_SITE_URL	Base HTTP do Convex, ex.: https://.convex.site (sem barra no final)
CANVAS_AGENT_TOKEN	Token compartilhado do tipo bearer, quando o deployment possui um configurado

Links públicos de compartilhamento sempre usam https://canvas.n3wth.com/c/{slug} (não o host do site Convex).

Autenticação: Se CANVAS_AGENT_TOKEN estiver definido no deployment do Convex, toda rota de agente abaixo requer Authorization: Bearer $CANVAS_AGENT_TOKEN. Se o token não estiver definido (local/dev), as mesmas rotas funcionam sem cabeçalho — defina o token em produção.

API

Autenticação em toda rota de agente mutante/leitura:

Authorization: Bearer $CANVAS_AGENT_TOKEN
Content-Type: application/json

Descoberta (sem autenticação):

curl -sS "$CANVAS_SITE_URL/agent/v1"

1. Criar

curl -sS -X POST "$CANVAS_SITE_URL/agent/v1/canvases" \
  -H "Authorization: Bearer $CANVAS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meu canvas",
    "source": "# Olá\n\nIsto é **Markdown**."
  }'

A resposta inclui slug, url, version. Retorne url para o usuário — esse é o canvas para abrir em https://canvas.n3wth.com/c/{slug}.

2. Escrever fonte

curl -sS -X PUT "$CANVAS_SITE_URL/agent/v1/canvases/$SLUG/source" \
  -H "Authorization: Bearer $CANVAS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"# Atualizado\n\nNovo conteúdo aqui."}'

Abas abertas em https://canvas.n3wth.com/c/$SLUG são re-renderizadas sem recarregar.

3. Ler fonte atual

curl -sS "$CANVAS_SITE_URL/agent/v1/canvases/$SLUG" \
  -H "Authorization: Bearer $CANVAS_AGENT_TOKEN"

4. Listar

curl -sS "$CANVAS_SITE_URL/agent/v1/canvases" \
  -H "Authorization: Bearer $CANVAS_AGENT_TOKEN"

Retorna apenas metadados (sem os corpos da fonte).

Fluxo de trabalho do agente

1. Confirme que CANVAS_SITE_URL e CANVAS_AGENT_TOKEN estão definidos em seu ambiente (nunca os commite).
2. POST /agent/v1/canvases com title/source opcionais.
3. Informe ao humano/outro agente a url da resposta (https://canvas.n3wth.com/c/{slug}).
4. Itere com PUT .../source conforme você refina.
5. GET .../canvases/{slug} se precisar da fonte atual antes de editar.

Erros

Status	Significado
401	Token bearer ausente/incorreto (apenas quando o deployment tem CANVAS_AGENT_TOKEN definido)
404	Slug desconhecido
400	Validação (tamanho da fonte, JSON)

Limite máximo da fonte: 512 KiB de caracteres.

Fora do escopo

Nenhum quadro branco de desenho, nenhum produto de canvas de terceiros. Esta API é apenas criar / escrever fonte / ler / listar.

Instalação portátil

Copie esta pasta para skills.n3wth.com ou qualquer raiz de habilidades do agente doméstico como canvas/SKILL.md. Aponte agentes para ela a partir de AGENTS.md. Contato: [email protected]. GitHub: https://github.com/n3wth.