agent-devkit 0.0.1

package/runtime/vendor/plugins/open-design/_official/examples/live-dashboard/open-design.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://open-design.ai/schemas/plugin.v1.json",
+  "specVersion": "1.0.0",
+  "name": "example-live-dashboard",
+  "title": "Live Dashboard",
+  "title_i18n": {
+    "zh-CN": "实时仪表板",
+    "zh-TW": "即時儀表板",
+    "ja": "ライブダッシュボード",
+    "ko": "라이브 대시보드",
+    "de": "Live-Dashboard",
+    "fr": "Tableau de bord en direct",
+    "ru": "Живая панель управления",
+    "es": "Panel en vivo",
+    "pt-BR": "Painel ao vivo",
+    "it": "Dashboard live",
+    "vi": "Bảng điều khiển trực tiếp",
+    "pl": "Panel na żywo",
+    "id": "Dasbor Langsung",
+    "nl": "Live dashboard",
+    "ar": "لوحة معلومات مباشرة",
+    "tr": "Canlı Gösterge Paneli",
+    "uk": "Жива панель керування",
+    "en": "Live Dashboard"
+  },
+  "version": "0.1.0",
+  "description": "Notion-style team dashboard rendered as a Live Artifact. A single-page, self-contained HTML dashboard with KPIs, a 7-day sparkline, a real-time activity feed and a linked-database task table — wired to Notion via the Composio connector catalog. Refreshes on demand and when the artifact is opened. Falls back to seeded mock data when no connector is bound, so it works offline / in screenshots / in the picker preview.",
+  "description_i18n": {
+    "zh-CN": "Notion 风格的团队仪表板，以 Live Artifact 形式呈现。单页自包含 HTML 仪表板，包含 KPI、7 天趋势图、实时活动流和关联数据库任务表，通过 Composio 连接器目录连接到 Notion。支持按需刷新和打开时自动刷新，未绑定连接器时使用模拟数据，可离线使用。",
+    "zh-TW": "Notion 風格的團隊儀表板，以 Live Artifact 形式呈現。單頁自包含 HTML 儀表板，包含 KPI、7 天趨勢圖、即時活動串流和關聯資料庫任務表，透過 Composio 連接器目錄連接到 Notion。支援按需重新整理和開啟時自動重新整理，未綁定連接器時使用模擬資料，可離線使用。",
+    "ja": "Notion スタイルのチームダッシュボードを Live Artifact としてレンダリング。KPI、7 日間のスパークライン、リアルタイムアクティビティフィード、リンクデータベースタスクテーブルを含む単一ページの自己完結型 HTML ダッシュボード。Composio コネクタカタログ経由で Notion に接続。オンデマンドおよび開封時に更新し、コネクタ未接続時はモックデータで動作。",
+    "ko": "Notion 스타일 팀 대시보드를 Live Artifact로 렌더링. KPI, 7일 스파크라인, 실시간 활동 피드, 링크된 데이터베이스 작업 테이블이 포함된 단일 페이지 자체 포함 HTML 대시보드. Composio 커넥터 카탈로그를 통해 Notion에 연결. 요청 시 및 열 때 새로고침되며, 커넥터 미연결 시 모의 데이터로 작동.",
+    "de": "Notion-artiges Team-Dashboard als Live Artifact. Einseitiges, eigenständiges HTML-Dashboard mit KPIs, 7-Tage-Sparkline, Echtzeit-Aktivitätsfeed und verlinkter Datenbank-Aufgabentabelle, verbunden mit Notion über den Composio-Connector-Katalog. Aktualisiert auf Anfrage und beim Öffnen, nutzt Mock-Daten wenn kein Connector verbunden ist.",
+    "fr": "Tableau de bord d'équipe style Notion rendu comme Live Artifact. Dashboard HTML autonome d'une page avec KPI, graphique sparkline sur 7 jours, flux d'activité en temps réel et table de tâches liée à une base de données, connecté à Notion via le catalogue de connecteurs Composio. Se rafraîchit à la demande et à l'ouverture, utilise des données fictives sans connecteur.",
+    "ru": "Командная панель в стиле Notion как Live Artifact. Одностраничная автономная HTML-панель с KPI, 7-дневным графиком, лентой активности в реальном времени и таблицей задач из связанной базы данных, подключённая к Notion через каталог коннекторов Composio. Обновляется по запросу и при открытии, работает с тестовыми данными без коннектора.",
+    "es": "Panel de equipo estilo Notion renderizado como Live Artifact. Panel HTML autónomo de una página con KPI, gráfico sparkline de 7 días, feed de actividad en tiempo real y tabla de tareas vinculada a base de datos, conectado a Notion mediante el catálogo de conectores Composio. Se actualiza bajo demanda y al abrir, funciona con datos de prueba sin conector.",
+    "pt-BR": "Painel de equipe estilo Notion renderizado como Live Artifact. Painel HTML autônomo de página única com KPIs, gráfico sparkline de 7 dias, feed de atividades em tempo real e tabela de tarefas vinculada ao banco de dados, conectado ao Notion via catálogo de conectores Composio. Atualiza sob demanda e ao abrir, funciona com dados simulados sem conector.",
+    "it": "Dashboard di team in stile Notion renderizzata come Live Artifact. Dashboard HTML autonoma a pagina singola con KPI, sparkline a 7 giorni, feed attività in tempo reale e tabella task collegata al database, connessa a Notion tramite catalogo connettori Composio. Si aggiorna su richiesta e all'apertura, funziona con dati mock senza connettore.",
+    "vi": "Bảng điều khiển nhóm kiểu Notion được hiển thị dưới dạng Live Artifact. Bảng điều khiển HTML độc lập một trang với KPI, biểu đồ sparkline 7 ngày, nguồn cấp hoạt động thời gian thực và bảng tác vụ liên kết cơ sở dữ liệu, kết nối với Notion qua danh mục trình kết nối Composio. Làm mới theo yêu cầu và khi mở, hoạt động với dữ liệu mô phỏng khi không có trình kết nối.",
+    "pl": "Dashboard zespołowy w stylu Notion renderowany jako Live Artifact. Jednostronicowy, samodzielny dashboard HTML z KPI, wykresem sparkline na 7 dni, feedem aktywności w czasie rzeczywistym i tabelą zadań połączoną z bazą danych, podłączony do Notion przez katalog konektorów Composio. Odświeża się na żądanie i przy otwarciu, działa z danymi testowymi bez konektora.",
+    "id": "Dasbor tim bergaya Notion yang dirender sebagai Live Artifact. Dasbor HTML mandiri satu halaman dengan KPI, sparkline 7 hari, feed aktivitas real-time, dan tabel tugas terhubung database, tersambung ke Notion melalui katalog konektor Composio. Menyegarkan sesuai permintaan dan saat dibuka, bekerja dengan data tiruan tanpa konektor.",
+    "nl": "Teamdashboard in Notion-stijl weergegeven als Live Artifact. Op zichzelf staand HTML-dashboard van één pagina met KPI's, 7-daagse sparkline, realtime activiteitenfeed en gekoppelde databasetakentabel, verbonden met Notion via de Composio-connectorcatalogus. Wordt op verzoek en bij openen vernieuwd, werkt met mockgegevens zonder connector.",
+    "ar": "لوحة معلومات الفريق بنمط Notion معروضة كـ Live Artifact. لوحة معلومات HTML مستقلة من صفحة واحدة مع KPI ومخطط sparkline لمدة 7 أيام وموجز نشاط فوري وجدول مهام مرتبط بقاعدة البيانات، متصلة بـ Notion عبر كتالوج موصلات Composio. تُحدّث عند الطلب وعند الفتح، تعمل ببيانات تجريبية بدون موصل.",
+    "tr": "Notion tarzı ekip gösterge paneli Live Artifact olarak sunulur. KPI'lar, 7 günlük sparkline, gerçek zamanlı etkinlik akışı ve bağlantılı veritabanı görev tablosu içeren tek sayfalık, bağımsız HTML gösterge paneli, Composio bağlayıcı kataloğu üzerinden Notion'a bağlanır. İstek üzerine ve açılışta yenilenir, bağlayıcı olmadan sahte verilerle çalışır.",
+    "uk": "Командна панель у стилі Notion як Live Artifact. Одностороннкова автономна HTML-панель з KPI, 7-денним графіком sparkline, стрічкою активності в реальному часі та таблицею завдань із пов'язаної бази даних, підключена до Notion через каталог з'єднувачів Composio. Оновлюється на запит і при відкритті, працює з тестовими даними без з'єднувача.",
+    "en": "Notion-style team dashboard rendered as a Live Artifact. A single-page, self-contained HTML dashboard with KPIs, a 7-day sparkline, a real-time activity feed and a linked-database task table — wired to Notion via the Composio connector catalog. Refreshes on demand and when the artifact is opened. Falls back to seeded mock data when no connector is bound, so it works offline / in screenshots / in the picker preview."
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Open Design",
+    "url": "https://github.com/nexu-io"
+  },
+  "homepage": "https://github.com/nexu-io/open-design/tree/main/plugins/_official/examples/live-dashboard",
+  "tags": [
+    "example",
+    "first-party",
+    "prototype",
+    "operation",
+    "web",
+    "desktop",
+    "team-dashboard",
+    "notion-dashboard",
+    "live-dashboard",
+    "ops-dashboard",
+    "team-workspace-dashboard",
+    "untitled",
+    "notion",
+    "live-artifact-dashboard"
+  ],
+  "compat": {
+    "agentSkills": [
+      {
+        "path": "./SKILL.md"
+      }
+    ]
+  },
+  "od": {
+    "kind": "scenario",
+    "taskKind": "new-generation",
+    "mode": "prototype",
+    "platform": "desktop",
+    "scenario": "operation",
+    "surface": "web",
+    "preview": {
+      "type": "html",
+      "entry": "./example.html"
+    },
+    "useCase": {
+      "query": {
+        "en": "Build me a Notion-style team dashboard for Acme Studio. KPIs: total tasks, done this week, active members, docs in review. Wire it to the Notion connector and let it refresh on demand.",
+        "zh-CN": "使用这个插件完成以下任务：Build me a Notion-style team dashboard for Acme Studio. KPIs: total tasks, done this week, active members, docs in review. Wire it to the Notion connector and let it refresh on demand."
+      },
+      "exampleOutputs": [
+        {
+          "path": "./example.html",
+          "title": "Live Dashboard"
+        }
+      ]
+    },
+    "inputs": [
+      {
+        "name": "workspace_name",
+        "type": "string",
+        "required": true
+      },
+      {
+        "name": "page_title",
+        "type": "string",
+        "default": "Team Dashboard"
+      },
+      {
+        "name": "connector",
+        "type": "string",
+        "values": [
+          "notion",
+          "linear",
+          "stripe",
+          "posthog",
+          "mock"
+        ],
+        "default": "notion"
+      },
+      {
+        "name": "refresh_seconds",
+        "type": "number",
+        "default": 30,
+        "min": 10,
+        "max": 300
+      },
+      {
+        "name": "stale_after_seconds",
+        "type": "number",
+        "default": 90,
+        "min": 30,
+        "max": 600
+      },
+      {
+        "name": "kpi_count",
+        "type": "string",
+        "values": [
+          2,
+          4,
+          6
+        ],
+        "default": 4
+      },
+      {
+        "name": "include_activity_feed",
+        "type": "boolean",
+        "default": true
+      },
+      {
+        "name": "include_task_table",
+        "type": "boolean",
+        "default": true
+      }
+    ],
+    "context": {
+      "skills": [
+        {
+          "path": "./SKILL.md"
+        }
+      ],
+      "designSystem": {
+        "primary": true
+      },
+      "craft": [
+        "typography",
+        "color",
+        "anti-ai-slop",
+        "motion-discipline",
+        "state-coverage"
+      ],
+      "assets": [
+        "./example.html",
+        "./assets/template.html",
+        "./references/checklist.md",
+        "./references/components.md",
+        "./references/connectors.md",
+        "./references/layouts.md"
+      ]
+    },
+    "pipeline": {
+      "stages": [
+        {
+          "id": "generate",
+          "atoms": [
+            "file-write",
+            "live-artifact"
+          ]
+        }
+      ]
+    },
+    "capabilities": [
+      "prompt:inject",
+      "fs:write"
+    ]
+  }
+}

