SKILL.md- the skill, written out in plain English

const skillMdPath = join(cwd, "state/skills", slug, "SKILL.md");
if (!existsSync(skillMdPath)) {
  throw new Error(`Skill not found: ${slug}`);
}

// surface: Human surface name
// intents: phrase one; phrase two; phrase three
// response: Short middle-chat sentence when this surface opens.

const tmp = `${resourcesDir}/ui.openui.tmp.${process.pid}`;
writeFileSync(tmp, openui);
renameSync(tmp, outputPath);

# Generate to stdout (for inspection)
npx tsx state/lib/dashboard-builder.ts ai-spend

# Generate and write atomically to the skill's resources folder
npx tsx state/lib/dashboard-builder.ts dogfood-loop > state/skills/dogfood-loop/resources/ui.openui

# Compare before/after
npx tsx state/lib/dashboard-builder.ts email-send-tick > /tmp/email-send-tick.new
diff state/skills/email-send-tick/resources/ui.openui /tmp/email-send-tick.new | head -20

AGENTS.md- what the AI loads when this skill comes up

# Generate to stdout (inspection)
npx tsx state/lib/dashboard-builder.ts <slug>

# Generate the default dashboard to stdout
npx tsx state/lib/dashboard-builder.ts <slug>

# Validate and atomically write any OpenUI resource
npx tsx state/lib/openui-resource-contract.ts write-file <slug> /tmp/resource.openui ui.openui
npx tsx state/lib/openui-resource-contract.ts write-file <slug> /tmp/schedule.openui schedule.openui

# Test syntax (first line only)
npx tsx state/lib/dashboard-builder.ts <slug> | head -1

# Compare before/after
diff state/skills/<slug>/resources/ui.openui <(npx tsx state/lib/dashboard-builder.ts <slug>)

# List all OpenUI resources
find state/skills -path "*/resources/*.openui" | wc -l

# Find missing default dashboards
for d in state/skills/*/; do [ ! -f "$d/resources/ui.openui" ] && echo "$(basename $d)"; done

echo "[$(date -u +%FT%TZ)] dashboard-builder: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-dashboard-builder/api.ts -- Auto-generate resources/ui.openui for any skill.
 * Legacy module name; the output is a skill-owned OpenUI resource, not always
 * a dashboard-shaped surface.
 *
 * The system extends itself: given a skill slug, read its SKILL.md + eval logs,
 * then emit a tailored OpenUI Lang resource via LLM composition.
 * Falls back to heuristic templates if the LLM call fails.
 *
 * Usage:
 *   npx tsx state/lib/dashboard-builder.ts <slug>
 *   npx tsx state/lib/dashboard-builder.ts ai-spend > /tmp/ai-spend.regen.openui
 *
 * Or import as module:
 *   import { generateDashboard } from "./dashboard-builder.ts";
 *   const openui = await generateDashboard("dogfood-loop");
 */

import { readFileSync, existsSync } from "fs";
import { join, resolve } from "path";
import { realpathSync } from "fs";
import { dispatchFor, readDefaultModel, readDispatchConfig } from "./dispatch.ts";
import { findOpenUiResourceIssues, writeOpenUiResource } from "./openui-resource-contract.ts";

interface SkillMeta {
  name: string;
  description: string;
  category?: string;
  type?: string;
}

// --- OpenUI Fallback Templates ---

const TEMPLATE_BASIC = (slug: string): string => `evals = Query("get_evals", {slug: "${slug}", days: 7}, {evals: []}, 60)

header = CardHeader("${slug} — last 7 days")
runCount = @Count(evals.evals)
avgScore = @Avg(evals.evals.score)
lastRun = @First(@Sort(evals.evals, "ts", "desc"))
avgScoreText = "" + @Round(avgScore, 2)
lastTsText = "" + lastRun.ts

kpiRow = Stack([
  Card([TextContent("Runs", "small"), TextContent("" + runCount, "large-heavy")]),
  Card([TextContent("Avg score", "small"), TextContent(avgScoreText, "medium")]),
  Card([TextContent("Last", "small"), TextContent(lastTsText, "small")])
], "row", "s", "stretch", "start", true)

table = Table([
  Col("When", evals.evals.ts),
  Col("Score", evals.evals.score),
  Col("Note", evals.evals.notes)
])

root = Stack([header, kpiRow, Card([table])])
`;

