Guiro – Shareable Visual Snapshots

Guiro (https://guiro.io) is an ephemeral Presentation Layer as a Service. You give it a structured JSON bundle describing a layout of visual components, and it returns a short-lived, publicly accessible share link (e.g. https://guiro.io/s/{slug}). The rendered page is a polished, read-only visual — a dashboard, report, chart, calendar, or status page. No login or account is needed to view it.

Use this skill whenever you produce structured results — metrics, tables, timelines, financial data, event schedules, progress tracking — and want to turn them into a shareable visual artifact the user can open in a browser, send to a colleague, or print to PDF.

What you can build

API workflow

1. Fetch capabilities — discover supported protocol versions and component catalogs.
2. Build payload — assemble an A2UI JSON bundle targeting the live contract values.
3. Validate — confirm the payload is well-formed before creating.
4. Create — publish the bundle and receive the share link.

Endpoints

Base URL: https://api.guiro.io

Authentication

All requests require an API key via the X-API-Key header. The key is read from the GUIRO_API_KEY environment variable. If the key is missing, ask the user to provide one.

Commands

# 1 – Fetch capabilities (saves to .guiro/runtime-capabilities.json)
bash "{baseDir}/scripts/fetch-capabilities.sh"

# 2 – Write a sample payload (dashboard | calendar | chart | donut)
bash "{baseDir}/scripts/write-sample-payload.sh" ./payload.json dashboard

# 3 – Validate and create the guiro
bash "{baseDir}/scripts/create-guiro.sh" --payload ./payload.json --idempotency-key run-001

The sample payloads are starting points. Replace the placeholder content with real data relevant to the user's request.

Payload structure

A valid A2UI bundle has this shape:

{
  "storage_version": "1",
  "a2ui_version": "0.9",
  "catalog_id": "guiro.shadcn.detached.v1",
  "theme": {
    "primary": "#0f766e",
    "secondary": "#0f172a"
  },
  "messages": [
    {
      "version": "v0.9",
      "createSurface": {
        "surfaceId": "share-main",
        "catalogId": "guiro.shadcn.detached.v1"
      }
    },
    {
      "version": "v0.9",
      "updateComponents": {
        "surfaceId": "share-main",
        "components": [ ... ]
      }
    }
  ]
}

• storage_version, a2ui_version, catalog_id — use values from the capabilities response.
• messages must contain one createSurface message and one updateComponents message.
• Target exactly one surface.

Component reference

The components array is a flat list of component objects. Each has an id (unique string) and a component type. Parent components reference children by id. The tree must include a component with id: "root".

Layout

Content

Component tree example

[
  { "id": "root", "component": "Card", "child": "page" },
  { "id": "page", "component": "Column", "gap": "lg", "children": ["heading", "metrics"] },
  { "id": "heading", "component": "Text", "text": "Monthly Report", "variant": "h1" },
  { "id": "metrics", "component": "Row", "gap": "md", "children": ["badge1", "progress1"] },
  { "id": "badge1", "component": "Badge", "label": "Active: 42", "variant": "outline" },
  { "id": "progress1", "component": "ProgressIndicator", "value": 75, "max": 100 }
]

Theme

Colors accept hex (#0f766e) or oklch (oklch(0.527 0.154 150.069)) values:

{ "primary": "#0f766e", "secondary": "#0f172a" }

Choose theme colors that suit the content. Use contrasting primary and secondary values.

Rules

• Always fetch capabilities first and use the returned values for storage_version, a2ui_version, and catalog_id.
• Always validate before create.
• The bundle must target exactly one surface.
• The updateComponents array must include a component with id: "root".
• Treat validation errors as authoritative — fix the payload and re-validate until it passes.
• Use the sample payloads as structural templates but replace all placeholder content with real data from the user's request.
• Prefer Icon for section headers, callouts, and status accents when it improves scanability.

Output

Successful create returns:

{
  "slug": "abc123",
  "url": "https://guiro.io/s/abc123",
  "expires_at": "2025-07-15T12:00:00Z"
}

Share the url with the user. Guiros are ephemeral — after expires_at, the link shows a standardized "This Guiro has Expired" page.