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

criteria:
  - name: artifact_url_returned
    kind: deterministic
    check: "The skill returns a fetchable artifact or https URL for every generated image."
  - name: gallery_route_uses_media_index
    kind: deterministic
    check: "Inspection flows read /images/gallery or /media/recent?kind=image rather than a legacy generation ledger."
  - name: auditor_independent
    kind: judge
    check: "A verifier independent from the generator evaluates whether the generated image satisfies the prompt."

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/image.ts -- Image generation and CDN upload client.
 *
 * Same shape as xano.ts, github.ts, pipeline.ts: typed functions, one import.
 * Wraps the shell scripts in state/bin/image/ under a clean interface.
 *
 *   import { generate, upload } from "../lib/image.ts";
 *   const result = await generate({ illustration: "...", text: "Title", slug: "my-img", format: "skool-course" });
 *   console.log(result.cdnUrl);
 *
 * CLI:
 *   npx tsx state/lib/image.ts generate --illustration "..." --text "Title" --slug test --format linkedin-post
 *   npx tsx state/lib/image.ts upload --file /tmp/img.png --context course-imagery --slug my-slug
 */

import { execSync } from "child_process";
import { readFileSync, existsSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";

const BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "image");

// ── Types ──

export type ImageFormat =
  | "linkedin-post"
  | "linkedin-carousel"
  | "skool-course"
  | "blog-hero"
  | "video-slide"
  | "thumbnail"
  | "instagram-feed"
  | "instagram-story";

export interface GenerateOptions {
  /** Visual concept for the illustration area (use this OR topic+council) */
  illustration?: string;
  /** Topic for art council to debate (use with council) */
  topic?: string;
  /** Title text rendered in the lower third */
  text: string;
  /** Short slug for filenames and CDN path */
  slug: string;
  /** Target platform format (default: linkedin-post) */
  format?: ImageFormat;
  /** Output directory (default: /tmp/snappy-image) */
  outDir?: string;
  /** Max self-inspection edit rounds (default: 1) */
  maxAutoTurns?: number;
  /** Optional reference image path for style transfer */
  ref?: string;
  /** Art council panel to use (e.g. "art", "textbook", "whimsy") */
  council?: string;
  /** Fan out all council proposals in parallel (default: false) */
  matrix?: boolean;
}

export interface GenerateResult {
  /** Local path to final image */
  path: string;
  /** CDN URL of final image */
  cdnUrl: string;
  /** Inspector verdict: "pass" or "fix" */
  verdict: string;
  /** Eval score: 1.0 if pass, 0.5 if fix-applied, 0.0 if error */
  score: number;
  /** Number of versions generated (1 = no edits needed) */
  versions: number;
  /** All CDN URLs for each version */
  allUrls: string[];
  /** Matrix results (only when council + matrix mode) */
  matrix?: { expert: string; url: string }[];
}

export interface UploadOptions {
  /** Local file path */
  file: string;
  /** CDN context/folder (default: images/generated) */
  context?: string;
  /** Slug for the CDN key */
  slug?: string;
}

// ── Functions ──

/**
 * Generate an image with self-inspecting loop.
 * Calls generate-iterate.sh under the hood.
 */