const TEMPLATE_PIPELINE = (slug: string): string => `evals = Query("get_evals", {slug: "${slug}", days: 7}, {evals: []}, 60)

header = CardHeader("${slug} — pipeline status")
runCount = @Count(evals.evals)
successCount = @Count(@Filter(evals.evals, "score", "==", 1.0))
failCount = @Count(@Filter(evals.evals, "score", "<", 1.0))

kpiRow = Stack([
  Card([TextContent("Runs (7d)", "small"), TextContent("" + runCount, "large-heavy")]),
  Card([TextContent("Successes", "small"), TextContent("" + successCount, "medium")]),
  Card([TextContent("Failures", "small"), TextContent("" + failCount, "medium")])
], "row", "s", "stretch", "start", true)

failures = @Filter(evals.evals, "score", "<", 1.0)
failureTable = Table([
  Col("Timestamp", failures.ts),
  Col("Score", failures.score),
  Col("Issue", failures.primary_issue)
])

table = Table([
  Col("Timestamp", evals.evals.ts),
  Col("Score", evals.evals.score),
  Col("Note", evals.evals.notes)
])

root = Stack([header, kpiRow, Card([TextContent("Recent failures", "small-heavy"), failureTable]), Card([TextContent("All runs", "small-heavy"), table])])
`;

const TEMPLATE_CHANNEL = (slug: string): string => `evals = Query("get_evals", {slug: "${slug}", days: 7}, {evals: []}, 60)
recent = Query("get_recent", {limit: 30}, {evals: [], total: 0, truncated: false}, 30)

header = CardHeader("${slug} — activity")
runCount = @Count(evals.evals)
sortedEvals = @Sort(evals.evals, "ts", "desc")
lastRun = @First(sortedEvals)
latestScoreText = "" + lastRun.score

kpiRow = Stack([
  Card([TextContent("Activity (7d)", "small"), TextContent("" + runCount, "large-heavy")]),
  Card([TextContent("Latest score", "small"), TextContent(latestScoreText, "medium")])
], "row", "s", "stretch", "start", true)

recentItems = @Filter(recent.evals, "skill", "==", "${slug}")
activityTable = Table([
  Col("Time", recentItems.ts),
  Col("Verb", recentItems.verb),
  Col("Score", recentItems.score),
  Col("Note", recentItems.note)
])

allTable = Table([
  Col("When", evals.evals.ts),
  Col("Score", evals.evals.score),
  Col("Note", evals.evals.notes)
])

root = Stack([header, kpiRow, Card([TextContent("Recent activity", "small-heavy"), activityTable]), Card([TextContent("All runs", "small-heavy"), allTable])])
`;

const TEMPLATE_SYSTEM = (slug: string): string => `evals = Query("get_evals", {slug: "${slug}", days: 7}, {evals: []}, 60)
full = Query("get_full_state", {}, {agents: [], skills: []}, 120)

header = CardHeader("${slug}")
runCount = @Count(evals.evals)
avgScore = @Avg(evals.evals.score)
avgScoreText = "" + @Round(avgScore, 2)

kpiRow = Stack([
  Card([TextContent("System runs", "small"), TextContent("" + runCount, "large-heavy")]),
  Card([TextContent("Avg score", "small"), TextContent(avgScoreText, "medium")])
], "row", "s", "stretch", "start", true)

table = Table([
  Col("When", evals.evals.ts),
  Col("Score", evals.evals.score),
  Col("Note", evals.evals.notes)
])

metadata = Card([
  TextContent("${slug} — system skill", "small-heavy"),
  TextContent("Monitors and maintains snappy-os infrastructure", "small")
])

root = Stack([header, kpiRow, metadata, Card([table])])
`;

// --- Skill Type Detection (fallback heuristic) ---

