Skip to content

nexu-io/open-design / design-templates/live-artifact

live-artifact

Verified

Create refreshable, auditable OpenDesign artifacts backed by connector or local data. Trigger when the user asks for live dashboards, refreshable reports, synced views, or reusable data-backed artifacts.

references/artifact-schema.md

View on GitHub
# 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`:

```json
{
  "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

```json
{
  "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"
      }
    }
  }
}
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall