feat: design binary core — generate, check, compare commands

Stateless CLI (design/dist/design) wrapping OpenAI Responses API for
UI mockup generation. Three working commands:

- generate: brief -> PNG mockup via gpt-4o + image_generation tool
- check: vision-based quality gate via GPT-4o (text readability, layout
  completeness, visual coherence)
- compare: generates self-contained HTML comparison board with star
  ratings, radio Pick, per-variant feedback, regenerate controls,
  and Submit button that writes structured JSON for agent polling

Auth reads from ~/.gstack/openai.json (0600), falls back to
OPENAI_API_KEY env var. Compiled separately from browse binary
(openai added to devDependencies, not runtime deps).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitignore

@@ -1,6 +1,7 @@
 .env
 node_modules/
 browse/dist/
+design/dist/
 bin/gstack-global-discover
 .gstack/
 .claude/skills/

design/src/auth.ts

@@ -0,0 +1,63 @@
+/**
+ * Auth resolution for OpenAI API access.
+ *
+ * Resolution order:
+ * 1. ~/.gstack/openai.json → { "api_key": "sk-..." }
+ * 2. OPENAI_API_KEY environment variable
+ * 3. null (caller handles guided setup or fallback)
+ */
+
+import fs from "fs";
+import path from "path";
+
+const CONFIG_PATH = path.join(process.env.HOME || "~", ".gstack", "openai.json");
+
+export function resolveApiKey(): string | null {
+  // 1. Check ~/.gstack/openai.json
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const content = fs.readFileSync(CONFIG_PATH, "utf-8");
+      const config = JSON.parse(content);
+      if (config.api_key && typeof config.api_key === "string") {
+        return config.api_key;
+      }
+    }
+  } catch {
+    // Fall through to env var
+  }
+
+  // 2. Check environment variable
+  if (process.env.OPENAI_API_KEY) {
+    return process.env.OPENAI_API_KEY;
+  }
+
+  return null;
+}
+
+/**
+ * Save an API key to ~/.gstack/openai.json with 0600 permissions.
+ */
+export function saveApiKey(key: string): void {
+  const dir = path.dirname(CONFIG_PATH);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify({ api_key: key }, null, 2));
+  fs.chmodSync(CONFIG_PATH, 0o600);
+}
+
+/**
+ * Get API key or exit with setup instructions.
+ */
+export function requireApiKey(): string {
+  const key = resolveApiKey();
+  if (!key) {
+    console.error("No OpenAI API key found.");
+    console.error("");
+    console.error("Run: $D setup");
+    console.error("  or save to ~/.gstack/openai.json: { \"api_key\": \"sk-...\" }");
+    console.error("  or set OPENAI_API_KEY environment variable");
+    console.error("");
+    console.error("Get a key at: https://platform.openai.com/api-keys");
+    process.exit(1);
+  }
+  return key;
+}

design/src/brief.ts

@@ -0,0 +1,59 @@
+/**
+ * Structured design brief — the interface between skill prose and image generation.
+ */
+
+export interface DesignBrief {
+  goal: string;           // "Dashboard for coding assessment tool"
+  audience: string;       // "Technical users, YC partners"
+  style: string;          // "Dark theme, cream accents, minimal"
+  elements: string[];     // ["builder name", "score badge", "narrative letter"]
+  constraints?: string;   // "Max width 1024px, mobile-first"
+  reference?: string;     // DESIGN.md excerpt or style reference text
+  screenType: string;     // "desktop-dashboard" | "mobile-app" | "landing-page" | etc.
+}
+
+/**
+ * Convert a structured brief to a prompt string for image generation.
+ */
+export function briefToPrompt(brief: DesignBrief): string {
+  const lines: string[] = [
+    `Generate a pixel-perfect UI mockup of a ${brief.screenType} for: ${brief.goal}.`,
+    `Target audience: ${brief.audience}.`,
+    `Visual style: ${brief.style}.`,
+    `Required elements: ${brief.elements.join(", ")}.`,
+  ];
+
+  if (brief.constraints) {
+    lines.push(`Constraints: ${brief.constraints}.`);
+  }
+
+  if (brief.reference) {
+    lines.push(`Design reference: ${brief.reference}`);
+  }
+
+  lines.push(
+    "The mockup should look like a real production UI, not a wireframe or concept art.",
+    "All text must be readable. Layout must be clean and intentional.",
+    "1536x1024 pixels."
+  );
+
+  return lines.join(" ");
+}
+
+/**
+ * Parse a brief from either a plain text string or a JSON file path.
+ */
+export function parseBrief(input: string, isFile: boolean): string {
+  if (!isFile) {
+    // Plain text prompt — use directly
+    return input;
+  }
+
+  // JSON file — parse and convert to prompt
+  const raw = Bun.file(input);
+  // We'll read it synchronously via fs since Bun.file is async
+  const fs = require("fs");
+  const content = fs.readFileSync(input, "utf-8");
+  const brief: DesignBrief = JSON.parse(content);
+  return briefToPrompt(brief);
+}

design/src/check.ts

@@ -0,0 +1,92 @@
+/**
+ * Vision-based quality gate for generated mockups.
+ * Uses GPT-4o vision to verify text readability, layout completeness, and visual coherence.
+ */
+
+import fs from "fs";
+import { requireApiKey } from "./auth";
+
+export interface CheckResult {
+  pass: boolean;
+  issues: string;
+}
+
+/**
+ * Check a generated mockup against the original brief.
+ */
+export async function checkMockup(imagePath: string, brief: string): Promise<CheckResult> {
+  const apiKey = requireApiKey();
+  const imageData = fs.readFileSync(imagePath).toString("base64");
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 60_000);
+
+  try {
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o",
+        messages: [{
+          role: "user",
+          content: [
+            {
+              type: "image_url",
+              image_url: { url: `data:image/png;base64,${imageData}` },
+            },
+            {
+              type: "text",
+              text: [
+                "You are a UI quality checker. Evaluate this mockup against the design brief.",
+                "",
+                `Brief: ${brief}`,
+                "",
+                "Check these 3 things:",
+                "1. TEXT READABILITY: Are all labels, headings, and body text legible? Any misspellings?",
+                "2. LAYOUT COMPLETENESS: Are all requested elements present? Anything missing?",
+                "3. VISUAL COHERENCE: Does it look like a real production UI, not AI art or a collage?",
+                "",
+                "Respond with exactly one line:",
+                "PASS — if all 3 checks pass",
+                "FAIL: [list specific issues] — if any check fails",
+              ].join("\n"),
+            },
+          ],
+        }],
+        max_tokens: 200,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      // Non-blocking: if vision check fails, default to PASS with warning
+      console.error(`Vision check API error (${response.status}): ${error}`);
+      return { pass: true, issues: "Vision check unavailable — skipped" };
+    }
+
+    const data = await response.json() as any;
+    const content = data.choices?.[0]?.message?.content?.trim() || "";
+
+    if (content.startsWith("PASS")) {
+      return { pass: true, issues: "" };
+    }
+
+    // Extract issues after "FAIL:"
+    const issues = content.replace(/^FAIL:\s*/i, "").trim();
+    return { pass: false, issues: issues || content };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Standalone check command: check an existing image against a brief.
+ */
+export async function checkCommand(imagePath: string, brief: string): Promise<void> {
+  const result = await checkMockup(imagePath, brief);
+  console.log(JSON.stringify(result, null, 2));
+}

design/src/cli.ts

