@oaklandzoo/ostup 0.2.0 → 0.4.0

package/src/brief/sample-briefs.mjs

@@ -0,0 +1,304 @@
+// brief/sample-briefs.mjs: fixture briefs used by tests + dry-run flows. One per profile.
+
+import { SCHEMA_VERSION } from './schema.mjs';
+
+export const BOOKING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'lodge-booking',
+    display_name: 'Lodge Booking',
+    summary: 'A booking site for a boutique ski lodge with deposits, calendar sync, and a guest dashboard.',
+    owner_or_client: 'Hakuba Lodge LLC',
+  },
+  classification: {
+    site_profile: 'booking',
+    confidence: 0.94,
+    why: ['Booking + deposit explicit', 'Calendar/availability is a core flow', 'Guest dashboard implied'],
+    secondary_profiles: ['saas-dashboard'],
+  },
+  audience: { primary: 'small_business', buyer: 'Lodge owner', end_users: ['Travel guests', 'Lodge admins'] },
+  business_model: {
+    types: ['booking_revenue', 'deposit'],
+    pricing_notes: '$200-600/night peak; 30% deposit at booking',
+  },
+  scope: {
+    must_have_sections: ['hero', 'availability calendar', 'rooms', 'amenities', 'about', 'contact'],
+    core_flows: ['booking', 'payment', 'contact_form'],
+    non_goals: ['Channel manager integration v1', 'Multi-property support v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'Booking', fields: ['date_start', 'date_end', 'guest_name', 'status', 'deposit_status'], source: 'intake' },
+      { name: 'Room', fields: ['name', 'capacity', 'nightly_rate'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres', 'blob'],
+  },
+  brand: {
+    vibe: ['warm', 'rustic', 'premium'],
+    inspiration_urls: [],
+    color_notes: 'Espresso, sand, walnut. Earthy.',
+    font_notes: 'Serif header + clean sans body.',
+    logo_notes: 'Mountain silhouette + lodge name.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'booking',
+    addons: ['postgres', 'email', 'payments'],
+    template_paths: ['templates/base', 'templates/profiles/booking'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can request dates for a room',
+      'Admin receives booking-request email',
+      'Deposit checkout can be initiated',
+    ],
+    visual_checks: ['Hero readable on mobile', 'Calendar mobile-friendly'],
+    deploy_checks: ['Live URL returns 200', 'OG image renders'],
+  },
+};
+
+export const SAAS_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'tasktrace',
+    display_name: 'TaskTrace',
+    summary: 'A SaaS dashboard for solo founders to trace AI agent actions across their codebases.',
+    owner_or_client: 'GG Solo',
+  },
+  classification: {
+    site_profile: 'saas-dashboard',
+    confidence: 0.92,
+    why: ['Subscription billing planned', 'Auth + dashboard required', 'Multi-tenant data implied'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'founder', buyer: 'Solo dev', end_users: ['Solo developers', 'Small teams'] },
+  business_model: {
+    types: ['subscription', 'dashboard'],
+    pricing_notes: '$19/mo solo, $49/mo team',
+  },
+  scope: {
+    must_have_sections: ['landing hero', 'pricing', 'login', 'dashboard shell', 'settings', 'billing'],
+    core_flows: ['auth', 'payment', 'dashboard', 'contact_form'],
+    non_goals: ['Custom roles v1', 'SSO v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'User', fields: ['email', 'name', 'created_at', 'plan'], source: 'intake' },
+      { name: 'Trace', fields: ['user_id', 'repo', 'agent', 'action', 'timestamp'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres'],
+  },
+  brand: {
+    vibe: ['credible', 'fast', 'minimal'],
+    inspiration_urls: ['https://linear.app', 'https://vercel.com'],
+    color_notes: 'Dark mode default. Neutral grays + one accent.',
+    font_notes: 'Geist or system sans.',
+    logo_notes: 'Geometric mark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'production_2_4_weeks',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe', 'Neon'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'saas-dashboard',
+    addons: ['auth', 'payments', 'postgres'],
+    template_paths: ['templates/base', 'templates/profiles/saas-dashboard'],
+  },
+  verification: {
+    acceptance_tests: [
+      'User can sign up and log in',
+      'Stripe subscription can be initiated',
+      'Authenticated user sees the dashboard shell',
+    ],
+    visual_checks: ['Dashboard readable on mobile', 'Login page focused on the form'],
+    deploy_checks: ['Live URL returns 200 unauthenticated landing', 'Auth flow round-trips'],
+  },
+};
+
+export const BLOG_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'goodshin-notes',
+    display_name: 'Goodshin Notes',
+    summary: 'A content engine for technical essays and case studies, MDX-based, SEO-first, with RSS and sitemap.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'blog',
+    confidence: 0.93,
+    why: ['Content engine explicit', 'MDX requested', 'SEO + RSS are core flows'],
+    secondary_profiles: ['portfolio'],
+  },
+  audience: { primary: 'creator', buyer: 'GG', end_users: ['Engineers', 'Indie hackers', 'Designers'] },
+  business_model: {
+    types: ['content_traffic', 'brand_awareness'],
+    pricing_notes: 'No revenue v1; lead-gen for consulting',
+  },
+  scope: {
+    must_have_sections: ['homepage with latest 6', 'individual post page', 'tag index', 'about', 'rss', 'sitemap'],
+    core_flows: ['content_crud', 'newsletter'],
+    non_goals: ['Member-gated posts v1', 'Comments v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Post', fields: ['title', 'slug', 'date', 'tags', 'body_mdx'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['quiet', 'opinionated', 'craft'],
+    inspiration_urls: ['https://overreacted.io', 'https://jvns.ca'],
+    color_notes: 'Off-white background, dark text, restrained accent.',
+    font_notes: 'Serif headers, mono code, sans body.',
+    logo_notes: 'Wordmark only.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: [],
+    must_avoid: ['JS-heavy content tools', 'analytics that track readers'],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'blog',
+    addons: ['mdx'],
+    template_paths: ['templates/base', 'templates/profiles/blog'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can read a post',
+      'RSS feed validates',
+      'Sitemap includes every post',
+    ],
+    visual_checks: ['Post body has comfortable line length', 'Code blocks readable on mobile'],
+    deploy_checks: ['Live URL returns 200', '/rss.xml returns valid XML'],
+  },
+};
+
+export const LEAD_GEN_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'palm-roofing',
+    display_name: 'Palm Roofing Co.',
+    summary: 'A lead-gen site for a roofing company that captures contact requests and routes them to the owner by email.',
+    owner_or_client: 'Palm Roofing Co.',
+  },
+  classification: {
+    site_profile: 'lead-gen',
+    confidence: 0.95,
+    why: ['Service company explicit', 'Contact-request flow is the primary action', 'No ecommerce signals'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'small_business', buyer: 'Roofing co. owner', end_users: ['Homeowners with roof issues'] },
+  business_model: {
+    types: ['lead_capture', 'brand_awareness'],
+    pricing_notes: 'Free quotes; revenue is offline at job acceptance',
+  },
+  scope: {
+    must_have_sections: ['hero', 'services', 'service area', 'testimonials', 'faq', 'contact form'],
+    core_flows: ['contact_form'],
+    non_goals: ['Online payments v1', 'Customer portal v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Lead', fields: ['name', 'email', 'phone', 'address', 'message', 'created_at'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['trustworthy', 'local', 'no-nonsense'],
+    inspiration_urls: [],
+    color_notes: 'Navy and white. Accent orange for CTAs.',
+    font_notes: 'Bold sans for headlines.',
+    logo_notes: 'Wordmark with palm icon.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: ['Resend'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'lead-gen',
+    addons: ['email'],
+    template_paths: ['templates/base', 'templates/profiles/lead-gen'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can submit the contact form',
+      'Owner receives the lead by email',
+      'JSON-LD LocalBusiness schema renders',
+    ],
+    visual_checks: ['Hero CTA above the fold on mobile', 'Service area map placeholder or text present'],
+    deploy_checks: ['Live URL returns 200', '/contact form posts to /api/contact'],
+  },
+};
+
+export const MARKETING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'launch-soon',
+    display_name: 'Launch Soon',
+    summary: 'A single-page marketing site that announces a product, captures interest emails, and links to the GitHub repo.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'marketing',
+    confidence: 0.85,
+    why: ['No data persistence beyond email list', 'Single primary CTA', 'No transaction flow'],
+    secondary_profiles: ['lead-gen'],
+  },
+  audience: { primary: 'founder', buyer: 'GG', end_users: ['Early-interest visitors'] },
+  business_model: { types: ['brand_awareness'], pricing_notes: 'Free; pre-launch' },
+  scope: {
+    must_have_sections: ['hero', 'features', 'pricing', 'email signup', 'footer'],
+    core_flows: ['newsletter'],
+    non_goals: ['Multi-page v1', 'Blog v1'],
+  },
+  data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+  brand: {
+    vibe: ['bold', 'clear', 'modern'],
+    inspiration_urls: [],
+    color_notes: 'High contrast.',
+    font_notes: 'System sans, large hero.',
+    logo_notes: 'Wordmark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: { deadline: 'demo_today', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+  scaffold: {
+    base: 'next',
+    profile: 'marketing',
+    addons: [],
+    template_paths: ['templates/base', 'templates/profiles/marketing'],
+  },
+  verification: {
+    acceptance_tests: ['Visitor can submit email', 'Hero is readable on mobile'],
+    visual_checks: ['Hero readable at 420x900'],
+    deploy_checks: ['Live URL returns 200'],
+  },
+};
+
+// Alias export so that profile-name-derived lookups work consistently.
+export const SAAS_DASHBOARD_BRIEF = SAAS_BRIEF;
+
+export const SAMPLE_BRIEFS = {
+  marketing: MARKETING_BRIEF,
+  'lead-gen': LEAD_GEN_BRIEF,
+  booking: BOOKING_BRIEF,
+  blog: BLOG_BRIEF,
+  'saas-dashboard': SAAS_BRIEF,
+};

package/src/brief/schema.mjs

@@ -0,0 +1,176 @@
+// brief/schema.mjs: shape of brief.json + validation. Schema version 1.0.0.
+
+export const SCHEMA_VERSION = '1.0.0';
+
+export const PROFILES = ['marketing', 'lead-gen', 'booking', 'blog', 'storefront', 'saas-dashboard', 'directory', 'portfolio'];
+
+export const ADDONS = ['auth', 'payments', 'email', 'postgres', 'mdx', 'blob', 'analytics'];
+
+export const AUDIENCES = ['small_business', 'founder', 'agency', 'creator', 'community', 'other'];
+
+export const BUSINESS_MODELS = [
+  'lead_capture',
+  'booking_revenue',
+  'deposit',
+  'subscription',
+  'one_time_sale',
+  'content_traffic',
+  'dashboard',
+  'operations',
+  'brand_awareness',
+];
+
+export const CORE_FLOWS = [
+  'contact_form',
+  'booking',
+  'payment',
+  'auth',
+  'dashboard',
+  'content_crud',
+  'search_filter',
+  'newsletter',
+  'file_upload_download',
+  'other',
+];
+
+export const DATA_KINDS = [
+  'none',
+  'leads',
+  'bookings',
+  'products_orders',
+  'users_accounts',
+  'content',
+  'listings',
+  'files',
+  'unsure',
+];
+
+export const DEADLINES = ['demo_today', 'mvp_7_days', 'production_2_4_weeks', 'none'];
+
+export const BUDGET_POSTURES = ['free_tier_first', 'under_50_month', 'under_250_month', 'paid_ok'];
+
+const STRING = (v) => typeof v === 'string';
+const NONEMPTY = (v) => STRING(v) && v.trim().length > 0;
+const ARRAY_OF = (pred) => (v) => Array.isArray(v) && v.every(pred);
+
+export function validateBrief(brief) {
+  const errors = [];
+  if (!brief || typeof brief !== 'object') {
+    return { ok: false, errors: ['brief must be an object'] };
+  }
+
+  if (brief.schema_version !== SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${SCHEMA_VERSION}, got ${brief.schema_version}`);
+  }
+
+  const p = brief.project;
+  if (!p || typeof p !== 'object') {
+    errors.push('project missing');
+  } else {
+    if (!NONEMPTY(p.name)) errors.push('project.name required');
+    if (!NONEMPTY(p.summary)) errors.push('project.summary required');
+    if (p.summary && (p.summary.length < 20 || p.summary.length > 240)) {
+      errors.push('project.summary must be 20-240 chars');
+    }
+  }
+
+  const c = brief.classification;
+  if (!c || typeof c !== 'object') {
+    errors.push('classification missing');
+  } else {
+    if (!PROFILES.includes(c.site_profile)) {
+      errors.push(`classification.site_profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (typeof c.confidence !== 'number' || c.confidence < 0 || c.confidence > 1) {
+      errors.push('classification.confidence must be number 0-1');
+    }
+    if (!ARRAY_OF(NONEMPTY)(c.why)) {
+      errors.push('classification.why must be array of non-empty strings');
+    }
+  }
+
+  const a = brief.audience;
+  if (!a || typeof a !== 'object') {
+    errors.push('audience missing');
+  } else {
+    if (!AUDIENCES.includes(a.primary)) {
+      errors.push(`audience.primary must be one of: ${AUDIENCES.join(', ')}`);
+    }
+  }
+
+  const bm = brief.business_model;
+  if (!bm || typeof bm !== 'object') {
+    errors.push('business_model missing');
+  } else if (!Array.isArray(bm.types) || !bm.types.every((t) => BUSINESS_MODELS.includes(t))) {
+    errors.push(`business_model.types must be array of values from: ${BUSINESS_MODELS.join(', ')}`);
+  }
+
+  const scope = brief.scope;
+  if (!scope || typeof scope !== 'object') {
+    errors.push('scope missing');
+  } else {
+    if (!ARRAY_OF(NONEMPTY)(scope.must_have_sections) || scope.must_have_sections.length === 0) {
+      errors.push('scope.must_have_sections must be non-empty array');
+    }
+    if (!ARRAY_OF(NONEMPTY)(scope.core_flows) || scope.core_flows.length === 0) {
+      errors.push('scope.core_flows must be non-empty array');
+    }
+  }
+
+  const dm = brief.data_model;
+  if (!dm || typeof dm !== 'object') {
+    errors.push('data_model missing');
+  } else if (typeof dm.needs_storage !== 'boolean') {
+    errors.push('data_model.needs_storage must be boolean');
+  }
+
+  const brand = brief.brand;
+  if (!brand || typeof brand !== 'object') {
+    errors.push('brand missing');
+  } else if (!ARRAY_OF(NONEMPTY)(brand.vibe)) {
+    errors.push('brand.vibe must be array of strings');
+  }
+
+  const constraints = brief.constraints;
+  if (!constraints || typeof constraints !== 'object') {
+    errors.push('constraints missing');
+  } else {
+    if (!DEADLINES.includes(constraints.deadline)) {
+      errors.push(`constraints.deadline must be one of: ${DEADLINES.join(', ')}`);
+    }
+    if (!BUDGET_POSTURES.includes(constraints.budget_posture)) {
+      errors.push(`constraints.budget_posture must be one of: ${BUDGET_POSTURES.join(', ')}`);
+    }
+  }
+
+  const sc = brief.scaffold;
+  if (!sc || typeof sc !== 'object') {
+    errors.push('scaffold missing');
+  } else {
+    if (!PROFILES.includes(sc.profile)) {
+      errors.push(`scaffold.profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (!Array.isArray(sc.addons) || !sc.addons.every((a) => ADDONS.includes(a))) {
+      errors.push(`scaffold.addons must be array of values from: ${ADDONS.join(', ')}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function emptyBrief() {
+  return {
+    schema_version: SCHEMA_VERSION,
+    project: { name: '', display_name: '', summary: '', owner_or_client: '' },
+    classification: { site_profile: 'marketing', confidence: 0, why: [], secondary_profiles: [] },
+    audience: { primary: 'small_business', buyer: '', end_users: [] },
+    business_model: { types: [], pricing_notes: '' },
+    scope: { must_have_sections: [], core_flows: [], non_goals: [] },
+    data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+    brand: { vibe: [], inspiration_urls: [], color_notes: '', font_notes: '', logo_notes: '' },
+    inputs: { ingested: false, source_path: null, manifest_path: null },
+    constraints: { deadline: 'mvp_7_days', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+    scaffold: { base: 'next', profile: 'marketing', addons: [], template_paths: ['templates/base'] },
+    verification: { acceptance_tests: [], visual_checks: [], deploy_checks: [] },
+  };
+}

package/src/mvp-flow.mjs

@@ -17,6 +17,8 @@ import { renderSummary } from './summary.mjs';
 import { substitute, buildTokenMap } from './substitute.mjs';
 import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
 import { run as exec, isDryRun } from './exec.mjs';
+import { loadBrief, writeBriefFiles } from './brief/index.mjs';
+import { applyProfileOverlay } from './brief/profile-router.mjs';
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
@@ -33,7 +35,23 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
 
   preflightOrExit();
 
-  const answers = await runProjectPrompts({ flags });
+  let brief = null;
+  if (flags.brief) {
+    brief = await loadBrief(flags.brief);
+    process.stdout.write(`Loaded brief from ${resolve(flags.brief)}\n`);
+    process.stdout.write(`  Profile: ${brief.classification.site_profile} (confidence ${brief.classification.confidence})\n`);
+    process.stdout.write(`  Add-ons: ${(brief.scaffold.addons || []).join(', ') || '(none)'}\n`);
+  }
+
+  const promptFlags = brief
+    ? {
+        ...flags,
+        name: flags.name || brief.project.name,
+        profile: flags.profile || 'goodshin',
+      }
+    : flags;
+
+  const answers = await runProjectPrompts({ flags: promptFlags });
   if (!answers || answers.cancelled) {
     process.stdout.write('Cancelled.\n');
     const err = new Error('user cancelled prompts');
@@ -41,6 +59,14 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     throw err;
   }
 
+  if (brief) {
+    answers.displayName = brief.project.display_name || answers.displayName;
+    answers.description = brief.project.summary || answers.description;
+    if (brief.inputs?.source_path && !answers.ingestPath) {
+      answers.ingestPath = brief.inputs.source_path;
+    }
+  }
+
   printAnswersSummary(answers);
   if (!flags.yes) {
     const proceed = await confirmProceed();
@@ -76,6 +102,22 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   });
 
   await overlayKit({ targetDir, tokens });
+  if (brief) {
+    await writeBriefFiles({ targetDir, brief, force: true });
+    const overlay = await applyProfileOverlay({
+      targetDir,
+      profile: brief.scaffold.profile,
+      tokens,
+      dryRun: isDryRun(),
+    });
+    if (overlay.applied) {
+      process.stdout.write(`[brief] applied profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else if (isDryRun()) {
+      process.stdout.write(`[brief] would apply profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else {
+      process.stdout.write(`[brief] profile overlay '${brief.scaffold.profile}': ${overlay.reason}\n`);
+    }
+  }
   await writeProjectEnvFiles({ targetDir, collected: creds.collected });
   await ensureGitignoreEnv({ targetDir });
 

package/src/templates.mjs

@@ -26,6 +26,8 @@ export const REGISTRY = [
   { src: '.claude/commands/update-gui.md',    dest: '.claude/commands/update-gui.md' },
   { src: '.claude/commands/update-backend.md', dest: '.claude/commands/update-backend.md' },
   { src: '.claude/commands/add-storage.md',   dest: '.claude/commands/add-storage.md' },
+  { src: '.claude/commands/generate-image-prompt.md', dest: '.claude/commands/generate-image-prompt.md' },
+  { src: '.claude/commands/generate-image.md', dest: '.claude/commands/generate-image.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },

package/templates/.claude/commands/generate-image-prompt.md

@@ -0,0 +1,118 @@
+---
+description: Compose an image-generation prompt from the project brief plus 2-3 clarifying questions. Outputs a copy-pasteable prompt the operator pastes into DALL-E, Midjourney, Imagen, or any image tool. No API call, no key required.
+---
+
+# Generate image prompt (composer only)
+
+Use this when you need an image asset the project does not have yet. Composer only: produces a prompt for the operator to paste elsewhere. When the resulting image is dropped into `inputs/images/`, run `/update-image` to promote it per CLAUDE.md Part 19.
+
+## Step 1: identify the asset type
+
+If the operator named a type (e.g. `/generate-image-prompt hero`), use it. Otherwise ask.
+
+Asset types:
+
+| Type | Dimensions | Notes |
+|---|---|---|
+| `hero` | 1920x1080 | Focal point off-center to leave room for overlaid headline |
+| `background` | 2400x3000 or 1920x2400 | Full-bleed, subtle or busy is operator's call |
+| `og-image` | 1200x630 | Bold, brand-forward, high contrast for social previews |
+| `favicon` | 512x512 source | Mark only, no scene, must read at 16x16 |
+| `infographic` | operator-defined | Clean type, flat or isometric, tight palette |
+| `brand-scene` | 1920x1080 | Lifestyle or product photography style |
+| `card` | 1200x900 or 1080x1080 | Focal image with headline headroom |
+| `logo` | 1024x1024 | Mark only, transparent background preferred |
+
+## Step 2: read the project context
+
+```bash
+[ -f docs/branding/ostup-brand-brief.md ] && cat docs/branding/ostup-brand-brief.md 2>/dev/null
+[ -f inputs/INGEST_MANIFEST.md ] && cat inputs/INGEST_MANIFEST.md 2>/dev/null
+[ -f inputs/README.md ] && cat inputs/README.md 2>/dev/null
+ls inputs/images/ 2>/dev/null
+grep -A 5 "Brand\|palette\|Visual identity\|tone" CLAUDE.md AGENTS.md 2>/dev/null | head -40
+[ -f docs/brief.md ] && cat docs/brief.md 2>/dev/null
+```
+
+Absorb: brand voice, color palette, mood, any existing visual style references, anything the brief specifies.
+
+## Step 3: ask at most 3 clarifying questions
+
+Tailor per asset type. Defaults below.
+
+For `hero`:
+- What is the subject in one phrase?
+- Mood: bold / quiet / playful / serious?
+- Any image already in `inputs/images/` to riff on?
+
+For `og-image`:
+- What headline word or short phrase should dominate?
+- Same palette as the rest of the site or a contrast variant?
+
+For `favicon`:
+- Use the existing logo mark, or a simplified abstraction of it?
+
+For `background`:
+- Specific subject or abstract texture?
+- Light or dark dominant?
+
+For others: subject, palette, mood unless the brief makes it obvious.
+
+## Step 4: compose the prompt
+
+Use this exact output shape. Fill every field. Honor the brand palette from the brief.
+
+```
+PROMPT
+------
+<one paragraph, vivid, specific. Cover: subject, composition, lighting, color
+palette (echo the brief), style references like "editorial photography" or
+"isometric flat illustration" or "product hero shot". End with concrete
+detail anchors.>
+
+MODEL RECOMMENDATION
+--------------------
+<pick one with a one-line reason:
+  - DALL-E 3: photorealism, reliable text-following
+  - Midjourney v6: strongest art direction, painterly
+  - Imagen: best typography
+  - Stable Diffusion via Replicate: fastest iteration, lowest cost>
+
+SIZE / ASPECT RATIO
+-------------------
+<exact dims for the asset type from Step 1>
+
+NEGATIVE PROMPT (if applicable)
+-------------------------------
+<one line: things to exclude. e.g. "no text, no people, no logos in frame, no watermarks">
+
+STYLE NOTES
+-----------
+<one line: e.g. "seed=2024 for reproducibility, subject off-center to leave
+right third clear for overlaid headline">
+```
+
+## Step 5: report
+
+```
+Composed prompt for <asset type>.
+
+Paste the PROMPT block above into your chosen image tool. When the image is
+back, save it to inputs/images/ with a clear filename (e.g.
+inputs/images/hero-v1.png).
+
+Then run /update-image <slot> to promote it into the project and verify
+visually per CLAUDE.md Part 19.
+
+To skip the paste-into-another-tool step, use /generate-image instead. That
+calls Vercel AI Gateway directly and saves the result to inputs/images/
+(requires VERCEL_AI_GATEWAY_KEY in env).
+```
+
+## Hard rules
+
+- Always honor the brand palette from the brief. Do not invent colors.
+- Always specify exact dimensions.
+- Never claim done. This command only composes a prompt.
+- If the brief and operator answers conflict, surface the conflict and ask. Do not silently choose one.
+- The PROMPT block must be copy-pasteable as-is; do not wrap it in commentary.