export async function generate(opts: GenerateOptions): Promise<GenerateResult> {
  if (!opts.illustration && !opts.topic) {
    throw new Error("generate requires either illustration or topic");
  }

  const outDir = opts.outDir ?? "/tmp/snappy-image";
  const format = opts.format ?? "linkedin-post";
  const maxTurns = opts.maxAutoTurns ?? 1;

  const args: string[] = [];

  // Council mode: pass topic + council panel, let experts debate the concept
  if (opts.topic && opts.council) {
    args.push(`--topic ${q(opts.topic)}`);
    args.push(`--council ${q(opts.council)}`);
    if (opts.matrix) args.push("--matrix");
  } else if (opts.illustration) {
    args.push(`--illustration ${q(opts.illustration)}`);
  }

  args.push(
    `--text ${q(opts.text)}`,
    `--slug ${q(opts.slug)}`,
    `--out-dir ${q(outDir)}`,
    `--format ${format}`,
    `--max-auto-turns ${maxTurns}`,
  );
  if (opts.ref) args.push(`--ref ${q(opts.ref)}`);

  const stdout = run(`bash ${BIN}/generate-iterate.sh ${args.join(" ")}`, 600_000);

  // Parse CDN URLs from stdout (lines like "v1: https://...")
  const urls = [...stdout.matchAll(/v\d+:\s+(https:\/\/\S+)/g)].map((m) => m[1]);

  // Parse matrix results if present (lines like "  Steinberg: https://...")
  const matrixMatches = [...stdout.matchAll(/^\s+(\w+):\s+(https:\/\/\S+)/gm)];
  const matrix =
    matrixMatches.length > 0 ? matrixMatches.map((m) => ({ expert: m[1], url: m[2] })) : undefined;

  // Read state.json for structured result
  const stateFile = `${outDir}/${opts.slug}/state.json`;
  let verdict = "unknown";
  let versions = urls.length;
  let finalPath = `${outDir}/${opts.slug}/v${versions}.png`;

  if (existsSync(stateFile)) {
    const state = JSON.parse(readFileSync(stateFile, "utf-8"));
    const frames = state.frames ?? [];
    const last = frames[frames.length - 1];
    if (last) {
      verdict = last.verdict ?? "unknown";
    }
    versions = frames.length;
    finalPath = `${outDir}/${opts.slug}/v${versions}.png`;
  }

  const score = verdict === "pass" ? 1.0 : versions > 1 ? 0.5 : 0.0;

  return {
    path: finalPath,
    cdnUrl: urls[urls.length - 1] ?? "",
    verdict,
    score,
    versions,
    allUrls: urls,
    matrix,
  };
}

/**
 * Upload a local file to the DO Spaces CDN.
 * Returns the public HTTPS URL.
 */
export async function upload(opts: UploadOptions): Promise<string> {
  const args = [`--file ${q(opts.file)}`];
  if (opts.context) args.push(`--context ${q(opts.context)}`);
  if (opts.slug) args.push(`--slug ${q(opts.slug)}`);

  const stdout = run(`bash ${BIN}/cdn-upload.sh ${args.join(" ")}`);

  // Last line of stdout is the https URL
  const lines = stdout.trim().split("\n");
  const url = lines.find((l) => l.startsWith("https://")) ?? lines[lines.length - 1];
  return url.trim();
}

// ── Helpers ──

function q(s: string): string {
  return `"${s.replace(/"/g, '\\"')}"`;
}

function run(cmd: string, timeout = 300_000): string {
  return execSync(cmd, {
    encoding: "utf-8",
    timeout,
    stdio: ["pipe", "pipe", "pipe"],
  });
}

// ── CLI ──

if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("image.ts")) {
  const [, , command, ...rest] = process.argv;

  function cliArg(name: string): string | undefined {
    const idx = rest.indexOf(`--${name}`);
    return idx >= 0 ? rest[idx + 1] : undefined;
  }

  (async () => {
    switch (command) {
      case "generate": {
        const illustration = cliArg("illustration");
        const topic = cliArg("topic");
        const text = cliArg("text");
        const slug = cliArg("slug");
        if ((!illustration && !topic) || !text || !slug) {
          console.error(
            "usage: image.ts generate --topic '...' --council art --text '...' --slug <slug> [--format <fmt>] [--matrix]",
          );
          console.error(
            "   or: image.ts generate --illustration '...' --text '...' --slug <slug> [--format <fmt>]",
          );
          process.exit(2);
        }
        const result = await generate({
          illustration: illustration || undefined,
          topic: topic || undefined,
          council: cliArg("council") || undefined,
          matrix: rest.includes("--matrix"),
          text,
          slug,
          format: (cliArg("format") as ImageFormat) ?? "linkedin-post",
          outDir: cliArg("out-dir"),
          maxAutoTurns: cliArg("max-auto-turns") ? Number(cliArg("max-auto-turns")) : undefined,
          ref: cliArg("ref"),
        });
        console.log(JSON.stringify(result, null, 2));
        break;
      }
      case "upload": {
        const file = cliArg("file");
        if (!file) {
          console.error("usage: image.ts upload --file <path> [--context <ctx>] [--slug <slug>]");
          process.exit(2);
        }
        const url = await upload({ file, context: cliArg("context"), slug: cliArg("slug") });
        console.log(url);
        break;
      }
      default:
        console.log("usage: image.ts <generate|upload> [options]");
        console.log("");
        console.log("  generate  --illustration '...' --text '...' --slug <slug> [--format <fmt>]");
        console.log("  upload    --file <path> [--context <ctx>] [--slug <slug>]");
    }
  })();
}

scripts- helper scripts it can run

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

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

no recent runs logged - the eval contract is declared but nothing has been graded yet