@@ -0,0 +1,181 @@
+/**
+ * gstack design CLI — stateless CLI for AI-powered design generation.
+ *
+ * Unlike the browse binary (persistent Chromium daemon), the design binary
+ * is stateless: each invocation makes API calls and writes files. Session
+ * state for multi-turn iteration is a JSON file in /tmp.
+ *
+ * Flow:
+ *   1. Parse command + flags from argv
+ *   2. Resolve auth (~/. gstack/openai.json → OPENAI_API_KEY → guided setup)
+ *   3. Execute command (API call → write PNG/HTML)
+ *   4. Print result JSON to stdout
+ */
+
+import { COMMANDS } from "./commands";
+import { generate } from "./generate";
+import { checkCommand } from "./check";
+import { compare } from "./compare";
+import { resolveApiKey, saveApiKey } from "./auth";
+
+function parseArgs(argv: string[]): { command: string; flags: Record<string, string | boolean> } {
+  const args = argv.slice(2); // skip bun/node and script path
+  if (args.length === 0) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const command = args[0];
+  const flags: Record<string, string | boolean> = {};
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    }
+  }
+
+  return { command, flags };
+}
+
+function printUsage(): void {
+  console.log("gstack design — AI-powered UI mockup generation\n");
+  console.log("Commands:");
+  for (const [name, info] of COMMANDS) {
+    console.log(`  ${name.padEnd(12)} ${info.description}`);
+    console.log(`  ${"".padEnd(12)} ${info.usage}`);
+  }
+  console.log("\nAuth: ~/.gstack/openai.json or OPENAI_API_KEY env var");
+  console.log("Setup: $D setup");
+}
+
+async function runSetup(): Promise<void> {
+  const existing = resolveApiKey();
+  if (existing) {
+    console.log("Existing API key found. Running smoke test...");
+  } else {
+    console.log("No API key found. Please enter your OpenAI API key.");
+    console.log("Get one at: https://platform.openai.com/api-keys");
+    console.log("(Needs image generation permissions)\n");
+
+    // Read from stdin
+    process.stdout.write("API key: ");
+    const reader = Bun.stdin.stream().getReader();
+    const { value } = await reader.read();
+    reader.releaseLock();
+    const key = new TextDecoder().decode(value).trim();
+
+    if (!key || !key.startsWith("sk-")) {
+      console.error("Invalid key. Must start with 'sk-'.");
+      process.exit(1);
+    }
+
+    saveApiKey(key);
+    console.log("Key saved to ~/.gstack/openai.json (0600 permissions).");
+  }
+
+  // Smoke test
+  console.log("\nRunning smoke test (generating a simple image)...");
+  try {
+    await generate({
+      brief: "A simple blue square centered on a white background. Minimal, geometric, clean.",
+      output: "/tmp/gstack-design-smoke-test.png",
+      size: "1024x1024",
+      quality: "low",
+    });
+    console.log("\nSmoke test PASSED. Design generation is working.");
+  } catch (err: any) {
+    console.error(`\nSmoke test FAILED: ${err.message}`);
+    console.error("Check your API key and organization verification status.");
+    process.exit(1);
+  }
+}
+
+async function main(): Promise<void> {
+  const { command, flags } = parseArgs(process.argv);
+
+  if (!COMMANDS.has(command)) {
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  switch (command) {
+    case "generate":
+      await generate({
+        brief: flags.brief as string,
+        briefFile: flags["brief-file"] as string,
+        output: (flags.output as string) || "/tmp/gstack-mockup.png",
+        check: !!flags.check,
+        retry: flags.retry ? parseInt(flags.retry as string) : 0,
+        size: flags.size as string,
+        quality: flags.quality as string,
+      });
+      break;
+
+    case "check":
+      await checkCommand(flags.image as string, flags.brief as string);
+      break;
+
+    case "compare": {
+      // Parse --images as glob or multiple files
+      const imagesArg = flags.images as string;
+      const images = await resolveImagePaths(imagesArg);
+      compare({
+        images,
+        output: (flags.output as string) || "/tmp/gstack-design-board.html",
+      });
+      break;
+    }
+
+    case "setup":
+      await runSetup();
+      break;
+
+    case "variants":
+    case "iterate":
+    case "diff":
+    case "evolve":
+    case "verify":
+      console.error(`Command '${command}' will be implemented in Commit 2+.`);
+      process.exit(1);
+      break;
+  }
+}
+
+/**
+ * Resolve image paths from a glob pattern or comma-separated list.
+ */
+async function resolveImagePaths(input: string): Promise<string[]> {
+  if (!input) {
+    console.error("--images is required. Provide glob pattern or comma-separated paths.");
+    process.exit(1);
+  }
+
+  // Check if it's a glob pattern
+  if (input.includes("*")) {
+    const glob = new Bun.Glob(input);
+    const paths: string[] = [];
+    for await (const match of glob.scan({ absolute: true })) {
+      if (match.endsWith(".png") || match.endsWith(".jpg") || match.endsWith(".jpeg")) {
+        paths.push(match);
+      }
+    }
+    return paths.sort();
+  }
+
+  // Comma-separated or single path
+  return input.split(",").map(p => p.trim());
+}
+
+main().catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});