package/runtime/vendor/plugins/open-design/_official/examples/live-dashboard/references/checklist.md

@@ -0,0 +1,83 @@
+# Pre-emit checklist (P0 must pass; do not write index.html until green)
+
+Quote each P0 row in your reply with `[x]` or `[ ]`. Do not emit while
+any P0 is unchecked.
+
+## Visual integrity
+
+- [ ] **P0 — Display face**. Page title uses a system / Notion-leaning
+      sans (SF Pro / system-ui) or an editorial serif from the active
+      DESIGN.md. **Never Inter Display, never SF Pro Display at body
+      size, never Helvetica condensed.**
+- [ ] **P0 — Accent restraint**. The `--accent` token appears at most
+      twice in the body markup (one Refresh button + one sparkline
+      stroke is canonical). No accent on KPI numbers.
+- [ ] **P0 — No purple/pink gradient header**. The Notion idiom is
+      flat. Backgrounds are `#fff` or `var(--bg-soft)`.
+- [ ] **P0 — Body contrast**. Body text vs. background ≥ 4.5:1.
+      Secondary text ≥ 4.0:1.
+- [ ] **P0 — No emoji icon strip across the top**. Page-emoji is one,
+      semantically meaningful (`📊` for ops, `📓` for docs, `🚀` for
+      launch — never an emoji decoration row).
+
+## Honesty (the most-violated rule)
+
+- [ ] **P0 — No invented metric**. Every number is either provided by
+      the user, by the connector, or labeled as `—` / `Sample`.
+      Forbidden: "10× faster", "join 50,000 founders", "99.99% uptime"
+      unless the user supplied the literal number.
+- [ ] **P0 — Sample-data badge**. When `inputs.connector === mock`,
+      the page must display "Sample data" in the live-pill or callout
+      so a screenshot of this artifact is never mistaken for real ops.
+- [ ] **P0 — Plausible KPI ranges**. `Total tasks` < 500 for a small
+      team. `Active members` ≤ team size. `Done this week` ≤ Total.
+
+## Connector wiring (only when connector !== mock)
+
+- [ ] **P0 — `connectors.json` exists** at the project root. See
+      `connectors.md` for the schema.
+- [ ] **P0 — Endpoints documented**. Every `fetch()` call inside
+      `index.html` corresponds to one entry in `connectors.json`.
+- [ ] **P0 — No hardcoded secrets**. No API tokens, integration secrets,
+      OAuth client IDs, or workspace IDs in the markup. The OD daemon
+      resolves these via `media-config.json`.
+- [ ] **P0 — Stale fallback**. On `fetch` error or > 90s without a
+      successful poll, the pill swaps to amber and the previous values
+      remain on screen. The artifact never goes blank.
+
+## Structural
+
+- [ ] **P0 — Single file**. `index.html` self-contained. No external
+      CSS/JS imports beyond the system font stack and one OD custom
+      element. No CDN URLs.
+- [ ] **P0 — Sidebar collapses on `< 980px`**. The dashboard is
+      mobile-readable; sidebar hides, KPI grid stacks 2-up, table
+      drops `due` and `priority` columns.
+- [ ] **P0 — `prefers-reduced-motion`**. All tweens and pulses are
+      disabled when `(prefers-reduced-motion: reduce)`.
+- [ ] **P0 — `tabular-nums` on KPI values**. Numeric values shouldn't
+      jitter horizontally during tween or auto-refresh.
+
+## Polish (P1)
+
+- [ ] P1 — Refresh button shows a spinning ↻ for the duration of the
+      poll, then settles back. No layout shift.
+- [ ] P1 — Activity feed: newly-inserted row gets a left-edge accent
+      bullet (•) and a soft accent background for 2s, then fades.
+- [ ] P1 — Database row that just changed flashes the row background
+      with a 1.4s ease-out.
+- [ ] P1 — Live-pill states: green pulse (idle), blue solid
+      (syncing), amber solid (stale).
+- [ ] P1 — Sparkline grid lines are dashed, line-color from `--line`,
+      stroke-dasharray `2 3`. Dots are filled `--accent` r=3.
+- [ ] P1 — Toast bottom-center, dark `#1f1f1f`, 1800ms auto-dismiss.
+
+## Content
+
+- [ ] P1 — Person chips: 18px round avatar, two-letter initials,
+      stable per-name color. No initials > 2 chars.
+- [ ] P1 — Status pill copy uses Notion canonical labels:
+      "Done", "In progress", "Blocked", "In review", "To do".
+      Case matters: "In progress" not "In-Progress".
+- [ ] P1 — Footer attribution names the source platform and the
+      connector slug exactly: `composio.notion`, `composio.linear`, etc.

