@oaklandzoo/ostup 0.1.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.1.2",
+  "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/mvp-flow.mjs

@@ -1,6 +1,7 @@
 // mvp-flow.mjs: orchestrate the full MVP scaffold: preflight, prompts, creds, scaffold, GitHub, Vercel, inject, summary.
 import { existsSync } from 'node:fs';
-import { readdir, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { readdir, mkdir, writeFile, readFile, rm, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { preflightOrExit } from './preflight.mjs';
@@ -56,6 +57,7 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   const targetDir = resolve(cwd, answers.projectName);
   await ensureFreshTarget(targetDir, flags.force);
   await mkdir(targetDir, { recursive: true });
+  await ensureMemoryDir(targetDir);
 
   await maybeScaffoldStack({ stack: answers.stack, projectName: answers.projectName, targetDir });
 
@@ -179,6 +181,16 @@ async function writeOne({ entry, targetDir, tokens, defer }) {
   const out = substitute(raw, tokens, { defer });
   await mkdir(dirname(dest), { recursive: true });
   await writeFile(dest, out, 'utf8');
+  if (entry.executable) {
+    await chmod(dest, 0o755);
+  }
+}
+
+export async function ensureMemoryDir(targetDir) {
+  const sanitized = targetDir.replace(/[/ ]/g, '-');
+  const memoryDir = join(homedir(), '.claude', 'projects', sanitized, 'memory');
+  await mkdir(memoryDir, { recursive: true });
+  return memoryDir;
 }
 
 async function writeProjectEnvFiles({ targetDir, collected }) {

package/src/scaffold.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
@@ -38,6 +39,7 @@ export async function scaffold({ targetDir, flags, stdinIsTTY = process.stdin.is
   const tokens = buildTokenMap(values);
 
   await mkdir(absTarget, { recursive: true });
+  await ensureMemoryDir(absTarget);
 
   for (const entry of REGISTRY) {
     await writeOne({ entry, absTarget, tokens });
@@ -60,6 +62,15 @@ async function writeOne({ entry, absTarget, tokens }) {
   const out = substitute(raw, tokens);
   await mkdir(dirname(dest), { recursive: true });
   await writeFile(dest, out, 'utf8');
+  if (entry.executable) {
+    await chmod(dest, 0o755);
+  }
+}
+
+async function ensureMemoryDir(absTarget) {
+  const sanitized = absTarget.replace(/[/ ]/g, '-');
+  const memoryDir = join(homedir(), '.claude', 'projects', sanitized, 'memory');
+  await mkdir(memoryDir, { recursive: true });
 }
 
 async function ensureTargetReady(absTarget, force) {

package/src/templates.mjs

@@ -21,6 +21,13 @@ export const REGISTRY = [
   { src: '.claude/commands/prompt-end.md',    dest: '.claude/commands/prompt-end.md' },
   { src: '.claude/commands/create-prd.md',    dest: '.claude/commands/create-prd.md' },
   { src: '.claude/commands/generate-tasks.md', dest: '.claude/commands/generate-tasks.md' },
+  { src: '.claude/commands/preflight.md',     dest: '.claude/commands/preflight.md' },
+  { src: '.claude/commands/update-image.md',  dest: '.claude/commands/update-image.md' },
+  { 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' },
@@ -31,6 +38,7 @@ export const REGISTRY = [
   { src: 'docs/ARCHITECTURE.md',               dest: 'docs/ARCHITECTURE.md' },
   { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
   { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
+  { src: 'scripts/screenshot.sh',              dest: 'scripts/screenshot.sh', executable: true },
 ];
 
 export const OPTIONAL_REGISTRY = [

package/templates/.claude/commands/add-storage.md

@@ -0,0 +1,112 @@
+---
+description: Provision a Vercel storage product (Blob, KV, Postgres, Edge Config), pull its env vars, and scaffold a typed lib helper.
+---
+
+# Add storage
+
+## Step 1: which type
+
+If the operator named a type (e.g. `/add-storage blob`), use it. Otherwise ask:
+
+| Type | What it is | When to pick |
+|---|---|---|
+| `blob` | File storage with public URLs | Image uploads, downloads, generated PDFs |
+| `kv` | Redis-style key/value | Sessions, caches, counters, rate limits |
+| `postgres` | Relational SQL | Users, transactions, anything with joins |
+| `edge-config` | Read-heavy small config (<8 KB) | Feature flags, A/B variants, allowlists |
+
+## Step 2: check what already exists
+
+```bash
+vercel <type> list-stores --all 2>&1 | head -10
+```
+
+If a suitable store already exists, ask the operator if they want to reuse it instead of creating a new one. Skip to Step 4 if reusing.
+
+## Step 3: provision a new store
+
+Ask for a store name. Default to `<project-name>-<type>`. Then run:
+
+```bash
+vercel <type> create-store <name> \
+  --environment production --environment preview --environment development --yes
+```
+
+For `blob`, also include `--access public` if the stored objects should be served via public URLs:
+
+```bash
+vercel blob create-store <name> --access public --yes \
+  --environment production --environment preview --environment development
+```
+
+Capture the output (store ID, etc.) and surface it.
+
+## Step 4: pull env vars
+
+```bash
+vercel env pull .env.local
+```
+
+Confirm `.env.local` got the new keys. Common ones:
+
+| Type | Keys |
+|---|---|
+| blob | `BLOB_READ_WRITE_TOKEN` |
+| kv | `KV_URL`, `KV_REST_API_URL`, `KV_REST_API_TOKEN`, `KV_REST_API_READ_ONLY_TOKEN` |
+| postgres | `POSTGRES_URL`, `POSTGRES_PRISMA_URL`, `POSTGRES_URL_NON_POOLING`, `POSTGRES_USER`, etc. |
+| edge-config | `EDGE_CONFIG` |
+
+## Step 5: install the SDK and scaffold the lib helper
+
+```bash
+npm install @vercel/<type>
+```
+
+Create `src/lib/<type>.ts` with typed helpers. Example for blob:
+
+```typescript
+// src/lib/blob.ts
+import { put, list, del } from '@vercel/blob';
+
+export async function uploadFile(path: string, body: Blob | ArrayBuffer | string) {
+  return put(path, body, { access: 'public' });
+}
+
+export async function listFiles(prefix?: string) {
+  return list({ prefix });
+}
+
+export async function deleteFile(url: string) {
+  return del(url);
+}
+```
+
+Match the project's existing TypeScript conventions (named exports, no defaults, etc.).
+
+## Step 6: update AGENTS.md
+
+Append under a `## Storage` section:
+
+```markdown
+## Storage
+
+- `<type>`: `src/lib/<type>.ts`. Store: `<name>`. Env vars in `.env.local`.
+```
+
+## Step 7: commit and push
+
+```bash
+git add src/lib/<type>.ts AGENTS.md package.json package-lock.json
+git commit -m "feat(storage): add <type> via src/lib/<type>.ts"
+git push
+```
+
+## Step 8: report
+
+```
+Added <type> storage:
+- Store:  <name>
+- Lib:    src/lib/<type>.ts
+- Env:    <list of keys>
+- Deploy: <url>
+```

package/templates/.claude/commands/bootstrap.md

@@ -22,6 +22,9 @@ find . -maxdepth 2 -type d ! -path '*/node_modules*' ! -path '*/.git*' ! -path '
 [ -f inputs/INGEST_MANIFEST.md ] && cat inputs/INGEST_MANIFEST.md
 [ -f inputs/README.md ] && cat inputs/README.md
 [ -d inputs ] && ls -la inputs/
+# Helpers available in this kit
+[ -x scripts/screenshot.sh ] && echo "scripts/screenshot.sh ready (required for visual verification per CLAUDE.md Part 19)"
+ls .claude/commands/ 2>/dev/null
 ```
 
 ## Step 2: Determine what you know

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

@@ -0,0 +1,65 @@
+---
+description: Surface what is already provisioned for this project (Vercel auth, blob stores, gh auth, env vars, Chrome). Prevents the agent from assigning CLI work it could do itself.
+---
+
+# Preflight
+
+Run at the start of any session where you might touch Vercel, gh, the GUI, or storage. The output tells you what already exists so you do not duplicate setup or assign the operator CLI work that is already done.
+
+## Step 1: probe everything in one block
+
+```bash
+echo "=== Vercel ==="
+vercel whoami 2>&1 | head -3
+if [ -f .vercel/project.json ]; then
+  echo "Linked:"
+  cat .vercel/project.json
+else
+  echo "Not linked (no .vercel/project.json)"
+fi
+echo ""
+echo "Blob stores:"
+vercel blob list-stores --all 2>&1 | head -10
+echo ""
+echo "Env vars:"
+vercel env list 2>&1 | head -15
+
+echo ""
+echo "=== GitHub ==="
+gh auth status 2>&1 | head -5
+git remote -v 2>&1 | head -2
+
+echo ""
+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
+
+After reading the output, print exactly:
+
+```
+SESSION READY
+
+Vercel:     <authed as X | linked to project Y | N blob stores | M env vars>
+GitHub:     <authed | remote URL>
+Chrome:     <present | MISSING>
+Screenshot: <ready | missing>
+Node:       <version>
+
+Anything missing above must be flagged before claiming any work that depends on it.
+```
+
+## Step 3: hard rule
+
+Do NOT propose CLI steps the operator should run for anything Vercel or gh already covers per the SESSION READY line above. CLAUDE.md Part 3 Rule 9 is the constraint: agent does what the agent can do.

package/templates/.claude/commands/update-backend.md

@@ -0,0 +1,74 @@
+---
+description: Make a backend logic change (API route, lib function, server action), deploy, and verify the new behavior via API call before claiming done.
+---
+
+# Update backend
+
+Non-visual analog to `/update-gui`. Verify behavior, not just compile.
+
+## Step 1: confirm intent
+
+Restate the change in one sentence. Get a thumbs-up before editing if scope is non-trivial.
+
+## Step 2: edit
+
+Make the change. Minimal diff.
+
+## Step 3: write or run a test
+
+If a test framework is configured, run the test suite:
+
+```bash
+npm test 2>&1 | tail -10
+```
+
+If no tests exist for the touched code, write one that exercises the new behavior (preferred), or capture an expected response shape for Step 6.
+
+If no test framework exists at all, skip to Step 4 and rely on the curl probe in Step 6.
+
+## Step 4: build
+
+```bash
+npm run build 2>&1 | tail -10
+```
+
+If the build fails, fix before deploying.
+
+## Step 5: deploy
+
+```bash
+git add <changed-files>
+git commit -m "<short message>"
+git push
+```
+
+Wait ~60 seconds for Vercel auto-deploy.
+
+## Step 6: probe the live endpoint
+
+For an API route change:
+
+```bash
+curl -s -i "<deploy-url>/api/<route>" | head -20
+```
+
+For a route that takes a body:
+
+```bash
+curl -s -X POST "<deploy-url>/api/<route>" \
+  -H "Content-Type: application/json" \
+  -d '{"key":"value"}' | head -20
+```
+
+Compare the response to the expected shape from Step 3.
+
+## Step 7: report
+
+```
+Backend change shipped: <one-line description>
+Deploy: <url>
+Verified via: <test name or curl command>
+Response: <status, key field, whatever proves it works>
+```
+
+If verification fails, do NOT claim done. Diagnose, fix, re-deploy, re-probe.

package/templates/.claude/commands/update-gui.md

@@ -0,0 +1,55 @@
+---
+description: Make a UI change, deploy it, and verify visually before claiming done. Enforces CLAUDE.md Part 19.
+---
+
+# Update GUI
+
+This command exists so that CLAUDE.md Part 19 (visual verification) is the default for any UI change, not an afterthought.
+
+## Step 1: confirm intent
+
+The operator described the change. Restate it in one sentence and get a thumbs-up before editing if the scope is non-trivial. Skip the thumbs-up for tiny changes (typo, single color, single class).
+
+## Step 2: edit
+
+Make the change. Keep the diff minimal. No unrelated cleanup in the same commit.
+
+## Step 3: build locally
+
+```bash
+npm run build 2>&1 | tail -10
+```
+
+If the build fails, fix before deploying.
+
+## Step 4: deploy
+
+```bash
+git add <changed-files>
+git commit -m "<short message>"
+git push
+```
+
+Wait ~60 seconds for Vercel auto-deploy.
+
+## Step 5: screenshot
+
+```bash
+scripts/screenshot.sh <deploy-url> /tmp/gui-check.png 420,900
+```
+
+## Step 6: read the PNG
+
+Use the Read tool on `/tmp/gui-check.png`. Confirm the visual change matches what the operator asked for. If it does not, diagnose (CSS regression, z-index, cache, stale file path) and re-deploy. Do NOT claim done.
+
+## Step 7: report
+
+```
+GUI change shipped: <one-line description>
+Deploy: <url>
+Screenshot: /tmp/gui-check.png (read, change confirmed)
+```
+
+## Hard rule
+
+HTTP 200, build success, lint pass, byte counts: none of these count as visual verification. Only a read PNG counts.

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

@@ -0,0 +1,57 @@
+---
+description: Swap an image referenced in the codebase (background, hero, logo) using a candidate from inputs/images/. Always ends with screenshot verification per CLAUDE.md Part 19.
+---
+
+# Update an image
+
+## Step 1: figure out the slot
+
+If the operator named a slot (e.g. `/update-image bg-week`), use that.
+
+If not, list every image reference in the codebase:
+
+```bash
+grep -rln -E "/(bg|hero|logo|images?)/[a-zA-Z0-9_-]+\.(png|jpg|jpeg|svg|webp|avif)" src/ public/ 2>/dev/null
+```
+
+Show the operator the slots and ask which to update.
+
+## Step 2: pick the source
+
+List candidates in `inputs/images/`:
+
+```bash
+ls -la inputs/images/ 2>/dev/null
+```
+
+If there is an `inputs/images/MANIFEST.md`, read it for filenames and captions.
+
+If multiple candidates and the choice is not obvious, ask the operator. Do NOT Read more than 3 image files at a time — each Read returns a vision payload that is heavy in context.
+
+## Step 3: swap it in
+
+1. Copy the chosen file from `inputs/images/` to the right path under `public/`.
+2. Update any code references if the filename changed.
+3. `git add <changed files>` (the new image plus any code).
+4. `git commit -m "feat(images): swap <slot>"`
+5. `git push` (Vercel auto-deploys).
+
+## Step 4: verify visually (REQUIRED per CLAUDE.md Part 19)
+
+Wait ~60 seconds for Vercel to deploy. Then:
+
+```bash
+scripts/screenshot.sh <deploy-url> /tmp/after-swap.png 420,900
+```
+
+Read the resulting PNG with the Read tool. Confirm the new image is showing in the slot.
+
+## Step 5: report
+
+```
+Swapped <slot>: <old-filename> -> <new-filename>
+Deploy: <url>
+Screenshot: /tmp/after-swap.png (read and verified)
+```
+
+If the screenshot does not show the change, do NOT claim done. Diagnose (CSS z-index, wrong path, wrong file) and re-deploy before reporting.

package/templates/AGENTS.md

@@ -27,7 +27,12 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 ## Slash commands available
 
-- `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`
-- `/create-prd`, `/generate-tasks`
+Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`
 
-See each file under `.claude/commands/` for details.
+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.
+
+## Helpers
+
+- `scripts/screenshot.sh <url> [out] [WxH]` — headless Chrome screenshot. Required for visual verification per `CLAUDE.md` Part 19.

package/templates/CLAUDE.md

@@ -254,3 +254,16 @@ Detailed file map: `docs/ARCHITECTURE.md`.
 | What happened recently | `docs/SESSION_NOTES.md` |
 | Stack and file map | `docs/ARCHITECTURE.md` |
 | How to behave | `CLAUDE.md` (this file) |
+
+---
+
+# PART 19: VISUAL VERIFICATION
+
+Any change that affects what the operator sees in a browser (HTML, CSS, Tailwind classes, image swaps, layout, copy in JSX, fonts, colors, hero sections, anything rendered) is NOT done until BOTH of the following are true:
+
+1. `scripts/screenshot.sh <deployed-url>` has been run after the change is deployed.
+2. The resulting PNG has been read with the Read tool and the visual change is confirmed to match the intent.
+
+HTTP 200, build success, lint passing, byte counts of the deployed HTML: none of these count as visual verification.
+
+If `scripts/screenshot.sh` is missing or Chrome is not installed, surface the gap before claiming the change is done. Do not assume.

package/templates/START_HERE.md

@@ -47,11 +47,18 @@ Type these in your CLI agent. Each runs a structured routine.
 | Command | What it does | When to run it |
 |---|---|---|
 | `/bootstrap` | Scans the repo and asks up to 5 clarifiers, then fills in `CLAUDE.md` Parts 13 to 17 and `docs/ARCHITECTURE.md` with your project's real facts. | Once, on the first session. |
+| `/preflight` | Surfaces what is already provisioned (Vercel auth, blob stores, gh auth, env vars, Chrome). Stops the agent from assigning CLI work it could do itself. | Start of any session where you might touch Vercel, gh, the GUI, or storage. |
 | `/prompt-start` | Reads HANDOFF, MANUAL_TASKS, git status. Briefs the agent on the current state. Asks "Proceed or pivot?" | Start of every session after the first. |
 | `/prompt-mid` | Checks context budget, restates progress, verifies any files the agent claimed to write actually exist. | Mid-session, if you feel lost or the agent seems off-track. |
 | `/prompt-end` | Rewrites HANDOFF, appends to SESSION_NOTES, surfaces any new blockers to MANUAL_TASKS. | End of every session. Always. Without this the next session has no memory of what just happened. |
 | `/create-prd` | Asks 3 to 5 clarifying questions, then writes a PRD to `tasks/prd-<feature>.md`. | Before building a significant new feature. Optional for small changes. |
 | `/generate-tasks` | Reads a PRD, breaks it into a phased task list at `tasks/tasks-<feature>.md` (parent tasks first, then sub-tasks after you say "Go"). | After a PRD is approved, before the agent starts coding. |
+| `/update-image` | Swap an image (background, hero, logo) using a candidate from `inputs/images/`. Ends with screenshot verification. | Any time you want to change a visual asset. |
+| `/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
 

package/templates/scripts/screenshot.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Headless Chrome screenshot helper. Use to visually verify a UI change.
+# Required by CLAUDE.md Part 19 (Visual Verification).
+#
+# Usage:   scripts/screenshot.sh <url> [output-path] [width,height]
+# Example: scripts/screenshot.sh https://your-app.vercel.app /tmp/check.png 420,900
+
+set -e
+
+if [ -z "$1" ]; then
+  echo "Usage: $0 <url> [output-path] [width,height]" >&2
+  echo "Example: $0 https://your-app.vercel.app /tmp/check.png 420,900" >&2
+  exit 1
+fi
+
+URL="$1"
+OUT="${2:-/tmp/screenshot-$(date +%s).png}"
+SIZE="${3:-420,900}"
+
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+if [ ! -x "$CHROME" ]; then
+  CHROME="$(command -v chromium 2>/dev/null || command -v google-chrome 2>/dev/null || echo '')"
+fi
+
+if [ -z "$CHROME" ] || [ ! -x "$CHROME" ]; then
+  echo "ERROR: Chrome not found. Install Google Chrome from https://www.google.com/chrome/" >&2
+  exit 1
+fi
+
+"$CHROME" \
+  --headless=new --disable-gpu --hide-scrollbars \
+  --window-size="$SIZE" --virtual-time-budget=4000 \
+  --screenshot="$OUT" "$URL" 2>/dev/null
+
+echo "$OUT"