workbuddy_skills/open-design/design-templates/live-artifact/references/artifact-schema.md

Live Artifact Schema Reference

Live artifacts are stored as daemon-owned project files under .live-artifacts/<artifactId>/. Agents author the source files, then register them through daemon tooling. The daemon assigns IDs, project scope, timestamps, run scope, and refresh status.

Source files

File	Owner	Purpose
artifact.json	agent-authored input, daemon-validated	Artifact metadata, preview settings, document metadata, and source descriptors. Must not contain daemon-owned fields.
template.html	agent-authored	html_template_v1 template used to render the preview.
data.json	agent-authored then refresh-runner-updated	Canonical preview data. API document.dataJson is only a derived cache.
provenance.json	agent-authored then refresh-runner-updated	Source summary and generation notes.
index.html	daemon-derived	Generated preview output. Do not treat as source of truth.

Create/update input

artifact.json should match LiveArtifactCreateInput or LiveArtifactUpdateInput from packages/contracts/src/api/live-artifacts.ts.

Allowed agent-owned top-level fields:

• title
• slug
• sessionId
• pinned
• status
• preview
• document

Daemon-owned fields are rejected in agent input:

• id
• projectId
• createdAt
• updatedAt
• createdByRunId
• schemaVersion
• refreshStatus
• lastRefreshedAt

HTML document contract

MVP documents use html_template_v1:

{
  "format": "html_template_v1",
  "templatePath": "template.html",
  "generatedPreviewPath": "index.html",
  "dataPath": "data.json",
  "dataJson": {}
}

template.html + data.json is rendered by the daemon into index.html and the preview route.

Binding rules

• Use escaped interpolation: {{data.path.to.value}}.
• Paths must start with data and use dot-separated keys; numeric array indexes are allowed as path segments.
• Supported structural directive: data-od-repeat="item in data.items" for one-level array repeats.
• Nested repeats, conditionals, filters, helper functions, partials, and expression evaluation are not supported.
• Raw HTML insertion is forbidden: no triple braces, ampersand interpolation, data-od-html, data-od-raw, or equivalent.
• Interpolation in text and ordinary attributes is HTML-escaped by default.
• Do not interpolate inside tag names, attribute names, comments, <script>, <style>, <iframe srcdoc>, event-handler attributes, or unsupported URL-bearing attributes.

Bounded JSON limits

All persisted JSON values must fit the shared bounded JSON envelope:

Limit	Value
Maximum object/array depth	8
Maximum keys per object	100
Maximum array length	500
Maximum string length	16 KiB
Maximum serialized JSON size	256 KiB

Forbidden keys anywhere in persisted JSON include raw, rawResponse, payload, body, headers, cookie, authorization, token, secret, credential, and password.

Minimal static artifact input

{
  "title": "Release Status",
  "preview": { "type": "html", "entry": "index.html" },
  "document": {
    "format": "html_template_v1",
    "templatePath": "template.html",
    "generatedPreviewPath": "index.html",
    "dataPath": "data.json",
    "dataJson": {
      "summary": {
        "title": "Release Status",
        "status": "On track"
      }
    }
  }
}