package/runtime/vendor/plugins/open-design/_official/examples/live-dashboard/references/components.md

@@ -0,0 +1,212 @@
+# Components
+
+Copy these markup shapes verbatim. Re-skin via the active `DESIGN.md`
+(color, typography, spacing tokens). Do not invent new component
+shapes — that's where AI-slop sneaks in.
+
+All snippets assume the CSS custom properties defined in
+`assets/template.html` (`--ink`, `--ink-2`, `--bg-soft`, `--accent`,
+`--line`, `--pill-*-bg/ink`, …).
+
+---
+
+## live-pill (top-right of the topbar)
+
+```html
+<div class="pill-live" id="livePill">
+  <span class="dot"></span>
+  <span id="liveText">Live · synced</span>
+</div>
+```
+
+Three states:
+
+| State    | Class on `.pill-live` | Dot color | Text                          |
+|---       |---                    |---        |---                            |
+| Idle     | (none)                | green     | `Live · synced`               |
+| Syncing  | `.syncing`            | accent    | `Syncing…`                    |
+| Stale    | `.stale`              | amber     | `Stale · 2 min ago`           |
+
+The green dot animates a 1.8s `pulse` keyframe. Disable on
+`prefers-reduced-motion`.
+
+---
+
+## kpi card (one cell of the KPI grid)
+
+```html
+<div class="kpi">
+  <div class="label">Total tasks</div>
+  <div class="value" id="kTotal">142</div>
+  <div class="delta up"><span class="arr">↑</span> 6 vs last week</div>
+</div>
+```
+
+Rules:
+- `.value` is `font-size: 32px; font-weight: 600; letter-spacing: -0.01em;
+  font-variant-numeric: tabular-nums`
+- `.label` is `12px uppercase letter-spacing .03em` color `--ink-2`
+- `.delta.up` → green; `.delta.down` → red; neutral `.delta` is grey
+- On refresh, tween `value` between old and new with a 600ms cubic
+  ease-out, and add `.flash` for 700ms (turns the number `--accent-ink`
+  briefly).
+- **Never** put a colored progress bar under the number.
+- **Never** put a sparkline inside a KPI card — sparklines belong in
+  the two-column block.
+
+---
+
+## sparkline (SVG, hand-rolled)
+
+```html
+<svg class="spark" viewBox="0 0 600 140" preserveAspectRatio="none">
+  <g class="spark-grid">
+    <line x1="0" y1="35"  x2="600" y2="35"/>
+    <line x1="0" y1="70"  x2="600" y2="70"/>
+    <line x1="0" y1="105" x2="600" y2="105"/>
+  </g>
+  <path class="spark-fill" d=""></path>
+  <path class="spark-line" d=""></path>
+  <g id="sparkDots"></g>
+  <g id="sparkLabels" class="spark-axis"></g>
+</svg>
+```
+
+CSS:
+- `.spark-fill` is `fill: rgba(<accent-rgb>, 0.10)`
+- `.spark-line` is `fill: none; stroke: var(--accent); stroke-width: 2`
+- `.spark-grid line` is `stroke: var(--line); stroke-dasharray: 2 3`
+- `.spark-dot` (circles, r=3) is `fill: var(--accent)`
+
+Compute paths from a length-7 series with padding 24/16/10/24 (L/R/T/B)
+inside the 600×140 viewBox. Today's bucket is at the right.
+
+Do not use Chart.js / Recharts / D3 — single artifact, no external deps.
+
+---
+
+## activity-feed row
+
+```html
+<div class="feed-row">
+  <span class="av" style="background:#f1c40f">SC</span>
+  <div class="body">
+    <span class="who">Sarah Chen</span>
+    <span class="what"> moved</span>
+    <span class="target"> 🚀 Q3 Roadmap planning</span>
+    <span class="what"> to In progress</span>
+  </div>
+  <div class="time">3 min ago</div>
+</div>
+```
+
+- Avatar: 26px round, two-letter initials, color stable per person.
+- `.target` gets a 1px dotted underline and `cursor: pointer`.
+- A "just inserted" row gets the `.new` class for 2s — applies a soft
+  `rgba(<accent>, .06)` background and a `•` bullet before the name.
+- Re-render relative timestamps every 15s.
+
+---
+
+## status pills (Notion canonical five-color set)
+
+```html
+<span class="pill done">Done</span>
+<span class="pill progress">In progress</span>
+<span class="pill blocked">Blocked</span>
+<span class="pill review">In review</span>
+<span class="pill todo">To do</span>
+```
+
+| Class      | Background      | Foreground      | Notion label   |
+|---         |---              |---              |---             |
+| `done`     | `#dbeddb`       | `#2b593f`       | Done           |
+| `progress` | `#fdecc8`       | `#976d23`       | In progress    |
+| `blocked`  | `#ffe2dd`       | `#b13b2c`       | Blocked        |
+| `review`   | `#d3e5ef`       | `#1f5b78`       | In review      |
+| `todo`     | `#e9e5e3`       | `#5a534f`       | To do          |
+
+Do not introduce extra states. Map any project-specific state into one
+of these five.
+
+---
+
+## linked-database row
+
+```html
+<div class="db-row">
+  <div class="db-cell">📐</div>
+  <div class="db-cell title"><span class="t">Design tokens v2 spec</span></div>
+  <div class="db-cell"><span class="pill review">In review</span></div>
+  <div class="db-cell"><span class="person">…avatar…<span>Lisa Zhao</span></span></div>
+  <div class="db-cell due">May 14</div>
+  <div class="db-cell priority">Med</div>
+</div>
+```
+
+- 6-column grid: `32px 2.4fr 1fr 1fr 0.9fr 0.9fr`
+- `.db-row.changed` triggers a 1.4s row-flash via the `rowflash`
+  keyframe.
+- Hover: `background: var(--bg-soft)`. No transform / shadow.
+
+---
+
+## refresh button (page header, primary)
+
+```html
+<button class="btn primary" id="refreshBtn">
+  <span class="ico" id="refreshIco">↻</span>
+  <span>Refresh from Notion</span>
+</button>
+```
+
+- Default: `background: var(--accent); color: #fff;`
+- Hover: `background: var(--accent-ink)`
+- During poll: add `.spin` to `.ico`, disable button taps via the
+  `busy` flag in JS (do **not** rely on `[disabled]` so visuals stay
+  identical).
+- Label adapts to connector: "Refresh from Notion" / "Refresh from
+  Linear" / "Refresh from Stripe" — never just "Refresh" alone.
+
+---
+
+## auto-toggle (page header, ghost)
+
+```html
+<button class="btn ghost" id="autoBtn" title="Auto refresh every 30s">
+  <span>⏱</span><span id="autoLbl">Auto · on</span>
+</button>
+```
+
+Toggles `setInterval(refresh, refresh_seconds * 1000)`. Persists to
+`localStorage.live_dashboard_auto` so a reload restores the state.
+
+---
+
+## toast (bottom-center, transient)
+
+```html
+<div class="toast" id="toast">Synced — 3 changes from Notion</div>
+```
+
+`position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%);`
+1800ms auto-dismiss. Dark `#1f1f1f` background, white text. One toast
+at a time; subsequent calls reset the timer.
+
+---
+
+## callout (Notion idiom)
+
+```html
+<div class="callout">
+  <div class="emj">💡</div>
+  <div>
+    <div><strong>This page is a Live Artifact.</strong> Numbers below are pulled from
+    your <strong>Acme Studio</strong> Notion workspace via the Composio connector.</div>
+    <small>Refreshes on demand or when the page opens. Last 7 days only.</small>
+  </div>
+</div>
+```
+
+One short, declarative sentence + a smaller meta line. No marketing
+copy, no "Powered by", no exclamation marks.