design/src/commands.ts

@@ -0,0 +1,62 @@
+/**
+ * Command registry — single source of truth for all design commands.
+ *
+ * Dependency graph:
+ *   commands.ts ──▶ cli.ts (runtime dispatch)
+ *              ──▶ gen-skill-docs.ts (doc generation)
+ *              ──▶ tests (validation)
+ *
+ * Zero side effects. Safe to import from build scripts and tests.
+ */
+
+export const COMMANDS = new Map<string, {
+  description: string;
+  usage: string;
+  flags?: string[];
+}>([
+  ["generate", {
+    description: "Generate a UI mockup from a design brief",
+    usage: "generate --brief \"...\" --output /path.png",
+    flags: ["--brief", "--brief-file", "--output", "--check", "--retry", "--size", "--quality"],
+  }],
+  ["variants", {
+    description: "Generate N design variants from a brief",
+    usage: "variants --brief \"...\" --count 3 --output-dir /path/",
+    flags: ["--brief", "--brief-file", "--count", "--output-dir", "--size", "--quality", "--viewports"],
+  }],
+  ["iterate", {
+    description: "Iterate on an existing mockup with feedback",
+    usage: "iterate --session /path/session.json --feedback \"...\" --output /path.png",
+    flags: ["--session", "--feedback", "--output"],
+  }],
+  ["check", {
+    description: "Vision-based quality check on a mockup",
+    usage: "check --image /path.png --brief \"...\"",
+    flags: ["--image", "--brief"],
+  }],
+  ["compare", {
+    description: "Generate HTML comparison board for user review",
+    usage: "compare --images /path/*.png --output /path/board.html",
+    flags: ["--images", "--output"],
+  }],
+  ["diff", {
+    description: "Visual diff between two mockups",
+    usage: "diff --before old.png --after new.png",
+    flags: ["--before", "--after", "--output"],
+  }],
+  ["evolve", {
+    description: "Generate improved mockup from existing screenshot",
+    usage: "evolve --screenshot current.png --brief \"make it calmer\" --output /path.png",
+    flags: ["--screenshot", "--brief", "--output"],
+  }],
+  ["verify", {
+    description: "Compare live site screenshot against approved mockup",
+    usage: "verify --mockup approved.png --screenshot live.png",
+    flags: ["--mockup", "--screenshot", "--output"],
+  }],
+  ["setup", {
+    description: "Guided API key setup + smoke test",
+    usage: "setup",
+    flags: [],
+  }],
+]);

design/src/compare.ts