function detectSkillType(skillMeta: SkillMeta): string {
  const desc = (skillMeta.description || "").toLowerCase();
  const cat = (skillMeta.category || "").toLowerCase();

  if (skillMeta.type === "channel") return "channel";
  if (skillMeta.type === "system") return "system";
  if (skillMeta.type === "reference") return "system";

  if (
    cat === "channels" ||
    cat === "integration" ||
    desc.includes("send") ||
    desc.includes("publish") ||
    desc.includes("dispatch")
  ) {
    return "channel";
  }

  if (
    cat === "system" ||
    cat === "admin" ||
    cat === "memory" ||
    desc.includes("pipeline") ||
    desc.includes("queue") ||
    desc.includes("monitor")
  ) {
    return "system";
  }

  if (
    desc.includes("step") ||
    desc.includes("phase") ||
    desc.includes("stage") ||
    /(?<![a-z-])process(?![a-z-])/.test(desc)
  ) {
    return "pipeline";
  }

  return "basic";
}

function generateFromTemplate(slug: string, meta: SkillMeta): string {
  const skillType = detectSkillType(meta);
  switch (skillType) {
    case "pipeline": return TEMPLATE_PIPELINE(slug);
    case "channel": return TEMPLATE_CHANNEL(slug);
    case "system": return TEMPLATE_SYSTEM(slug);
    default: return TEMPLATE_BASIC(slug);
  }
}

// --- LLM Composition ---

const LANG_SYSTEM_PROMPT = `You compose live skill-owned OpenUI resources in OpenUI Lang for snappy-os skills.

AVAILABLE DATA (Query tool names + return shape):
  - get_evals({slug, days}) → {evals: [{ts, score, notes, primary_issue, ...}]}
  - get_agents() → {agents: [{name, status, lastRun, score, ...}]}
  - get_skills() → {skills: [{name, runs, score, lastRun, ...}]}
  - get_recent({limit}) → {evals: [{ts, skill, verb, score, note, primary_issue, ...}], total, truncated, last_updated}
  - get_dispatch_log() → {entries: [{ts, model, durationMs, ...}]}
  - get_inbox_email({days}) → {messages: [{from, subject, ts, ...}]}
  - get_inbox_slack({}) → {messages: [{channel_name, text, ts, ...}]}
  - get_inbox_calendar({days}) → {events: [{summary, start, location, ...}]}
  - get_brain() → {nodes: [...], edges: [...]}
  - get_recall({days}) → {threads: [...], evals: [...], commits: [...]}

LANG PRIMITIVES (use these and only these):
  Card, CardHeader, Stack, Col, Table, BarChart, LineChart, AreaChart, PieChart, Tag, TagBlock, Button, Buttons, Callout, TextCallout, Steps, StepsItem, Tabs, TabItem, Accordion, AccordionItem, ListBlock, ListItem, MarkDownRenderer, Image, ImageBlock, Separator, TextContent, CodeBlock

OFFICIAL OPENUI SIGNATURES:
  - Callout(variant, title, description) where variant is "info" | "warning" | "error" | "success" | "neutral".
    Do NOT emit legacy Callout("ok", "...") or Callout("warn", "...").
  - StepsItem(title, details). Details is required; use "done", "running", "pending", or a short status phrase.

LANG SYNTAX RULES:
  - Every variable assignment uses =
  - Function calls: BarChart(title, [val1, val2], "blue")  positional args
  - Stack accepts arrays: Stack([Card([...]), Card([...])], "row", "s", "stretch", "start", true)
  - Any horizontal Stack must pass wrap=true as the 6th positional arg so generated components fit the chat viewport.
  - Use "column" for vertical Stack direction. Never emit legacy "col".
  - Filter/map: @Filter(arr, field, op, value), @Count(arr), @Sum(arr.field), @Avg(arr.field)
  - Supported @ built-ins are only @Count, @Sum, @Avg, @Min, @Max, @First, @Last, @Filter, @Sort, @Round, @Abs, @Floor, @Ceil, @Each, @Run, @Set, @Reset, @ToAssistant, @OpenUrl.
  - Never emit unsupported helpers such as @If, @Coalesce, @Slice, @Get, @Distinct, or @FormatTime.
  - The final assignment MUST be root = <expression>
  - Strings must be double-quoted; arrays use []; objects use {key: value}
  - Ternary expressions are valid OpenUI Lang; use them sparingly and keep them readable.
  - NO Python list comprehensions, NO JS template literals, NO nullish coalescing, NO pipe chains inside Lang
  - Every Query() needs a default value as 3rd arg and refresh interval (in seconds) as 4th arg

STYLE GUIDE (snappy-os tone):
  - Workshop, not showroom. No bouncy animations or marketing language.
  - Use tokens via OpenUI primitives, do not inline color hex.
  - Headers: short and direct. "X — last 7 days" not "Welcome to your X dashboard!"
  - No emojis, no em dashes, no exclamation points.
  - First-line stats over prose. Tables over paragraphs.

OUTPUT RULES:
  - Output ONLY the OpenUI Lang code. No explanation, no markdown fences, no comments.
  - The very first character of your output must be a letter (start of a variable name).
  - Do not wrap in backticks. Do not prefix with "Here is" or similar.`;