package/runtime/vendor/plugins/open-design/_official/examples/live-dashboard/references/connectors.md

@@ -0,0 +1,173 @@
+# Connectors
+
+`live-dashboard` is a **Live Artifact**. The values it shows are not
+hard-coded — they are polled from a connector at runtime. The OD daemon
+(0.4.0+) ships a Composio connector catalog and a `connectors.json`
+contract that artifacts emit alongside `index.html`.
+
+When `inputs.connector === mock` (or the daemon cannot resolve the
+configured connector), the artifact falls back to seeded sample data.
+This keeps screenshots, the picker preview, and offline use working.
+
+> **Status — relationship to `skills/live-artifact/`.**
+>
+> The canonical, currently-shipping live-artifact contract lives in
+> [`skills/live-artifact/SKILL.md`](../../live-artifact/SKILL.md): it is
+> *file-shaped* (`artifact.json` + `template.html` + `data.json` +
+> `provenance.json`) and *CLI-shaped* on the agent side (the agent calls
+> `"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts {create,update}` and
+> `tools connectors {list,execute}` rather than HTTP). The renderer is
+> scalar-only `html_template_v1` (`apps/daemon/src/live-artifacts/render.ts`).
+>
+> `live-dashboard` is a **complementary** browser-runtime variant: the
+> artifact is rendered as a single self-contained HTML page, and the
+> live behaviors (refresh-on-open, manual Refresh, auto-refresh, stale
+> pill) run in-page rather than at template-render time. Polling
+> therefore needs an HTTP shape, which is what the rest of this file
+> describes (`POST /api/od/connectors/poll`).
+>
+> Treat the HTTP shape below as a **forward-looking proposal** that
+> sits alongside the file/CLI contract: the daemon does not yet expose
+> `POST /api/od/connectors/poll` (`apps/daemon/src/server.ts` /
+> `apps/daemon/src/live-artifacts/`), so out-of-the-box the artifact
+> renders against the seeded sample data and the Refresh button only
+> tweens the fixture. When the daemon-team route lands, only
+> `seedNextChange()` in the template needs to be replaced with the
+> `poll()` helper documented here — the `connectors.json` shape is
+> already a usable declarative source-of-truth that downstream tooling
+> (the live-artifact CLI, MCP wrappers, audit logs) can read today.
+
+---
+
+## `connectors.json` schema
+
+Emit one `connectors.json` at the project root next to `index.html`:
+
+```json
+{
+  "schema": "od.connector/1",
+  "primary": "notion",
+  "freshness": {
+    "auto_refresh_seconds": 30,
+    "warn_after_seconds": 90,
+    "fail_after_seconds": 600
+  },
+  "bindings": {
+    "notion": {
+      "provider": "composio.notion",
+      "auth_ref": "media-config.json#notion.token",
+      "reads": [
+        {
+          "id": "tasks_active",
+          "endpoint": "databases.{id}.query",
+          "params": { "id": "${notion.tasks_db_id}",
+                      "filter": { "property": "Status", "status": { "does_not_equal": "Done" } },
+                      "sorts":  [{ "property": "Updated", "direction": "descending" }] },
+          "shape": "task[]"
+        },
+        {
+          "id": "kpi_total",
+          "endpoint": "databases.{id}.query",
+          "params": { "id": "${notion.tasks_db_id}", "page_size": 1 },
+          "extract": "$.metadata.total_count",
+          "shape": "integer"
+        },
+        {
+          "id": "activity_recent",
+          "endpoint": "search",
+          "params": { "filter": { "property": "object", "value": "page" },
+                      "sort":   { "direction": "descending", "timestamp": "last_edited_time" },
+                      "page_size": 8 },
+          "shape": "activity[]"
+        }
+      ],
+      "events": [
+        { "id": "task_changed", "type": "page.updated", "selector": "$.tasks_db_id" }
+      ]
+    }
+  }
+}
+```
+
+The shape is intentionally close to Notion's REST API — the daemon's
+connector adapter rewrites `endpoint` and `params` into the live
+provider call. Other connectors (Linear, Stripe, Posthog) follow the
+same shape with provider-specific `endpoint` strings.
+
+---
+
+## Resolution order (what the daemon does)
+
+1. Read `connectors.json` from the artifact dir.
+2. Look up `bindings[primary].provider` in the Composio catalog.
+3. Resolve `auth_ref` against the daemon's `media-config.json`. The
+   actual lookup is environment-aware (see
+   [`apps/daemon/src/media-config.ts`](../../../apps/daemon/src/media-config.ts),
+   `configFile()` — precedence high → low):
+   - `<OD_MEDIA_CONFIG_DIR>/media-config.json` when that env var is set;
+   - else `<OD_DATA_DIR>/media-config.json` when `OD_DATA_DIR` is set
+     (relative paths are anchored to the active project root, `$HOME`
+     and `~` shorthands are expanded);
+   - else daemon-managed media configuration for the active project. Before
+     documenting daemon storage paths, read root `AGENTS.md` → **Daemon data
+     directory contract**.
+
+   The artifact never opens any of these paths itself — it always goes
+   through the daemon poll endpoint, and the daemon enforces the
+   correct lookup order. **Never** read tokens from the artifact.
+4. For each `reads[].endpoint`, the daemon constructs the live HTTP
+   request with the resolved auth and substitutes `${...}` placeholders
+   from the resolved `media-config.json#<provider>.*` values.
+5. Cache responses for `freshness.auto_refresh_seconds`. The
+   `Refresh` button issues an explicit poll that bypasses the cache.
+
+---
+
+## Wiring inside `index.html`
+
+The artifact does **not** call Composio directly. It calls the OD
+daemon's local proxy:
+
+```js
+async function poll(readId) {
+  const res = await fetch(`/api/od/connectors/poll`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ project: "<project_id>", read: readId })
+  });
+  if (!res.ok) throw new Error(`poll ${readId} failed: ${res.status}`);
+  return res.json();
+}
+```
+
+`<project_id>` is injected by the daemon at render time via a
+`<meta name="od:project" content="...">` tag. The artifact reads it
+once on mount.
+
+---
+
+## Fallback behavior
+
+- On `fetch` error: keep the previously-rendered values, swap the
+  live-pill to amber `Stale · <ago>`, write a small grey hint into the
+  footer (`Source: Notion · last good poll 4 min ago`).
+- On `inputs.connector === mock`: skip `poll()` entirely, use the
+  `seedMock()` function in `index.html`. The live-pill displays
+  `Sample data` in grey with no dot animation.
+- On 401/403: surface a one-time toast `Reconnect Notion in Settings →
+  Connectors` and stop further polls until the next manual Refresh.
+
+---
+
+## Provider-specific cheat sheet
+
+| Connector | `provider`         | Shape of one row             | Typical KPI                        |
+|---        |---                 |---                           |---                                 |
+| Notion    | `composio.notion`  | `task = {title, status, assignee, due, prio, updated}` | total tasks · done this week · members · review |
+| Linear    | `composio.linear`  | `issue = {title, state, assignee, priority, updated}`  | backlog · in progress · blocked · cycle progress |
+| Stripe    | `composio.stripe`  | `event = {type, amount, customer, created}`            | MRR · churn · new subs · refunds   |
+| Posthog   | `composio.posthog` | `event = {name, distinct_id, $current_url, ts}`        | DAU · signups · feature adoption · errors |
+
+Do not invent per-provider shapes. If the user wants something not in
+this table, fall back to `mock` and surface a footer hint asking the
+user to extend the connector catalog.