@@ -0,0 +1,404 @@
+/**
+ * Generate HTML comparison board for user review of design variants.
+ * Opens in headed Chrome via $B goto. User picks favorite, rates, comments, submits.
+ * Agent reads feedback from hidden DOM element.
+ *
+ * Design spec: single column, full-width mockups, APP UI aesthetic.
+ */
+
+import fs from "fs";
+import path from "path";
+
+export interface CompareOptions {
+  images: string[];
+  output: string;
+}
+
+/**
+ * Generate the comparison board HTML page.
+ */
+export function generateCompareHtml(images: string[]): string {
+  const variantLabels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+  const variantCards = images.map((imgPath, i) => {
+    const label = variantLabels[i] || `${i + 1}`;
+    // Embed images as base64 data URIs for self-contained HTML
+    const imgData = fs.readFileSync(imgPath).toString("base64");
+    const ext = path.extname(imgPath).slice(1) || "png";
+
+    return `
+    <div class="variant" data-variant="${label}">
+      <img src="data:image/${ext};base64,${imgData}" alt="Variant ${label}" />
+      <div class="variant-controls">
+        <label class="pick-label">
+          <input type="radio" name="preferred" value="${label}" />
+          <span class="pick-text">Pick</span>
+        </label>
+        <div class="stars" data-variant="${label}">
+          ${[1,2,3,4,5].map(n => `<span class="star" data-value="${n}">★</span>`).join("")}
+        </div>
+        <input type="text" class="feedback-input" data-variant="${label}"
+               placeholder="What do you like/dislike?" />
+        <button class="more-like-this" data-variant="${label}">More like this</button>
+      </div>
+    </div>`;
+  }).join("\n");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Design Exploration</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    background: #fff;
+    color: #333;
+  }
+
+  .header {
+    padding: 16px 24px;
+    border-bottom: 1px solid #e5e5e5;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+  .header h1 { font-size: 16px; font-weight: 600; }
+  .header .meta { font-size: 13px; color: #999; }
+
+  .variants { max-width: 1200px; margin: 0 auto; padding: 0 24px; }
+
+  .variant {
+    border-bottom: 1px solid #e5e5e5;
+    padding: 24px 0;
+  }
+  .variant:last-child { border-bottom: none; }
+
+  .variant img {
+    width: 100%;
+    height: auto;
+    display: block;
+    border-radius: 4px;
+  }
+
+  .variant-controls {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    padding: 12px 0 0;
+    flex-wrap: wrap;
+  }
+
+  .pick-label {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    cursor: pointer;
+    font-size: 14px;
+    font-weight: 600;
+  }
+  .pick-label input[type="radio"] { accent-color: #000; }
+
+  .stars { display: flex; gap: 2px; }
+  .star {
+    font-size: 20px;
+    color: #ddd;
+    cursor: pointer;
+    user-select: none;
+    transition: color 0.1s;
+  }
+  .star.filled { color: #000; }
+  .star:hover { color: #666; }
+
+  .feedback-input {
+    flex: 1;
+    min-width: 200px;
+    padding: 6px 10px;
+    border: 1px solid #e5e5e5;
+    border-radius: 4px;
+    font-size: 13px;
+    outline: none;
+  }
+  .feedback-input:focus { border-color: #999; }
+  .feedback-input::placeholder { color: #999; }
+
+  .more-like-this {
+    padding: 6px 12px;
+    background: none;
+    border: 1px solid #e5e5e5;
+    border-radius: 4px;
+    font-size: 13px;
+    cursor: pointer;
+    color: #666;
+  }
+  .more-like-this:hover { border-color: #999; color: #333; }
+
+  .overall-section {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 16px 24px;
+    border-top: 1px solid #e5e5e5;
+  }
+  .overall-section summary {
+    font-size: 14px;
+    color: #666;
+    cursor: pointer;
+    padding: 8px 0;
+  }
+  .overall-textarea {
+    width: 100%;
+    padding: 8px 10px;
+    border: 1px solid #e5e5e5;
+    border-radius: 4px;
+    font-size: 13px;
+    resize: vertical;
+    min-height: 60px;
+    margin-top: 8px;
+    outline: none;
+    font-family: inherit;
+  }
+  .overall-textarea:focus { border-color: #999; }
+
+  .regenerate-bar {
+    background: #f7f7f7;
+    padding: 16px 24px;
+    margin-top: 8px;
+  }
+  .regenerate-bar .inner {
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+  .regenerate-bar h3 { font-size: 14px; font-weight: 600; margin-bottom: 10px; }
+  .regen-controls {
+    display: flex;
+    gap: 8px;
+    flex-wrap: wrap;
+    align-items: center;
+  }
+  .regen-chiclet {
+    padding: 6px 14px;
+    background: #fff;
+    border: 1px solid #e5e5e5;
+    border-radius: 16px;
+    font-size: 13px;
+    cursor: pointer;
+  }
+  .regen-chiclet:hover { border-color: #999; }
+  .regen-chiclet.active { border-color: #000; background: #f0f0f0; }
+  .regen-custom {
+    flex: 1;
+    min-width: 150px;
+    padding: 6px 10px;
+    border: 1px solid #e5e5e5;
+    border-radius: 4px;
+    font-size: 13px;
+    outline: none;
+  }
+  .regen-custom:focus { border-color: #999; }
+  .regen-btn {
+    padding: 6px 16px;
+    background: #fff;
+    border: 1px solid #e5e5e5;
+    border-radius: 4px;
+    font-size: 13px;
+    cursor: pointer;
+    font-weight: 600;
+  }
+  .regen-btn:hover { border-color: #000; }
+
+  .submit-bar {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 16px 24px;
+    display: flex;
+    justify-content: flex-end;
+  }
+  .submit-btn {
+    padding: 10px 24px;
+    background: #000;
+    color: #fff;
+    border: none;
+    border-radius: 4px;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .submit-btn:hover { background: #333; }
+  .submit-btn:disabled { background: #ccc; cursor: not-allowed; }
+
+  .success-msg {
+    display: none;
+    max-width: 1200px;
+    margin: 24px auto;
+    padding: 16px 24px;
+    background: #f0f9f0;
+    border: 1px solid #c3e6c3;
+    border-radius: 4px;
+    font-size: 14px;
+    text-align: center;
+  }
+
+  /* Hidden result elements for agent polling */
+  #status, #feedback-result { display: none; }
+
+  /* Skeleton loading state */
+  .skeleton {
+    background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+    background-size: 200% 100%;
+    animation: shimmer 1.5s infinite;
+    border-radius: 4px;
+    height: 400px;
+  }
+  @keyframes shimmer {
+    0% { background-position: 200% 0; }
+    100% { background-position: -200% 0; }
+  }
+</style>
+</head>
+<body>
+
+<div class="header">
+  <h1>Design Exploration</h1>
+  <span class="meta">${images.length} variants</span>
+</div>
+
+<div class="variants">
+  ${variantCards}
+</div>
+
+<div class="overall-section">
+  <details>
+    <summary>Overall direction (optional)</summary>
+    <textarea class="overall-textarea" id="overall-feedback"
+              placeholder="Any overall notes about direction?"></textarea>
+  </details>
+</div>
+
+<div class="regenerate-bar">
+  <div class="inner">
+    <h3>Want to explore more?</h3>
+    <div class="regen-controls">
+      <button class="regen-chiclet" data-action="different">Totally different</button>
+      <button class="regen-chiclet" data-action="match">Match my design</button>
+      <input type="text" class="regen-custom" id="regen-custom-input"
+             placeholder="Tell us what you want different..." />
+      <button class="regen-btn" id="regen-btn">Regenerate →</button>
+    </div>
+  </div>
+</div>
+
+<div class="submit-bar">
+  <button class="submit-btn" id="submit-btn">✓ Submit</button>
+</div>
+
+<div class="success-msg" id="success-msg">
+  Feedback submitted! Return to your coding agent.
+</div>
+
+<!-- Hidden elements for agent polling -->
+<div id="status"></div>
+<div id="feedback-result"></div>
+
+<script>
+  // Star rating
+  document.querySelectorAll('.stars').forEach(starsEl => {
+    const stars = starsEl.querySelectorAll('.star');
+    let rating = 0;
+
+    stars.forEach(star => {
+      star.addEventListener('click', () => {
+        rating = parseInt(star.dataset.value);
+        stars.forEach(s => {
+          s.classList.toggle('filled', parseInt(s.dataset.value) <= rating);
+        });
+      });
+    });
+  });
+
+  // Regenerate chiclets (toggle active)
+  document.querySelectorAll('.regen-chiclet').forEach(chiclet => {
+    chiclet.addEventListener('click', () => {
+      document.querySelectorAll('.regen-chiclet').forEach(c => c.classList.remove('active'));
+      chiclet.classList.add('active');
+    });
+  });
+
+  // More like this buttons
+  document.querySelectorAll('.more-like-this').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const variant = btn.dataset.variant;
+      // Set regeneration context
+      document.querySelectorAll('.regen-chiclet').forEach(c => c.classList.remove('active'));
+      document.getElementById('regen-custom-input').value = 'More like variant ' + variant;
+      // Trigger regenerate
+      submitRegenerate('more_like_' + variant);
+    });
+  });
+
+  // Regenerate button
+  document.getElementById('regen-btn').addEventListener('click', () => {
+    const activeChiclet = document.querySelector('.regen-chiclet.active');
+    const customInput = document.getElementById('regen-custom-input').value;
+    const action = activeChiclet ? activeChiclet.dataset.action : 'custom';
+    const detail = customInput || action;
+    submitRegenerate(detail);
+  });
+
+  function submitRegenerate(detail) {
+    const feedback = collectFeedback();
+    feedback.regenerated = true;
+    feedback.regenerateAction = detail;
+    document.getElementById('feedback-result').textContent = JSON.stringify(feedback);
+    document.getElementById('status').textContent = 'regenerate';
+  }
+
+  // Submit button
+  document.getElementById('submit-btn').addEventListener('click', () => {
+    const feedback = collectFeedback();
+    feedback.regenerated = false;
+    document.getElementById('feedback-result').textContent = JSON.stringify(feedback);
+    document.getElementById('status').textContent = 'submitted';
+    document.getElementById('submit-btn').disabled = true;
+    document.getElementById('success-msg').style.display = 'block';
+  });
+
+  function collectFeedback() {
+    const preferred = document.querySelector('input[name="preferred"]:checked');
+    const ratings = {};
+    const comments = {};
+
+    document.querySelectorAll('.variant').forEach(v => {
+      const variant = v.dataset.variant;
+      const stars = v.querySelectorAll('.star.filled');
+      ratings[variant] = stars.length;
+      const input = v.querySelector('.feedback-input');
+      if (input && input.value) {
+        comments[variant] = input.value;
+      }
+    });
+
+    return {
+      preferred: preferred ? preferred.value : null,
+      ratings,
+      comments,
+      overall: document.getElementById('overall-feedback').value || null,
+    };
+  }
+</script>
+
+</body>
+</html>`;
+}
+
+/**
+ * Compare command: generate comparison board HTML from image files.
+ */
+export function compare(options: CompareOptions): void {
+  const html = generateCompareHtml(options.images);
+  const outputDir = path.dirname(options.output);
+  fs.mkdirSync(outputDir, { recursive: true });
+  fs.writeFileSync(options.output, html);
+  console.log(JSON.stringify({ outputPath: options.output, variants: options.images.length }));
+}

design/src/generate.ts

@@ -0,0 +1,153 @@
+/**
+ * Generate UI mockups via OpenAI Responses API with image_generation tool.
+ */
+
+import fs from "fs";
+import path from "path";
+import { requireApiKey } from "./auth";
+import { parseBrief } from "./brief";
+import { createSession, sessionPath } from "./session";
+import { checkMockup } from "./check";
+
+export interface GenerateOptions {
+  brief?: string;
+  briefFile?: string;
+  output: string;
+  check?: boolean;
+  retry?: number;
+  size?: string;
+  quality?: string;
+}
+
+export interface GenerateResult {
+  outputPath: string;
+  sessionFile: string;
+  responseId: string;
+  checkResult?: { pass: boolean; issues: string };
+}
+
+/**
+ * Call OpenAI Responses API with image_generation tool.
+ * Returns the response ID and base64 image data.
+ */
+async function callImageGeneration(
+  apiKey: string,
+  prompt: string,
+  size: string,
+  quality: string,
+): Promise<{ responseId: string; imageData: string }> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 120_000);
+
+  try {
+    const response = await fetch("https://api.openai.com/v1/responses", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o",
+        input: prompt,
+        tools: [{
+          type: "image_generation",
+          size,
+          quality,
+        }],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`API error (${response.status}): ${error}`);
+    }
+
+    const data = await response.json() as any;
+
+    const imageItem = data.output?.find((item: any) =>
+      item.type === "image_generation_call"
+    );
+
+    if (!imageItem?.result) {
+      throw new Error(
+        `No image data in response. Output types: ${data.output?.map((o: any) => o.type).join(", ") || "none"}`
+      );
+    }
+
+    return {
+      responseId: data.id,
+      imageData: imageItem.result,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Generate a single mockup from a brief.
+ */
+export async function generate(options: GenerateOptions): Promise<GenerateResult> {
+  const apiKey = requireApiKey();
+
+  // Parse the brief
+  const prompt = options.briefFile
+    ? parseBrief(options.briefFile, true)
+    : parseBrief(options.brief!, false);
+
+  const size = options.size || "1536x1024";
+  const quality = options.quality || "high";
+  const maxRetries = options.retry ?? 0;
+
+  let lastResult: GenerateResult | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      console.error(`Retry ${attempt}/${maxRetries}...`);
+    }
+
+    // Generate the image
+    const startTime = Date.now();
+    const { responseId, imageData } = await callImageGeneration(apiKey, prompt, size, quality);
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    // Write to disk
+    const outputDir = path.dirname(options.output);
+    fs.mkdirSync(outputDir, { recursive: true });
+    const imageBuffer = Buffer.from(imageData, "base64");
+    fs.writeFileSync(options.output, imageBuffer);
+
+    // Create session
+    const session = createSession(responseId, prompt, options.output);
+
+    console.error(`Generated (${elapsed}s, ${(imageBuffer.length / 1024).toFixed(0)}KB) → ${options.output}`);
+
+    lastResult = {
+      outputPath: options.output,
+      sessionFile: sessionPath(session.id),
+      responseId,
+    };
+
+    // Quality check if requested
+    if (options.check) {
+      const checkResult = await checkMockup(options.output, prompt);
+      lastResult.checkResult = checkResult;
+
+      if (checkResult.pass) {
+        console.error(`Quality check: PASS`);
+        break;
+      } else {
+        console.error(`Quality check: FAIL — ${checkResult.issues}`);
+        if (attempt < maxRetries) {
+          console.error("Will retry...");
+        }
+      }
+    } else {
+      break;
+    }
+  }
+
+  // Output result as JSON to stdout
+  console.log(JSON.stringify(lastResult, null, 2));
+  return lastResult!;
+}

design/src/session.ts

@@ -0,0 +1,79 @@
+/**
+ * Session state management for multi-turn design iteration.
+ * Session files are JSON in /tmp, keyed by PID + timestamp.
+ */
+
+import fs from "fs";
+import path from "path";
+
+export interface DesignSession {
+  id: string;
+  lastResponseId: string;
+  originalBrief: string;
+  feedbackHistory: string[];
+  outputPaths: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Generate a unique session ID from PID + timestamp.
+ */
+export function createSessionId(): string {
+  return `${process.pid}-${Date.now()}`;
+}
+
+/**
+ * Get the file path for a session.
+ */
+export function sessionPath(sessionId: string): string {
+  return path.join("/tmp", `design-session-${sessionId}.json`);
+}
+
+/**
+ * Create a new session after initial generation.
+ */
+export function createSession(
+  responseId: string,
+  brief: string,
+  outputPath: string,
+): DesignSession {
+  const id = createSessionId();
+  const session: DesignSession = {
+    id,
+    lastResponseId: responseId,
+    originalBrief: brief,
+    feedbackHistory: [],
+    outputPaths: [outputPath],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  fs.writeFileSync(sessionPath(id), JSON.stringify(session, null, 2));
+  return session;
+}
+
+/**
+ * Read an existing session from disk.
+ */
+export function readSession(sessionFilePath: string): DesignSession {
+  const content = fs.readFileSync(sessionFilePath, "utf-8");
+  return JSON.parse(content);
+}
+
+/**
+ * Update a session with new iteration data.
+ */
+export function updateSession(
+  session: DesignSession,
+  responseId: string,
+  feedback: string,
+  outputPath: string,
+): void {
+  session.lastResponseId = responseId;
+  session.feedbackHistory.push(feedback);
+  session.outputPaths.push(outputPath);
+  session.updatedAt = new Date().toISOString();
+
+  fs.writeFileSync(sessionPath(session.id), JSON.stringify(session, null, 2));
+}

package.json

@@ -8,7 +8,8 @@
     "browse": "./browse/dist/browse"
   },
   "scripts": {
-    "build": "bun run gen:skill-docs && bun run gen:skill-docs --host codex && bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && git rev-parse HEAD > browse/dist/.version && rm -f .*.bun-build || true",
+    "build": "bun run gen:skill-docs && bun run gen:skill-docs --host codex && bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile design/src/cli.ts --outfile design/dist/design && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && git rev-parse HEAD > browse/dist/.version && git rev-parse HEAD > design/dist/.version && rm -f .*.bun-build || true",
+    "dev:design": "bun run design/src/cli.ts",
     "gen:skill-docs": "bun run scripts/gen-skill-docs.ts",
     "dev": "bun run browse/src/cli.ts",
     "server": "bun run browse/src/server.ts",