Live Artifact Skill

Create an OpenDesign live artifact: a project-scoped, previewable HTML artifact whose data can later be refreshed without redesigning the presentation.

Resource map

live-artifact/
├── SKILL.md
└── references/
    ├── artifact-schema.md      ← `references/artifact-schema.md`: artifact files, DTO shape, template binding rules
    ├── connector-policy.md     ← `references/connector-policy.md`: connector safety, redaction, credential boundaries
    └── refresh-contract.md     ← `references/refresh-contract.md`: source metadata, refresh execution, snapshots

Current status

Use the references in this directory as the source of truth for the live artifact file contract. Prefer daemon wrapper commands over raw HTTP when registering or updating live artifacts.

When to use this skill

Use this skill when the user asks for a data-backed view that should remain useful after the first render, for example a live dashboard, refreshable report, synced status page, auditable data view, or artifact that can later be refreshed from local/project data or connectors.

Before creating files, decide whether the user actually wants a live artifact or a normal static artifact:

• Use a live artifact when the user mentions refresh, sync, recurring updates, connector-backed data, source/provenance tracking, dashboards, reports, or reusable data-backed views.
• Use a normal static artifact when the user only wants a one-off HTML/mockup/image/file and does not need refresh, source metadata, or data/provenance panels.
• If the intent is ambiguous, ask one short question: “Should this be refreshable/live, or just a static artifact?”

Workflow

1. Resolve scope and data source without blocking on connected connectors

   • Identify the preview goal, audience, data freshness expectations, and whether refresh should be possible later.
   • If the user explicitly names a connector/source such as Notion, GitHub, Slack, or Google Drive, do not ask “where should the data come from?” before checking daemon connector tools.
   • Prefer local/project sources or daemon connector tools when available.
   • Do not call provider APIs directly when a daemon connector/wrapper exists.
   • If connector data is needed, first list connectors with "$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact. If the named connector is present with status: "connected", choose an appropriate read-only auto tool from its catalog and execute it through the connector wrapper.
   • For Notion specifically, a connected notion connector plus a user brief that names Notion is enough to start with notion.notion_search using a query derived from the requested artifact/topic. Use notion.notion_fetch_database only when the user supplied a database id or the search result clearly identifies one.
   • Ask the user a data-source question only when no matching connected connector exists, multiple connected candidates fit equally well, or the requested artifact has no usable topic/query to search for. If you must ask, be specific: ask for the page/database/topic or permission to search broadly, not “where is the Notion data source?”

2. Author the source files

   • Write template.html as the human-designed HTML template. The daemon hydrates it with data.json using the html_template_v1 binding contract — stay inside it or hydration fails and the raw template ships with visible {{…}} tokens:
     • Scalars: {{data.path.to.value}}. Paths start with data, dot-separated; numeric array indexes are allowed ({{data.kpis.0.value}}). Every binding must resolve to a single string/number, not an object or array.
     • Lists: repeat one element with data-od-repeat="item in data.items", then bind loop-scoped fields inside it as {{item.label}} (or {{item}} for a scalar array). One level only; data.* still works inside the repeat for globals.
     • Do NOT hand-loop in a <script> (scripts are stripped from previews), and do NOT reference a bare loop variable like {{metric.value}} without a matching data-od-repeat scope — that binding is unresolvable. Nested repeats, conditionals, filters, helpers, and raw/triple-brace interpolation are unsupported.
   • Write data.json as the canonical preview data used by those bindings — real values, not placeholders.
   • Write artifact.json with the live artifact metadata, preview declaration, document declaration, and safe source descriptors.

…