function buildUserPrompt(slug: string, meta: SkillMeta, skillBody: string): string {
  return `THE SKILL:
  name: ${slug}
  category: ${meta.category || "unset"}
  description: ${meta.description}

Body of SKILL.md (prose that defines behavior):
${skillBody.slice(0, 3000)}

YOUR JOB:
  Compose an OpenUI resource that answers "what is happening with this skill right now?" using a layout structure that matches THIS skill's purpose.

  LAYOUT BY SKILL TYPE — mandatory. Do NOT default to "Card + CardHeader + description + tags". That is the lazy fallback and it is FORBIDDEN.

  PIPELINE skill (npm publish, scheduled job, cron worker, send-tick, queue drainer):
    MUST use Steps([StepsItem(...), ...]) to show the pipeline stages.
    MUST show a KPI row: throughput / failure-rate / last-run.
    MUST show a recent-failures Table.
    Shape: Stack([header, phases, kpiRow, Card([failureTable])])
    Example:
      evals = Query("get_evals", {slug: "${slug}", days: 7}, {evals: []}, 60)
      header = CardHeader("${slug} — pipeline status")
      phases = Steps([StepsItem("check", "done"), StepsItem("run", "running"), StepsItem("tag", "pending")])
      successCount = @Count(@Filter(evals.evals, "score", "==", 1.0))
      failCount = @Count(@Filter(evals.evals, "score", "<", 1.0))
      kpiRow = Stack([Card([TextContent("Runs", "small"), TextContent("" + @Count(evals.evals), "large-heavy")]), Card([TextContent("Failures", "small"), TextContent("" + failCount, "medium")])], "row", "s", "stretch", "start", true)
      failures = @Filter(evals.evals, "score", "<", 1.0)
      failTable = Table([Col("When", failures.ts), Col("Issue", failures.primary_issue)])
      root = Stack([header, phases, kpiRow, Card([failTable])])

  CHANNEL skill (email, slack, calendar, inbox, message delivery, notifications):
    MUST use Tabs([TabItem("All", ...), TabItem("Recent", ...), TabItem("Errors", ...)]) to slice data.
    Each tab contains a Table with message-level rows.
    Shape: Stack([header, kpiRow, Tabs([TabItem("All", allTable), TabItem("Errors", errTable)])])

  SYSTEM skill (head-screen, brain-insights, ai-spend, dogfood-loop, monitor, health check):
    MUST use Callout("success" or "warning", "Current health", "<status text>") at the top for current health.
    MUST show a KPI grid of 4 cards in a row.
    MUST show a recent-activity feed at the bottom.
    Shape: Stack([header, statusCallout, kpiGrid, activityFeed])

  KNOWLEDGE / REFERENCE skill (now, dashboard-builder, catalog, index, reference):
    MUST use Accordion([AccordionItem(...), ...]) for collapsible context sections.
    MUST use Tag / TagBlock for major facets.
    MUST use a Callout for the key prose context.
    Shape: Stack([header, facetTags, Accordion([...]), Callout("info", "Context", "...")])

  BASIC skill (anything else):
    Use run count + avg score KPI row + recent runs table.
    Still MUST NOT use a plain generic Card+description. Show numbers.

  Pick the Query sources that are most relevant. Not every skill needs get_evals — an inbox skill should show inbox data. Do not force get_evals if it does not fit.

  IMPORTANT: Keep the total output under 60 lines. Use at most 3-4 sections. Prefer concise, high-signal layouts over exhaustive ones. The generated surface must fit on screen without scrolling.

  Output ONLY the OpenUI Lang. Start immediately with the first variable assignment.`;
}

