@oaklandzoo/ostup 0.3.0 → 0.5.0

package/templates/profiles/marketing/README.md

@@ -0,0 +1,39 @@
+# Profile: marketing
+
+> Single-page or short marketing site. Default for projects with weak signals.
+
+## Day-one scope
+
+| Section | Purpose | Required |
+|---|---|---|
+| Hero | Single primary value statement + one CTA (email or "Get started") | yes |
+| Features | 3-6 short benefit cards | yes |
+| Social proof / Testimonials | Quote, logo strip, or "in use at" line | optional |
+| Pricing | One or two tiers, simple | optional |
+| Email signup | Inline form posting to /api/subscribe (no DB; logs or forwards) | optional |
+| Footer | Links, year, attribution | yes |
+
+## Wired infrastructure
+
+None by default. Pure static.
+
+If the brief includes `email` add-on (newsletter signup), the agent should wire Resend or a generic webhook for the form submission.
+
+## What ships in this overlay
+
+- `section-prompts.md` — concrete guidance for each section.
+- Anything in `.additions` is appended to the matching scaffolded file.
+
+## Hard rules
+
+- Mobile-first. Test at 420x900 with `scripts/screenshot.sh`.
+- No third-party tracking. No popups. No chat widget.
+- One CTA per page. If a section has its own CTA, route it to the same destination as the hero CTA.
+- All copy comes from `docs/brief.md`. The agent paraphrases for the page, never invents new claims.
+
+## Acceptance
+
+- Hero readable at 420x900.
+- Single primary CTA visible above the fold.
+- Lighthouse mobile Performance >= 90, Accessibility >= 95.
+- No console errors.

package/templates/profiles/marketing/section-prompts.md

@@ -0,0 +1,36 @@
+# Marketing profile section prompts
+
+Agent: build each section using the brief in `docs/brief.md`. Do not invent claims.
+
+## Hero
+
+- 1 headline (5-9 words) drawn from `project.summary`.
+- 1 subhead (one sentence) describing who it is for and what changes.
+- 1 primary CTA button. Text is imperative, e.g. "Get the early access link" or "Start free."
+- Optional: small visual (an SVG mark from `inputs/images/`, NOT a generic stock photo).
+
+## Features (3-6 cards)
+
+- Each card has: short title (3-5 words) + one-sentence description.
+- Pull titles from `scope.must_have_sections` (skip "hero" and "footer").
+- Description echoes the brief vibe in `brand.vibe`.
+- Use a grid; on mobile stack 1 column.
+
+## Pricing (if included)
+
+- 1-3 tiers. Each tier: name, price (or "free"), 3-5 bullets, single CTA.
+- Use the pricing notes in `business_model.pricing_notes`.
+- If no pricing info in brief, omit the section entirely. Do not invent prices.
+
+## Email signup
+
+- One field (email) + one button.
+- Submit to `/api/subscribe` (or `/api/contact`).
+- Inline success message on submit: "You're on the list."
+- No double opt-in flow v1.
+
+## Footer
+
+- Copyright year (current).
+- 2-4 links max: GitHub, npm, docs, contact.
+- No social icons unless the brief says social presence matters.

package/templates/profiles/saas-dashboard/.env.example.additions

@@ -0,0 +1,21 @@
+# --- saas-dashboard profile additions ---
+# Auth (Better Auth)
+BETTER_AUTH_SECRET=
+BETTER_AUTH_URL=http://localhost:3000
+
+# Database (Neon recommended for Postgres)
+DATABASE_URL=
+
+# Stripe subscriptions
+STRIPE_SECRET_KEY=
+STRIPE_PUBLISHABLE_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PRICE_ID_SOLO=
+STRIPE_PRICE_ID_TEAM=
+
+# Public app URL
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Email (for verification + password reset)
+RESEND_API_KEY=
+AUTH_FROM_EMAIL=noreply@example.com

package/templates/profiles/saas-dashboard/README.md

