@oaklandzoo/ostup 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

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.

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

@@ -0,0 +1,168 @@
+---
+description: Compose an image-generation prompt AND call Vercel AI Gateway to actually generate the image. Saves to inputs/images/ and appends to MANIFEST.md. Requires VERCEL_AI_GATEWAY_KEY. Per CLAUDE.md Part 19, use /update-image to promote into the project.
+---
+
+# Generate image (composer plus API call)
+
+Same flow as `/generate-image-prompt`, but calls Vercel AI Gateway and saves the result. Operator skips the paste-into-another-tool step.
+
+## Step 1: preflight
+
+Check the key exists:
+
+```bash
+if [ -n "$VERCEL_AI_GATEWAY_KEY" ]; then
+  echo "VERCEL_AI_GATEWAY_KEY: present"
+else
+  echo "VERCEL_AI_GATEWAY_KEY: MISSING"
+  echo "Get a key: https://vercel.com/dashboard/ai-gateway"
+  echo "Set it in .env.local (export VERCEL_AI_GATEWAY_KEY=...) and rerun."
+  echo "Aborting."
+fi
+```
+
+If the key is missing, stop and ask the operator to set it. Do not call the API without a key.
+
+## Step 2: identify the asset type, read context, ask clarifying questions
+
+Run Steps 1-3 of `/generate-image-prompt`. Compose the prompt in memory (or print it first for operator review if scope is significant).
+
+## Step 3: surface cost estimate before calling
+
+Print exactly:
+
+```
+About to call Vercel AI Gateway:
+  Model:           openai/dall-e-3
+  Size:            1024x1024
+  Quality:         standard
+  Estimated cost:  ~$0.04 (DALL-E 3 standard 1024x1024)
+
+Proceed? (y/n)
+```
+
+Wait for operator confirmation. If they answer no, stop. If they answer yes (or the agent was invoked with `--yes` semantics from /update-image), proceed.
+
+Cost reference (verify against current Vercel AI Gateway pricing before claiming numbers):
+
+| Model | Size | Cost per image |
+|---|---|---:|
+| openai/dall-e-3 | 1024x1024 standard | ~$0.04 |
+| openai/dall-e-3 | 1024x1024 hd | ~$0.08 |
+| openai/dall-e-3 | 1792x1024 standard | ~$0.08 |
+| openai/dall-e-3 | 1792x1024 hd | ~$0.12 |
+| stability-ai/stable-diffusion-xl | 1024x1024 | ~$0.003 |
+
+If size or model differs from defaults, recompute and surface.
+
+## Step 4: call the API
+
+Use bash and curl. OpenAI-compatible endpoint via Vercel AI Gateway.
+
+```bash
+TIMESTAMP=$(date +%s)
+TYPE="<asset-type>"
+OUT="inputs/images/${TYPE}-${TIMESTAMP}.png"
+mkdir -p inputs/images
+
+# Use a heredoc to safely encode the prompt
+PROMPT_JSON=$(cat <<'JSON_EOF'
+{
+  "model": "openai/dall-e-3",
+  "prompt": "<COMPOSED_PROMPT_GOES_HERE>",
+  "size": "1024x1024",
+  "quality": "standard",
+  "n": 1,
+  "response_format": "b64_json"
+}
+JSON_EOF
+)
+
+curl -s https://ai-gateway.vercel.sh/v1/images/generations \
+  -H "Authorization: Bearer $VERCEL_AI_GATEWAY_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$PROMPT_JSON" > /tmp/ostup-img-response.json
+
+# Verify success
+if ! grep -q "b64_json" /tmp/ostup-img-response.json 2>/dev/null; then
+  echo "API call failed. Response:"
+  cat /tmp/ostup-img-response.json
+  exit 1
+fi
+
+# Extract base64 and write the PNG
+python3 -c "
+import json, base64, sys
+with open('/tmp/ostup-img-response.json') as f:
+    d = json.load(f)
+b64 = d['data'][0]['b64_json']
+with open('$OUT', 'wb') as f:
+    f.write(base64.b64decode(b64))
+print('Saved:', '$OUT')
+"
+
+rm -f /tmp/ostup-img-response.json
+```
+
+If the model returns a URL instead of base64 (some configurations), fall back to:
+
+```bash
+URL=$(python3 -c "import json; print(json.load(open('/tmp/ostup-img-response.json'))['data'][0]['url'])")
+curl -sL -o "$OUT" "$URL"
+```
+
+## Step 5: append to manifest
+
+```bash
+MANIFEST="inputs/images/MANIFEST.md"
+
+# Initialize if missing
+if [ ! -f "$MANIFEST" ]; then
+  echo "# Image manifest" > "$MANIFEST"
+  echo "" >> "$MANIFEST"
+  echo "Generated images, prompts used, models, and timestamps." >> "$MANIFEST"
+  echo "" >> "$MANIFEST"
+fi
+
+cat >> "$MANIFEST" <<EOF
+
+## ${TIMESTAMP} — <asset-type>
+
+- **File:** \`${OUT}\`
+- **Model:** openai/dall-e-3
+- **Size:** 1024x1024
+- **Quality:** standard
+- **Cost:** ~\$0.04
+- **Prompt:**
+  > <COMPOSED_PROMPT_SUMMARY_ONE_LINE>
+
+EOF
+```
+
+## Step 6: report and offer to promote
+
+```
+Generated <asset type>: inputs/images/<asset-type>-<timestamp>.png
+Manifest updated: inputs/images/MANIFEST.md
+
+Want to promote it into the project now? Running /update-image <slot> will:
+  1. Copy this image into public/<slot>/
+  2. Update any code references
+  3. Commit + push
+  4. Wait for Vercel deploy
+  5. Run scripts/screenshot.sh and read the PNG to verify visually
+
+Proceed with /update-image? (y/n)
+```
+
+If operator agrees, run the full `/update-image` routine. Otherwise stop.
+
+## Hard rules
+
+- Generated images land in `inputs/images/` ONLY. Never directly in `public/`. The operator (or `/update-image`) promotes.
+- Every generation appends a manifest line with prompt + model + size + timestamp + cost.
+- Cost is always surfaced before the API call. No surprise charges.
+- Missing `VERCEL_AI_GATEWAY_KEY` fails fast with a clear pointer to the dashboard URL.
+- Brand palette from the brief must be in the prompt. No "free interpretation."
+- This command does not promote the image. `/update-image` handles promotion + Part 19 visual verification.
+- If the API call fails (rate limit, content policy, network), report the full error and do NOT retry silently.