function validateLang(output: string): boolean {
  const trimmed = output.trim();
  if (!trimmed) return false;
  // Must not start with backticks or explanation prose
  if (trimmed.startsWith("```") || trimmed.startsWith("Here ") || trimmed.startsWith("I ")) return false;
  // First non-empty line must contain = (variable assignment)
  const firstLine = trimmed.split("\n").find(l => l.trim().length > 0) || "";
  if (!firstLine.includes("=")) return false;
  // Must contain root =
  if (!trimmed.includes("root =")) return false;
  // Must contain at least one Query call
  if (!trimmed.includes('Query("get_')) return false;
  const runtimeIssues = findOpenUiResourceIssues(trimmed);
  if (runtimeIssues.length > 0) {
    process.stderr.write(`[dashboard-builder] invalid OpenUI resource: ${runtimeIssues[0].detail}\n`);
    return false;
  }
  return true;
}

function normalizeLangOutput(output: string): string {
  const trimmed = output.trim();
  const toolMatch = trimmed.match(/\[\[TOOL:Lang\]\]([\s\S]*?)\[\[\/TOOL\]\]/);
  if (toolMatch?.[1]) return toolMatch[1].trim();

  const fenceMatch = trimmed.match(/```(?:openui|lang)?\s*([\s\S]*?)```/i);
  if (fenceMatch?.[1]) return fenceMatch[1].trim();

  return trimmed;
}

async function callLLMViaDispatch(slug: string, systemPrompt: string, userPrompt: string): Promise<string> {
  const axis = readDispatchConfig().subagent;
  const modelLabel = axis.model === "auto" ? readDefaultModel().slug : axis.model;
  process.stderr.write(`[dashboard-builder] composing ${slug} via ${axis.backend}/${modelLabel}\n`);

  const result = await dispatchFor("subagent", {
    prompt: userPrompt,
    systemPrompt,
    cwd: resolve(process.cwd()),
    tools: ["read", "grep", "ls"],
    timeoutMs: 180_000,
    interviewMode: false,
  });

  if (!result.ok || !result.output.trim()) {
    const detail = result.error || result.stderr || `exit ${result.exitCode}`;
    throw new Error(`${result.provider}/${result.model} failed: ${detail}`);
  }

  return normalizeLangOutput(result.output);
}

async function callLLM(slug: string, meta: SkillMeta, skillBody: string, systemPrompt = LANG_SYSTEM_PROMPT): Promise<string> {
  const userPrompt = buildUserPrompt(slug, meta, skillBody);
  return callLLMViaDispatch(slug, systemPrompt, userPrompt);
}

// --- Main Generator ---

// --- Dry-run overload (returns content without writing) ---
export async function generateDashboard(slug: string, opts?: { dryRun?: boolean }): Promise<{ content: string; written: boolean }>;
// Legacy overload: plain string return (backward-compat)
export async function generateDashboard(slug: string): Promise<string>;
export async function generateDashboard(slug: string, opts?: { dryRun?: boolean }): Promise<string | { content: string; written: boolean }> {
  const dryRun = opts?.dryRun === true;
  const _legacyStringReturn = opts === undefined;
  return _generateDashboardImpl(slug, dryRun, _legacyStringReturn);
}