@@ -0,0 +1,60 @@
+# Profile: saas-dashboard
+
+> SaaS MVP with auth, subscription billing skeleton, dashboard shell, settings. Pick the workflow over feature depth.
+
+## Day-one scope
+
+| Section | Purpose | Required |
+|---|---|---|
+| Landing hero | Convert visitor to signup | yes |
+| Pricing | 1-3 tiers, monthly + annual toggle | yes |
+| Sign up / Log in | Better Auth flow (email+password or magic link) | yes |
+| Dashboard shell | Authenticated route, empty state with onboarding hint | yes |
+| Settings | Profile + billing pages | yes |
+| Billing | Stripe Customer Portal link OR a stub for "manage subscription" | yes |
+| Footer | Links, year, GitHub, status page link if any | yes |
+
+## Wired infrastructure
+
+- **Better Auth** for authentication. Email+password v1; magic link v2.
+- **Postgres** for `User` + any product entities from the brief.
+- **Stripe** for subscriptions. Use Stripe Checkout for initial signup, Stripe Customer Portal for management.
+- **Middleware** at the route level: unauthenticated visitors to `/dashboard/*` redirect to `/login`.
+
+## Env additions
+
+See `.env.example.additions`.
+
+## API contracts
+
+```
+POST /api/auth/signup         (Better Auth handles)
+POST /api/auth/login          (Better Auth handles)
+POST /api/auth/logout         (Better Auth handles)
+GET  /api/auth/session        (Better Auth handles; returns user or 401)
+
+POST /api/billing/checkout    Body: { plan: 'solo' | 'team' }
+                              Response: { url } (Stripe Checkout URL)
+
+GET  /api/billing/portal      Response: { url } (Stripe Customer Portal URL)
+
+POST /api/webhooks/stripe     Handles subscription.created, .updated, .deleted
+                              Updates User.plan
+```
+
+## Hard rules
+
+- Auth gate runs at middleware level. Never serve dashboard UI to unauthenticated requests, even briefly.
+- Session cookies are httpOnly, secure in production, sameSite=lax.
+- Stripe webhook signature verification is mandatory. Reject on bad sig.
+- Empty dashboard state has a clear "Get started" path. No dead-end empty UI.
+- All errors during auth flow are user-facing (not stack traces).
+- Settings → Billing links to Stripe Customer Portal, not a custom billing UI v1.
+
+## Acceptance
+
+- New user can sign up, see empty dashboard, log out, log back in.
+- Stripe Checkout can be initiated; webhook updates user plan.
+- Visiting `/dashboard` unauthenticated redirects to `/login`.
+- Visiting `/login` while logged in redirects to `/dashboard`.
+- Lighthouse landing-page Performance >= 90; dashboard >= 80 (slightly lower acceptable due to auth code).

package/templates/profiles/saas-dashboard/section-prompts.md

@@ -0,0 +1,52 @@
+# SaaS dashboard profile section prompts
+
+Agent: build each section using the brief. Default auth library: Better Auth. Default DB: Postgres (Neon if no preference).
+
+## Landing hero (unauthenticated)
+
+- Single big claim: the change the product delivers (echo `project.summary`).
+- One CTA: "Start free" or "Get started" → routes to `/signup`.
+- Optional logo strip or "Used by" line if the brief mentions customers.
+
+## Pricing
+
+- 1-3 tiers from `business_model.pricing_notes`. If 1 tier: show it plus "Custom for teams >".
+- Monthly + annual toggle. Annual = 2 months free (standard pattern).
+- Each tier: name, price, 4-6 bullets, single CTA "Start free" or "Upgrade" depending on auth state.
+
+## Sign up / Log in
+
+- Two-tab UI on `/auth` OR separate `/signup` and `/login` routes.
+- Email + password v1.
+- Clear error states: "Email already in use", "Wrong password", "Too many attempts" (rate-limit).
+- After signup: email verification flow (Resend).
+- After login: redirect to `/dashboard`.
+
+## Dashboard shell
+
+- Sidebar nav (collapsible on mobile): Home, Settings, Billing, Logout.
+- Header bar: user email + dropdown.
+- Empty state: "Welcome to {{DISPLAY_NAME}}. Start by [first action from brief]."
+- One primary action button in the empty state.
+
+## Settings
+
+- Two sub-pages: Profile, Billing.
+- Profile: name, email (verified), change password.
+- Billing: link to Stripe Customer Portal via `/api/billing/portal`. Show current plan + next renewal date.
+
+## Billing
+
+- Stripe Checkout via `/api/billing/checkout`. Redirect on success to `/dashboard?welcome=1`.
+- Stripe Customer Portal for management.
+- Webhook updates `User.plan` field.
+
+## Footer
+
+- Privacy, Terms, Status, GitHub.
+- Year, copyright.
+- No SSO / SAML claims v1 unless brief says so explicitly.
+
+## Hard rule
+
+- Middleware-level auth gate. Use Next.js middleware to protect `/dashboard/*` and `/settings/*`. Unauthenticated requests redirect to `/login`. Authenticated requests to `/login` redirect to `/dashboard`.