package/templates/.claude/commands/preflight.md

@@ -34,6 +34,14 @@ echo "=== Local tools ==="
 node --version
 [ -d "/Applications/Google Chrome.app" ] && echo "Chrome: present" || echo "Chrome: MISSING (operator must install for visual verification per CLAUDE.md Part 19)"
 [ -x "scripts/screenshot.sh" ] && echo "scripts/screenshot.sh: ready" || echo "scripts/screenshot.sh: MISSING or not executable"
+
+echo ""
+echo "=== AI Gateway (for /generate-image) ==="
+if [ -n "$VERCEL_AI_GATEWAY_KEY" ]; then
+  echo "VERCEL_AI_GATEWAY_KEY: present (image generation enabled)"
+else
+  echo "VERCEL_AI_GATEWAY_KEY: not set (/generate-image will fail until set; get one at https://vercel.com/dashboard/ai-gateway; /generate-image-prompt still works as composer-only)"
+fi
 ```
 
 ## Step 2: print the SESSION READY summary

package/templates/AGENTS.md

@@ -29,7 +29,7 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`
 
-Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`
+Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
 
 See each file under `.claude/commands/` for the full routine.
 

package/templates/START_HERE.md

@@ -57,6 +57,8 @@ Type these in your CLI agent. Each runs a structured routine.
 | `/update-gui` | Make a UI change, deploy, screenshot, confirm the visual change matches intent. Enforces visual verification. | Any UI tweak. |
 | `/update-backend` | Make a backend/API change, deploy, probe the live endpoint, confirm behavior. | Any server/API change. |
 | `/add-storage` | Provision a Vercel Blob, KV, Postgres, or Edge Config store + scaffold a typed `src/lib/<type>.ts` helper + pull env vars. | When you need persistent storage. |
+| `/generate-image-prompt` | Compose an image-generation prompt from the project brief + 2-3 questions. No API call. Paste the prompt into your preferred image tool. | When you need a visual asset and want to use Midjourney, DALL-E, Imagen, etc. directly. |
+| `/generate-image` | Compose the prompt AND call Vercel AI Gateway, saving the image to `inputs/images/`. Requires `VERCEL_AI_GATEWAY_KEY`. | When you want the image generated in-line without leaving your agent. |
 
 ## Three workflows