async function _generateDashboardImpl(slug: string, dryRun: boolean, legacyStringReturn: boolean): Promise<string | { content: string; written: boolean }> {
  const skillDir = resolve(process.cwd(), "state/skills", slug);
  const skillMdPath = join(skillDir, "SKILL.md");

  if (!existsSync(skillMdPath)) {
    throw new Error(`Skill not found: ${slug} (expected at ${skillMdPath})`);
  }

  const skillMdContent = readFileSync(skillMdPath, "utf8");
  const meta = parseFrontmatter(skillMdContent);
  // Strip frontmatter to get just the body prose
  const skillBody = skillMdContent.replace(/^---\n[\s\S]+?\n---\n?/, "").trim();

  // Try LLM composition first
  let lang: string;
  try {
    const raw = await callLLM(slug, meta, skillBody);

    if (validateLang(raw)) {
      lang = raw;
    } else {
      // Retry with a stricter system prompt
      const stricterSystem = LANG_SYSTEM_PROMPT + "\n\nCRITICAL: Output ONLY OpenUI Lang. The first character must be a letter. No backticks, no prose.";
      try {
        const retryRaw = await callLLM(slug, meta, skillBody, stricterSystem);
        if (validateLang(retryRaw)) {
          lang = retryRaw;
        } else {
          process.stderr.write(`[dashboard-builder] dispatch output failed validation for ${slug}, using template fallback\n`);
          lang = generateFromTemplate(slug, meta);
        }
      } catch {
        process.stderr.write(`[dashboard-builder] dispatch retry failed for ${slug}, using template fallback\n`);
        lang = generateFromTemplate(slug, meta);
      }
    }
  } catch (e) {
    process.stderr.write(`[dashboard-builder] dispatch call failed for ${slug}: ${(e as Error).message}, using template fallback\n`);
    lang = generateFromTemplate(slug, meta);
  }

  if (legacyStringReturn) return lang;
  return { content: lang, written: false };
}

export async function writeDashboard(slug: string): Promise<string> {
  const skillDir = resolve(process.cwd(), "state/skills", slug);
  const resourcesDir = join(skillDir, "resources");
  const targetPath = join(resourcesDir, "ui.openui");

  // Respect DO NOT REGENERATE header
  if (existsSync(targetPath)) {
    const existing = readFileSync(targetPath, "utf8");
    const firstFive = existing.split("\n").slice(0, 5).join("\n");
    if (firstFive.includes("# DO NOT REGENERATE")) {
      process.stderr.write(`[dashboard-builder] Skipping ${slug}: DO NOT REGENERATE header present\n`);
      return targetPath;
    }
  }

  const result = await generateDashboard(slug, {});
  const lang = typeof result === "string" ? result : result.content;
  return writeOpenUiResource(slug, lang).path;
}

// Convenience: generate without writing, return content string only.
export async function generateDashboardContent(slug: string): Promise<string> {
  const result = await generateDashboard(slug, { dryRun: true });
  return (result as { content: string; written: boolean }).content;
}

function parseFrontmatter(content: string): SkillMeta {
  const match = content.match(/^---\n([\s\S]+?)\n---/);
  if (!match) return { name: "", description: "" };

  const yaml = match[1];
  const meta: SkillMeta = { name: "", description: "" };

  const nameMatch = yaml.match(/^name:\s*(.+)$/m);
  if (nameMatch) meta.name = nameMatch[1].trim();

  const descMatch = yaml.match(/^description:\s*['""]?(.+?)['""]?\s*$/m);
  if (descMatch) meta.description = descMatch[1].trim().replace(/^["']+|["']+$/g, "");

  const catMatch = yaml.match(/^category:\s*(.+)$/m);
  if (catMatch) meta.category = catMatch[1].trim();

  const typeMatch = yaml.match(/^type:\s*(.+)$/m);
  if (typeMatch) meta.type = typeMatch[1].trim();

  return meta;
}

// --- CLI ---

if ((() => {
  try {
    return import.meta.url === `file://${realpathSync(process.argv[1])}`;
  } catch {
    return false;
  }
})()) {
  (async () => {
    const slug = process.argv[2];
    if (!slug) {
      console.error("Usage: npx tsx state/lib/dashboard-builder.ts <slug>");
      process.exit(1);
    }

    try {
      const openui = await generateDashboard(slug);
      console.log(openui);
    } catch (err) {
      console.error("Error:", (err as Error).message);
      process.exit(1);
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 4 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 9 runs