package/templates/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Profile-aware verification gate. Runs the right checks for the project's profile.
+# Called after /update-image, /update-gui, /update-backend, or at any time the operator wants to verify.
+#
+# Usage:   scripts/verify.sh [profile] [deploy_url]
+# Reads:   docs/brief.json (for profile) if no profile arg
+# Defaults: profile=marketing, deploy_url from .vercel/project.json if available
+
+set -e
+
+PROFILE="${1:-}"
+DEPLOY_URL="${2:-}"
+
+# Auto-detect profile from brief.json if not given
+if [ -z "$PROFILE" ] && [ -f docs/brief.json ]; then
+  PROFILE=$(python3 -c "import json; print(json.load(open('docs/brief.json'))['scaffold']['profile'])" 2>/dev/null || echo "marketing")
+fi
+PROFILE="${PROFILE:-marketing}"
+
+# Auto-detect deploy URL if not given (best-effort; operator may need to pass it)
+if [ -z "$DEPLOY_URL" ]; then
+  if [ -f .vercel/project.json ]; then
+    PROJECT_NAME=$(python3 -c "import json; print(json.load(open('.vercel/project.json'))['projectName'])" 2>/dev/null || echo "")
+    if [ -n "$PROJECT_NAME" ]; then
+      DEPLOY_URL="https://${PROJECT_NAME}.vercel.app"
+    fi
+  fi
+fi
+
+echo "=========================================="
+echo "  Verifying profile: $PROFILE"
+echo "  Deploy URL: ${DEPLOY_URL:-<not detected; pass as arg 2>}"
+echo "=========================================="
+
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  local cmd="$2"
+  echo -n "  [$PROFILE] $desc ... "
+  if eval "$cmd" > /tmp/verify-out 2>&1; then
+    echo "PASS"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL"
+    echo "    Output: $(head -3 /tmp/verify-out)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# === Common checks (all profiles) ===
+echo ""
+echo "--- common ---"
+check "build succeeds" "npm run build"
+check ".env.example exists" "[ -f .env.example ]"
+check "no {{TOKEN}} placeholders in CLAUDE.md" "! grep -E '\\{\\{[A-Z_]+\\}\\}' CLAUDE.md || true"
+
+if [ -n "$DEPLOY_URL" ]; then
+  check "live URL returns 200" "curl -sI '$DEPLOY_URL' | head -1 | grep -E '200|301|302'"
+fi
+
+# === Profile-specific checks ===
+case "$PROFILE" in
+  lead-gen)
+    echo ""
+    echo "--- lead-gen ---"
+    check "/api/contact route exists" "[ -f src/app/api/contact/route.ts ] || [ -f src/app/api/contact/route.js ] || [ -f app/api/contact/route.ts ]"
+    check "JSON-LD LocalBusiness in HTML" "grep -r 'LocalBusiness' src/ 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "POST /api/contact returns 200 or 400" "curl -s -X POST '$DEPLOY_URL/api/contact' -H 'Content-Type: application/json' -d '{\"name\":\"verify\",\"email\":\"verify@example.com\",\"message\":\"verify\"}' -o /dev/null -w '%{http_code}' | grep -E '^(200|400)$'"
+    fi
+    ;;
+  booking)
+    echo ""
+    echo "--- booking ---"
+    check "booking API route exists" "find src/app/api/booking -type f 2>/dev/null | head -1 | grep -q ."
+    check "DATABASE_URL referenced in code or env" "grep -r 'DATABASE_URL' src/ .env.example 2>/dev/null | head -1"
+    ;;
+  saas-dashboard)
+    echo ""
+    echo "--- saas-dashboard ---"
+    check "auth middleware exists" "[ -f src/middleware.ts ] || [ -f src/middleware.js ] || [ -f middleware.ts ]"
+    check "/login or /signup page exists" "find src/app -type d \\( -name 'login' -o -name 'signup' -o -name 'auth' \\) 2>/dev/null | head -1 | grep -q ."
+    check "/dashboard page exists" "find src/app -type d -name 'dashboard' 2>/dev/null | head -1 | grep -q ."
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/dashboard redirects unauthenticated" "curl -s -o /dev/null -w '%{http_code}' '$DEPLOY_URL/dashboard' | grep -E '^(301|302|307|401)$'"
+    fi
+    ;;
+  blog)
+    echo ""
+    echo "--- blog ---"
+    check "content/posts/ exists" "[ -d content/posts ] || [ -d src/content/posts ]"
+    check "mdx package installed" "grep -q '@next/mdx\\|next-mdx-remote\\|@mdx-js' package.json 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/rss.xml returns 200" "curl -sI '$DEPLOY_URL/rss.xml' | head -1 | grep -q 200"
+      check "/sitemap.xml returns 200" "curl -sI '$DEPLOY_URL/sitemap.xml' | head -1 | grep -q 200"
+    fi
+    ;;
+  marketing|*)
+    echo ""
+    echo "--- marketing baseline ---"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "homepage has hero text" "curl -s '$DEPLOY_URL' | grep -iE '<h1' | head -1 | grep -q ."
+    fi
+    ;;
+esac
+
+# === Visual verification reminder ===
+echo ""
+echo "--- visual (per CLAUDE.md Part 19) ---"
+if [ -n "$DEPLOY_URL" ] && [ -x "scripts/screenshot.sh" ]; then
+  scripts/screenshot.sh "$DEPLOY_URL" /tmp/verify-screenshot.png 420,900 > /dev/null && \
+    echo "  Screenshot: /tmp/verify-screenshot.png (READ it to complete Part 19 verification)"
+else
+  echo "  Skipped (no deploy URL or no scripts/screenshot.sh)"
+fi
+
+# === Summary ===
+echo ""
+echo "=========================================="
+echo "  Verify summary: PASS=$PASS FAIL=$FAIL"
+echo "=========================================="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0