@moonpay/cli 1.49.1 → 1.50.0

package/skills/moonpay-artifact-builder/SKILL.md

@@ -0,0 +1,667 @@
+---
+name: moonpay-artifact-builder
+description: Author interactive HTML artifacts for the MoonPay Agents desktop app. Use when the user wants a custom interactive UI, a one-off dashboard, a status report, an editor, or a walkthrough that drives the MoonPay CLI under the hood. Artifacts are single HTML files that render in the app's sandboxed Artifacts view, call `mp` via window.mp.run, and inherit the host's dark design system. This skill defines the contract, the bridge API, and — primarily — the design system every artifact should use so the catalog feels like one product.
+---
+
+# MoonPay Artifact Builder
+
+The MoonPay Agents desktop app ships an **Artifacts** view that renders self-contained HTML files inside a sandboxed iframe. Each artifact can call the local `mp` CLI through a postMessage bridge — same way Claude/ChatGPT artifacts work, but first-party and able to invoke real money-moving operations.
+
+When you author an artifact, the goal isn't just "an HTML file that works" — it's an artifact that looks like it belongs next to the rest of the MoonPay Agents catalog. The design system below is how you get that for free.
+
+## When to use this skill
+
+The user wants a custom interactive UI for something they do recurringly: a dashboard, a status report, an editor, a walkthrough, a teaching artifact. Save to `~/.moonpay-agents/artifacts/<slug>.html` — it shows up in the app's Artifacts view on next list.
+
+If the user wants a *procedural* workflow (a multi-step automation), that's a skill, not an artifact — invoke **moonpay-skill-builder** instead.
+
+## On-disk format
+
+A single self-contained HTML file. No build step, no bundler, no external assets except CDN libs.
+
+### Frontmatter
+
+The first thing in the file MUST be an HTML comment with key/value pairs:
+
+```html
+<!--
+name: my-artifact-slug
+title: My Artifact Title
+description: One short sentence shown on the artifact card.
+tags: [explorer, portfolio]
+-->
+```
+
+| key | required | notes |
+|---|---|---|
+| `name` | required | URL-safe slug. Must match the filename (`<slug>.html`). |
+| `title` | required | Displayed at the top of the artifact card and in the header bar. |
+| `description` | required | One sentence on the card. Aim for ≤ 100 chars. |
+| `tags` | optional | Comma-separated, e.g. `[explorer, tokens]`. Used for filtering. |
+
+### Save location
+
+```
+~/.moonpay-agents/artifacts/<slug>.html
+```
+
+Drop the file in this dir and it shows up the next time the app lists artifacts. No reload needed.
+
+(Built-in MoonPay artifacts live inside the app bundle. Don't try to write there — user artifacts always go to the path above.)
+
+## The bridge: `window.mp.run`
+
+Artifacts call the MoonPay CLI through `window.mp.run(argv: string[]): Promise<string>`. The result is the raw stdout of `mp <argv...>` — usually JSON if you pass `--json`.
+
+```js
+const data = await window.mp.run(["token", "retrieve", "--token", addr, "--chain", "polygon", "--json"]);
+const token = JSON.parse(data);
+```
+
+### Bridge contract
+
+- **argv strings only.** The host validates every element is a string and rejects anything else. Numbers must be `String(x)`.
+- **Sandboxed iframe** with `sandbox="allow-scripts"`. No same-origin → no access to host cookies, localStorage, or storage. `fetch` to outside origins is restricted by browser CORS.
+- **One-way trust**: the host has full agency, the artifact has none unless the user has approved the underlying CLI command.
+
+### Bridge polyfill (copy/paste into every artifact)
+
+The host injects `window.mp.run` automatically. Include this polyfill anyway so the artifact works when previewed outside the app:
+
+```js
+const mp = window.mp || (() => {
+  let nextId = 1;
+  const pending = new Map();
+  window.addEventListener("message", (e) => {
+    const { id, type, result, error } = e.data || {};
+    if (type !== "mp.result" || !pending.has(id)) return;
+    const { resolve, reject } = pending.get(id);
+    pending.delete(id);
+    error ? reject(new Error(error)) : resolve(result);
+  });
+  return {
+    run(argv) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        window.parent.postMessage({ id, type: "mp.run", argv }, "*");
+      });
+    },
+  };
+})();
+```
+
+---
+
+# Design system
+
+This is the meat of this skill. Use these tokens in every artifact you author.
+
+The host (the MoonPay Agents app) injects a set of `--mp-*` CSS variables into the iframe. Inherit them via `var(--mp-thing, fallback)` so the artifact looks correct standalone too.
+
+## Color tokens
+
+```css
+:root {
+  color-scheme: dark;
+
+  /* Surfaces */
+  --bg:        var(--mp-bg-1,      #0a0a0b); /* surface 0 — page background */
+  --bg-2:      var(--mp-bg-2,      #131316); /* surface 1 — cards, panels */
+  --bg-3:      var(--mp-bg-3,      #1c1c20); /* surface 2 — inner cards, hovered states */
+
+  /* Text */
+  --fg:        var(--mp-fg,        #e7e7ea); /* primary text */
+  --fg-dim:    var(--mp-fg-dim,    #8a8a90); /* secondary text — labels, metadata */
+  --fg-faint:  var(--mp-fg-faint,  #5a5a60); /* tertiary text — placeholders, disabled */
+
+  /* Borders & dividers */
+  --border:    var(--mp-border,    #232328); /* default border */
+  --border-2:  var(--mp-border-2,  #2e2e34); /* emphasized border (active inputs, hover) */
+
+  /* Brand */
+  --accent:    var(--mp-accent,    #7e6cff); /* MoonPay purple — primary actions, focus */
+  --accent-2:  var(--mp-accent-2,  #9d8eff); /* lighter purple — hover, gradients */
+}
+```
+
+### Semantic colors (use directly, not via var)
+
+| Role | Hex | When to use |
+|---|---|---|
+| Success / positive | `#56d364` | Gains, completed states, "Active" pills |
+| Negative / loss / error | `#f47067` | Losses, error messages, declined states |
+| Warning | `#f4a261` | Caution, throttle, partial state |
+| Info | `#5cc8e7` | Neutral chains, metadata badges |
+
+## Typography
+
+```css
+:root {
+  --font-sans: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", sans-serif;
+  --font-mono: ui-monospace, "JetBrains Mono", "Fira Code", monospace;
+
+  --text-xs:   11px; /* labels, badges, chart axes */
+  --text-sm:   12px; /* secondary text, table cells */
+  --text-base: 13px; /* body */
+  --text-md:   14px; /* primary text in lists */
+  --text-lg:   18px; /* section titles */
+  --text-xl:   22px; /* card headings */
+  --text-2xl:  32px; /* hero values (e.g. portfolio total) */
+}
+```
+
+Weights: **400** for body, **500** for emphasis, **600** for headings and stat values. Never 700+ in dark UI — too aggressive.
+
+## Spacing scale
+
+4px base unit. Use these as `padding` / `margin` / `gap`.
+
+```css
+--space-1: 4px;   /* tight (icon-text gap) */
+--space-2: 8px;   /* compact (button padding-y, chip gap) */
+--space-3: 12px;  /* default (card inner gap) */
+--space-4: 16px;  /* comfortable (card padding) */
+--space-6: 24px;  /* page padding */
+--space-8: 32px;  /* section separator */
+--space-12: 48px; /* hero spacing */
+```
+
+## Radii
+
+```css
+--radius-sm:   6px;  /* badges, small pills */
+--radius:      12px; /* cards, buttons */
+--radius-lg:   16px; /* hero panels */
+--radius-full: 9999px; /* status pills, avatars */
+```
+
+## Motion
+
+```css
+--ease:        cubic-bezier(0.2, 0.8, 0.2, 1);
+--duration-1:  120ms; /* hover state */
+--duration-2:  180ms; /* card transitions */
+--duration-3:  240ms; /* page-level transitions */
+```
+
+Default to `transition: <prop> var(--duration-1) var(--ease)`. Never over 300ms.
+
+---
+
+# Component recipes
+
+These are the shapes the host app uses. Copy them into your artifact — that's how the catalog stays visually consistent.
+
+## Page wrapper
+
+```html
+<body>
+  <div class="page">
+    <h1>My Artifact</h1>
+    <p class="sub">One-line description of what this artifact shows.</p>
+    <!-- … content … -->
+  </div>
+</body>
+```
+
+```css
+*       { box-sizing: border-box; }
+html,
+body    { margin: 0; padding: 0; }
+body    { background: var(--bg); color: var(--fg); font-family: var(--font-sans); }
+.page   { max-width: 1100px; margin: 0 auto; padding: var(--space-6); min-height: 100vh; }
+h1      { font-size: var(--text-xl); font-weight: 600; margin: 0 0 4px; }
+.sub    { color: var(--fg-dim); font-size: var(--text-sm); margin: 0 0 var(--space-6); }
+h2      { font-size: var(--text-xs); font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; color: var(--fg-dim); margin: var(--space-6) 0 var(--space-3); }
+```
+
+## Card
+
+```html
+<div class="card">
+  <div class="k">Spent this month</div>
+  <div class="v">$847.20</div>
+  <div class="sub-v">12 transactions</div>
+</div>
+```
+
+```css
+.card    { background: var(--bg-2); border: 1px solid var(--border); border-radius: var(--radius); padding: var(--space-4); }
+.k       { color: var(--fg-dim); font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px; }
+.v       { font-size: var(--text-xl); font-weight: 600; font-variant-numeric: tabular-nums; }
+.sub-v   { color: var(--fg-dim); font-size: var(--text-xs); margin-top: 2px; }
+```
+
+## Stat row (4-up grid)
+
+```html
+<div class="stat-row">
+  <div class="card"><div class="k">Today</div><div class="v">$120</div></div>
+  <div class="card"><div class="k">This week</div><div class="v">$640</div></div>
+  <div class="card"><div class="k">This month</div><div class="v">$2,340</div></div>
+  <div class="card"><div class="k">YTD</div><div class="v">$18,200</div></div>
+</div>
+```
+
+```css
+.stat-row { display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--space-2); margin-bottom: var(--space-6); }
+@media (max-width: 800px) { .stat-row { grid-template-columns: repeat(2, 1fr); } }
+```
+
+## Button
+
+```html
+<button class="btn">Primary action</button>
+<button class="btn-ghost">Secondary</button>
+```
+
+```css
+.btn        { background: var(--accent); color: white; border: 0; border-radius: var(--radius); padding: var(--space-2) var(--space-4); font-size: var(--text-sm); font-weight: 500; cursor: pointer; transition: background var(--duration-1) var(--ease); }
+.btn:hover  { background: var(--accent-2); }
+.btn-ghost  { background: transparent; color: var(--fg); border: 1px solid var(--border); border-radius: var(--radius); padding: var(--space-2) var(--space-4); font-size: var(--text-sm); cursor: pointer; transition: border-color var(--duration-1) var(--ease); }
+.btn-ghost:hover { border-color: var(--border-2); }
+```
+
+## Status pill
+
+```html
+<span class="pill pill-success"><span class="dot"></span>Active</span>
+<span class="pill pill-warning"><span class="dot"></span>Throttled</span>
+<span class="pill pill-error"><span class="dot"></span>Declined</span>
+```
+
+```css
+.pill          { display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; border-radius: var(--radius-full); font-size: var(--text-xs); font-weight: 500; }
+.pill .dot     { width: 6px; height: 6px; border-radius: 50%; }
+.pill-success { background: rgba(86, 211, 100, 0.12); color: #56d364; } .pill-success .dot { background: #56d364; }
+.pill-warning { background: rgba(244, 162, 97, 0.12); color: #f4a261; } .pill-warning .dot { background: #f4a261; }
+.pill-error   { background: rgba(244, 112, 103, 0.12); color: #f47067; } .pill-error   .dot { background: #f47067; }
+```
+
+## Text input
+
+```html
+<input class="input" type="text" placeholder="0x…" />
+<input class="input" type="text" disabled value="locked" />
+<input class="input input-error" type="text" value="not a valid address" />
+```
+
+```css
+.input        { width: 100%; background: var(--bg-2); color: var(--fg); border: 1px solid var(--border); border-radius: var(--radius); padding: var(--space-2) var(--space-3); font-size: var(--text-sm); font-family: var(--font-sans); transition: border-color var(--duration-1) var(--ease), box-shadow var(--duration-1) var(--ease); }
+.input::placeholder { color: var(--fg-faint); }
+.input:hover  { border-color: var(--border-2); }
+.input:focus  { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 20%, transparent); }
+.input:disabled { color: var(--fg-faint); cursor: not-allowed; }
+.input-error  { border-color: #f47067; }
+.input-error:focus { box-shadow: 0 0 0 3px rgba(244, 112, 103, 0.18); }
+```
+
+## Select (native, restyled)
+
+```html
+<select class="select">
+  <option>USDC</option>
+  <option>USDT</option>
+  <option>SOL</option>
+</select>
+```
+
+```css
+.select { appearance: none; background: var(--bg-2) url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'><path fill='%238a8a90' d='M2 4l4 4 4-4z'/></svg>") right 10px center no-repeat; color: var(--fg); border: 1px solid var(--border); border-radius: var(--radius); padding: var(--space-2) 32px var(--space-2) var(--space-3); font-size: var(--text-sm); font-family: var(--font-sans); cursor: pointer; }
+.select:hover { border-color: var(--border-2); }
+.select:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 20%, transparent); }
+```
+
+## Switch (toggle)
+
+```html
+<label class="switch">
+  <input type="checkbox" />
+  <span class="track"></span>
+  <span class="label">Auto-refresh</span>
+</label>
+```
+
+```css
+.switch        { display: inline-flex; align-items: center; gap: var(--space-2); cursor: pointer; font-size: var(--text-sm); user-select: none; }
+.switch input  { position: absolute; opacity: 0; pointer-events: none; }
+.switch .track { position: relative; width: 32px; height: 18px; background: var(--bg-3); border: 1px solid var(--border); border-radius: var(--radius-full); transition: background var(--duration-1) var(--ease); }
+.switch .track::after { content: ""; position: absolute; top: 2px; left: 2px; width: 12px; height: 12px; background: var(--fg-dim); border-radius: 50%; transition: transform var(--duration-1) var(--ease), background var(--duration-1) var(--ease); }
+.switch input:checked + .track { background: color-mix(in srgb, var(--accent) 30%, var(--bg-3)); border-color: var(--accent); }
+.switch input:checked + .track::after { transform: translateX(14px); background: var(--accent); }
+```
+
+## Checkbox
+
+```html
+<label class="check">
+  <input type="checkbox" />
+  <span class="box"></span>
+  <span>Include declined transactions</span>
+</label>
+```
+
+```css
+.check       { display: inline-flex; align-items: center; gap: var(--space-2); cursor: pointer; font-size: var(--text-sm); user-select: none; }
+.check input { position: absolute; opacity: 0; pointer-events: none; }
+.check .box  { width: 16px; height: 16px; background: var(--bg-2); border: 1px solid var(--border); border-radius: 4px; display: inline-flex; align-items: center; justify-content: center; transition: background var(--duration-1) var(--ease), border-color var(--duration-1) var(--ease); }
+.check input:checked + .box { background: var(--accent); border-color: var(--accent); }
+.check input:checked + .box::after { content: ""; width: 10px; height: 6px; border-left: 2px solid white; border-bottom: 2px solid white; transform: rotate(-45deg) translate(1px, -1px); }
+```
+
+## Tabs
+
+```html
+<div class="tabs" role="tablist">
+  <button class="tab is-active" data-tab="overview">Overview</button>
+  <button class="tab" data-tab="transactions">Transactions</button>
+  <button class="tab" data-tab="wallets">Wallets</button>
+</div>
+```
+
+```css
+.tabs        { display: flex; gap: 4px; border-bottom: 1px solid var(--border); margin-bottom: var(--space-4); }
+.tab         { background: transparent; color: var(--fg-dim); border: 0; border-bottom: 2px solid transparent; padding: var(--space-2) var(--space-3); font-size: var(--text-sm); font-weight: 500; cursor: pointer; transition: color var(--duration-1) var(--ease), border-color var(--duration-1) var(--ease); margin-bottom: -1px; }
+.tab:hover   { color: var(--fg); }
+.tab.is-active { color: var(--fg); border-bottom-color: var(--accent); }
+```
+
+```js
+// Wire-up: toggle .is-active and show the matching panel
+document.querySelectorAll(".tab").forEach(t => t.addEventListener("click", () => {
+  document.querySelectorAll(".tab").forEach(x => x.classList.toggle("is-active", x === t));
+  document.querySelectorAll("[data-panel]").forEach(p => p.hidden = p.dataset.panel !== t.dataset.tab);
+}));
+```
+
+## Dialog (modal)
+
+Use the native `<dialog>` element — it gets accessibility for free.
+
+```html
+<dialog id="confirm-dialog" class="dialog">
+  <h3>Approve $500 delegation?</h3>
+  <p>This signs an SPL Approve transaction. The cap is the loss ceiling if anything goes wrong.</p>
+  <div class="dialog-actions">
+    <button class="btn-ghost" onclick="document.getElementById('confirm-dialog').close()">Cancel</button>
+    <button class="btn" onclick="approveDelegation()">Approve</button>
+  </div>
+</dialog>
+
+<button class="btn" onclick="document.getElementById('confirm-dialog').showModal()">Delegate wallet</button>
+```
+
+```css
+.dialog            { background: var(--bg-2); color: var(--fg); border: 1px solid var(--border); border-radius: var(--radius-lg); padding: var(--space-6); max-width: 420px; box-shadow: 0 24px 60px -20px rgba(0, 0, 0, 0.6); }
+.dialog::backdrop  { background: rgba(0, 0, 0, 0.6); backdrop-filter: blur(2px); }
+.dialog h3         { margin: 0 0 var(--space-2); font-size: var(--text-md); font-weight: 600; }
+.dialog p          { margin: 0 0 var(--space-4); color: var(--fg-dim); font-size: var(--text-sm); line-height: 1.5; }
+.dialog-actions    { display: flex; justify-content: flex-end; gap: var(--space-2); }
+```
+
+## Tooltip
+
+CSS-only, attribute-driven. Add `data-tooltip` to anything.
+
+```html
+<span data-tooltip="On-chain delegation transaction">tx hash</span>
+```
+
+```css
+[data-tooltip]               { position: relative; cursor: help; }
+[data-tooltip]::after        { content: attr(data-tooltip); position: absolute; bottom: calc(100% + 6px); left: 50%; transform: translateX(-50%); background: var(--bg-3); color: var(--fg); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 6px 10px; font-size: var(--text-xs); white-space: nowrap; opacity: 0; pointer-events: none; transition: opacity var(--duration-1) var(--ease); }
+[data-tooltip]:hover::after  { opacity: 1; }
+```
+
+## Skeleton (loading placeholder)
+
+```html
+<div class="skel" style="width:120px;height:14px"></div>
+```
+
+```css
+.skel { background: linear-gradient(90deg, var(--bg-2) 0%, var(--bg-3) 50%, var(--bg-2) 100%); background-size: 200% 100%; border-radius: var(--radius-sm); animation: skel-shimmer 1.4s infinite; }
+@keyframes skel-shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }
+```
+
+## Empty state
+
+```html
+<div class="empty">
+  No transactions yet.
+  <div class="hint">Click <strong>Start shopping</strong> above to make the first one.</div>
+</div>
+```
+
+```css
+.empty       { background: var(--bg-2); border: 1px dashed var(--border); border-radius: var(--radius); padding: var(--space-6); text-align: center; color: var(--fg-dim); font-size: var(--text-sm); }
+.empty .hint { color: var(--fg-faint); font-size: var(--text-xs); margin-top: 4px; }
+```
+
+## Loading / error
+
+Every `mp.run` call should produce a visible state for both — never silent.
+
+```css
+.loading { color: var(--fg-dim); font-size: var(--text-sm); padding: var(--space-4) 0; }
+.error   { color: #f47067; font-family: var(--font-mono); font-size: var(--text-xs); padding: var(--space-3) 0; }
+```
+
+## Charts
+
+Use [Chart.js](https://www.chartjs.org/) as the default. It loads from CDN, supports the chart types artifacts typically need (line, bar, doughnut, sparkline), is easy to theme with our tokens, and the agent already knows it well.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<canvas id="chart" style="max-height: 260px"></canvas>
+```
+
+```js
+// Read design tokens off the document so the chart inherits the host theme.
+const css = getComputedStyle(document.documentElement);
+const fg     = css.getPropertyValue("--fg").trim()     || "#e7e7ea";
+const fgDim  = css.getPropertyValue("--fg-dim").trim() || "#8a8a90";
+const border = css.getPropertyValue("--border").trim() || "#232328";
+const accent = css.getPropertyValue("--accent").trim() || "#7e6cff";
+
+// Apply defaults once, before instantiating any charts.
+Chart.defaults.color            = fgDim;
+Chart.defaults.borderColor      = border;
+Chart.defaults.font.family      = "-apple-system, Inter, sans-serif";
+Chart.defaults.font.size        = 11;
+Chart.defaults.plugins.legend.labels.color  = fg;
+Chart.defaults.plugins.tooltip.backgroundColor = "#1c1c20";
+Chart.defaults.plugins.tooltip.titleColor      = fg;
+Chart.defaults.plugins.tooltip.bodyColor       = fgDim;
+Chart.defaults.plugins.tooltip.borderColor     = border;
+Chart.defaults.plugins.tooltip.borderWidth     = 1;
+Chart.defaults.plugins.tooltip.padding         = 10;
+Chart.defaults.plugins.tooltip.cornerRadius    = 8;
+
+new Chart(document.getElementById("chart"), {
+  type: "line",
+  data: {
+    labels: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
+    datasets: [{
+      label: "Portfolio",
+      data: [12400, 12550, 12480, 12700, 12860, 13020, 13180],
+      borderColor: accent,
+      backgroundColor: "rgba(126, 108, 255, 0.12)",
+      fill: true,
+      tension: 0.3,
+      pointRadius: 0,
+      borderWidth: 2,
+    }],
+  },
+  options: {
+    maintainAspectRatio: false,
+    plugins: { legend: { display: false } },
+    scales: {
+      x: { grid: { display: false }, ticks: { color: fgDim } },
+      y: { grid: { color: border }, ticks: { color: fgDim, callback: v => "$" + v.toLocaleString() } },
+    },
+  },
+});
+```
+
+### Chart color palette (when you need multiple series)
+
+```js
+const SERIES = [
+  "#7e6cff", // accent (primary)
+  "#5cc8e7", // info / chain
+  "#56d364", // success
+  "#f4a261", // warning
+  "#f47067", // negative
+  "#fbbf24", // shopping
+  "#34d399", // hardware
+  "#9d8eff", // accent-2
+];
+```
+
+Use them in order. Two series → first two. Six categories → first six. Don't pick at random — the order matters for consistency across artifacts.
+
+### Sparkline shorthand
+
+For inline sparklines in tables / stat cards, set `pointRadius: 0`, `borderWidth: 1.5`, and disable both axes:
+
+```js
+new Chart(canvas, {
+  type: "line",
+  data: { labels: data.map((_, i) => i), datasets: [{ data, borderColor: accent, borderWidth: 1.5, pointRadius: 0, fill: false }] },
+  options: { maintainAspectRatio: false, plugins: { legend: { display: false }, tooltip: { enabled: false } }, scales: { x: { display: false }, y: { display: false } } },
+});
+```
+
+### Alternatives
+
+- **uPlot** — better for high-density time-series (100K+ points). Use when Chart.js feels slow.
+- **D3** — only when you need a chart Chart.js doesn't have (sankey, force-directed, custom geometries). Has a learning cliff.
+- **Echarts** — also fine; treat as a Chart.js replacement, not an addition.
+
+If you reach for Recharts, Plotly, or anything React-flavored — don't. Artifacts are vanilla; keep them that way.
+
+## Number formatting
+
+Two rules:
+1. Use `font-variant-numeric: tabular-nums` for any column of numbers so digits align vertically.
+2. Format USD via `Intl.NumberFormat`:
+   ```js
+   const fmtUsd = (n) => "$" + n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+   ```
+
+---
+
+---
+
+# Living references
+
+The MoonPay Agents app ships built-in artifacts. These are the canonical
+examples — read them when you need to see how the design system + bridge
+look in a real artifact. They live inside the moonpay-agents app bundle at
+`src-tauri/artifacts/<slug>.html`.
+
+| Artifact | What it shows |
+|---|---|
+| `moon-agents-card` | Hero panel with embedded image, stat row, status pill, delegated-wallet cards with progress meters, on-chain explorer links, transactions list with empty state, "Start shopping" CTA that deep-links into a chat via the `mp.openChat` bridge extension. The reference for any "card with live status + history" artifact. |
+
+When you're authoring something new, **read the closest built-in artifact first**. Copy its structure rather than inventing your own — that's the fastest way to make the catalog feel coherent.
+
+## Authoring checklist
+
+Before saving an artifact:
+
+1. **Frontmatter present and matches filename.** `name:` field === filename without `.html`.
+2. **Bridge polyfill included.**
+3. **Design tokens used everywhere.** `var(--mp-*)` for colors / radii / spacing — no hardcoded `#hexvalues` for theme colors. Semantic colors (success/error) can be hardcoded since they don't theme.
+4. **Loading + error states.** Every `mp.run` call wrapped in try/catch with a visible state.
+5. **Self-contained.** No external CSS or JS files. CDN libs OK but optional.
+6. **Tight scope.** Each artifact does one thing well. If you find yourself wanting two views, that's two artifacts.
+
+## Common pitfalls
+
+- **Numbers as argv.** `mp.run([..., size])` fails — the host rejects non-strings. Use `String(size)`.
+- **Forgetting `--json`.** Most `mp` commands need `--json` to return parseable output.
+- **CORS for outside APIs.** `fetch("https://api.example.com")` works from inside the iframe only if that origin sends CORS headers. Prefer routing through `mp` if possible.
+- **Hardcoded colors.** `background: #1c1c20` won't theme if MoonPay re-skins. Use `var(--mp-bg-3, #1c1c20)`.
+- **Mock data unmarked.** It's fine to ship a mocked artifact, but leave a `// MOCK` comment so the agent doesn't ship it as real.
+
+## Minimal starter
+
+```html
+<!--
+name: gas-tracker
+title: Gas Tracker
+description: Current gas prices across Ethereum, Polygon, and Base.
+tags: [tracker, gas]
+-->
+<!doctype html>
+<html><head><meta charset="utf-8"><title>Gas Tracker</title>
+<style>
+  :root {
+    color-scheme: dark;
+    --bg: var(--mp-bg-1, #0a0a0b);
+    --bg-2: var(--mp-bg-2, #131316);
+    --fg: var(--mp-fg, #e7e7ea);
+    --fg-dim: var(--mp-fg-dim, #8a8a90);
+    --border: var(--mp-border, #232328);
+    --accent: var(--mp-accent, #7e6cff);
+    --radius: var(--mp-radius, 12px);
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font-family: -apple-system, Inter, sans-serif; }
+  .page { max-width: 600px; margin: 0 auto; padding: 24px; }
+  h1 { font-size: 18px; font-weight: 600; margin: 0 0 4px; }
+  .sub { color: var(--fg-dim); font-size: 13px; margin: 0 0 24px; }
+  .row { display: flex; justify-content: space-between; padding: 12px 16px; background: var(--bg-2); border: 1px solid var(--border); border-radius: var(--radius); margin-bottom: 8px; font-variant-numeric: tabular-nums; }
+  .name { text-transform: capitalize; }
+  .gwei { color: var(--accent); font-weight: 600; }
+  .loading { color: var(--fg-dim); font-size: 13px; }
+  .error { color: #f47067; font-family: ui-monospace, monospace; font-size: 12px; }
+</style></head>
+<body>
+<div class="page">
+  <h1>Gas tracker</h1>
+  <p class="sub">Current gas prices across major chains.</p>
+  <div id="rows" class="loading">Loading…</div>
+</div>
+<script>
+  // Bridge polyfill — copy into every artifact
+  const mp = window.mp || (() => {
+    let nextId = 1; const pending = new Map();
+    window.addEventListener("message", (e) => {
+      const { id, type, result, error } = e.data || {};
+      if (type !== "mp.result" || !pending.has(id)) return;
+      const { resolve, reject } = pending.get(id);
+      pending.delete(id);
+      error ? reject(new Error(error)) : resolve(result);
+    });
+    return { run(argv) { const id = nextId++; return new Promise((resolve, reject) => { pending.set(id, { resolve, reject }); window.parent.postMessage({ id, type: "mp.run", argv }, "*"); }); } };
+  })();
+
+  (async () => {
+    try {
+      const chains = ["ethereum", "polygon", "base"];
+      const results = await Promise.all(chains.map(c =>
+        mp.run(["chain", "gas-price", "--chain", c, "--json"]).then(r => JSON.parse(r))
+      ));
+      document.getElementById("rows").classList.remove("loading");
+      document.getElementById("rows").innerHTML = chains.map((c, i) =>
+        `<div class="row"><span class="name">${c}</span><span class="gwei">${results[i].gwei} gwei</span></div>`
+      ).join("");
+    } catch (e) {
+      document.getElementById("rows").outerHTML =
+        `<div class="error">Failed to load: ${e.message}</div>`;
+    }
+  })();
+</script>
+</body></html>
+```
+
+That's the shape. Color tokens, font sizes, spacing, radii, error state, tabular nums — all the design system rules in one short file.
+
+## Related
+
+- **moonpay-skill-builder** — author procedural skills (the chat-side companion to artifacts).
+- **moonpay-automation-builder** — schedule a skill to run on a cron.