@oaklandzoo/ostup 0.3.0 → 0.4.0

package/templates/profiles/blog/README.md

@@ -0,0 +1,70 @@
+# Profile: blog
+
+> Content engine. MDX posts, RSS, sitemap, tag/author pages. SEO-first. No CMS v1.
+
+## Day-one scope
+
+| Section | Purpose | Required |
+|---|---|---|
+| Homepage | Latest 6-10 posts, intro paragraph | yes |
+| Post page | Single post by slug, MDX-rendered | yes |
+| Tag index | List of all tags with post counts | yes |
+| Tag page | All posts under a tag | yes |
+| Author page (if multi-author) | Author bio + their posts | conditional |
+| RSS feed | `/rss.xml` valid RSS 2.0 | yes |
+| Sitemap | `/sitemap.xml` valid sitemap | yes |
+| About | Static about page | yes |
+| Footer | Links, RSS, year | yes |
+
+## Wired infrastructure
+
+- **MDX** for post bodies. Posts live as `.mdx` files in `content/posts/`.
+- Frontmatter schema: `title`, `slug`, `date`, `tags[]`, `author?`, `description?`, `draft?`.
+- `next-mdx-remote` or `@next/mdx` (agent picks; both work).
+- Open Graph + Twitter card metadata per post.
+- Article + Organization JSON-LD schema.
+
+## Env additions
+
+See `.env.example.additions` (mostly empty for blog v1).
+
+## File contracts
+
+```
+content/posts/<slug>.mdx
+  ---
+  title: "Post title"
+  slug: "post-slug"
+  date: "2026-05-21"
+  tags: ["agents", "tooling"]
+  author: "GG"
+  description: "One-sentence summary for SEO."
+  ---
+  
+  Body in MDX.
+
+content/authors/<author>.mdx (optional)
+  ---
+  name: "GG"
+  bio: "One-paragraph bio."
+  social: { x: "@goodshin", github: "DubsFan" }
+  ---
+```
+
+## Hard rules
+
+- Posts ship as committed MDX files. No DB v1.
+- `draft: true` excludes from production builds AND from RSS/sitemap.
+- RSS / sitemap regenerate on build.
+- Code blocks use one syntax highlighter (Shiki recommended). Pick at build time, not client-side.
+- Reading width capped at 720px or so for body comfort.
+- Light + dark mode via `prefers-color-scheme`.
+
+## Acceptance
+
+- Homepage shows latest 6 posts sorted by date desc.
+- Individual post page renders MDX with syntax-highlighted code.
+- RSS feed validates at https://validator.w3.org/feed/.
+- Sitemap includes every published post (no drafts).
+- Tag pages reachable from each post's tag list.
+- Lighthouse Performance >= 95 (static content, should be fast).

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

@@ -0,0 +1,63 @@
+# Blog profile section prompts
+
+Agent: build each section using the brief. Default MDX library: `next-mdx-remote`. Use `gray-matter` for frontmatter parsing.
+
+## Homepage
+
+- Title + tagline from the brief.
+- Latest 6 posts: title (clickable), date, 1-2-sentence excerpt from `description` or first 160 chars of body.
+- "All posts" link to a chronological archive (optional v1).
+- Tag cloud or top 5 tags if there are 3+ tagged posts.
+
+## Post page (`/posts/[slug]`)
+
+- Title (h1), date, tags (clickable to tag pages), author (if multi-author).
+- MDX-rendered body.
+- Code blocks: syntax-highlighted with Shiki. Light + dark theme.
+- Body width capped (~65ch).
+- Reading time estimate (optional).
+- Open Graph: title, description, type=article, published_time, author.
+
+## Tag index (`/tags`)
+
+- All tags from all published posts, sorted by post count desc.
+- Each tag: name + post count + link.
+
+## Tag page (`/tags/[tag]`)
+
+- All posts under that tag, chronological desc.
+- Same card format as homepage list.
+
+## Author page (`/authors/[author]`) — only if multi-author
+
+- Author bio from `content/authors/<author>.mdx`.
+- All posts by that author.
+
+## RSS feed (`/rss.xml`)
+
+- RSS 2.0.
+- Include title, link, description, pubDate, category for each post.
+- Published posts only (`draft: false`).
+- Validate the output structure manually before claiming done.
+
+## Sitemap (`/sitemap.xml`)
+
+- All published posts + tag pages + author pages + homepage + about.
+- `<lastmod>` on each entry.
+- No drafts.
+
+## About
+
+- Pulled from the brief: who runs the site, what it covers, contact.
+- Single page. Plain text + maybe a portrait from `inputs/images/`.
+
+## Footer
+
+- RSS link with feed icon.
+- GitHub link (if applicable).
+- Year + copyright.
+
+## First post
+
+- If the brief mentions a launch announcement, write `content/posts/hello-world.mdx` as a placeholder with the project summary.
+- Otherwise leave `content/posts/` with a `.gitkeep` only and let the operator write the first post.

package/templates/profiles/booking/.env.example.additions

@@ -0,0 +1,16 @@
+# --- booking profile additions ---
+# Database for Booking entity (Neon recommended; any Postgres works)
+DATABASE_URL=
+
+# Email confirmation
+RESEND_API_KEY=
+BOOKING_TO_EMAIL=
+BOOKING_FROM_EMAIL=noreply@example.com
+
+# Optional: Stripe deposit checkout (enable only if `payments` addon is on)
+STRIPE_SECRET_KEY=
+STRIPE_PUBLISHABLE_KEY=
+STRIPE_WEBHOOK_SECRET=
+
+# Public app URL (Vercel sets this for production)
+NEXT_PUBLIC_APP_URL=http://localhost:3000

package/templates/profiles/booking/README.md

@@ -0,0 +1,61 @@
+# Profile: booking
+
+> Appointment / reservation site. Availability request, booking form, optional Stripe deposit, email confirmations.
+
+## Day-one scope
+
+| Section | Purpose | Required |
+|---|---|---|
+| Hero | Single value statement + "Check availability" or "Book now" CTA | yes |
+| Availability / Booking form | Date range or appointment slot picker + guest info | yes |
+| Rooms / Services | List of bookable units with descriptions and rates | yes |
+| Deposit checkout | Stripe Checkout for the deposit if `payments` addon is on | conditional |
+| Confirmation email | Auto-send on submission to both guest and admin | yes |
+| About / Amenities | Trust-building content from the brief | yes |
+| Footer | Contact, cancellation policy summary | yes |
+
+## Wired infrastructure
+
+- **Postgres** for the `Booking` entity (date_start, date_end, guest info, status, deposit_status).
+- **Resend** for guest + admin confirmation emails.
+- **Stripe Checkout** for deposit (only if `payments` addon is on per the brief).
+- Mobile-first calendar / date picker.
+
+## Env additions
+
+See `.env.example.additions`.
+
+## API contracts
+
+```
+POST /api/booking/request
+Body: { name, email, phone?, date_start, date_end, room_or_service?, notes? }
+Response: { ok, booking_id }
+Behavior: insert Booking with status='pending', email both parties.
+
+POST /api/booking/deposit
+Body: { booking_id }
+Response: { ok, checkout_url }
+Behavior: create Stripe Checkout session, return URL.
+
+POST /api/webhooks/stripe
+Behavior: on payment_intent.succeeded, mark booking deposit_status='paid'.
+```
+
+## Hard rules
+
+- Date pickers MUST be mobile-friendly (no tiny native date inputs without testing).
+- Server-side validate the date range (no past dates, no end-before-start).
+- Confirmation emails go out immediately on form submit, even before deposit.
+- Deposit is OPTIONAL: if `payments` addon is off, skip Stripe entirely. Booking still goes through.
+- Calendar availability check should be server-side; do not trust client.
+- If `Booking.status` is 'pending' for >48h with no deposit, mark as 'expired'.
+
+## Acceptance
+
+- Visitor can request dates and submit.
+- Both visitor and admin receive emails within 30 seconds.
+- Deposit Checkout opens if enabled, completes round-trip to the booking record.
+- Past dates rejected with clear error.
+- Hero CTA above the fold at 420x900.
+- Lighthouse mobile Performance >= 85 (acceptable lower than marketing because of date picker JS).

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

@@ -0,0 +1,47 @@
+# Booking profile section prompts
+
+Agent: build each section using the brief in `docs/brief.md`. Honor `must_avoid` strictly.
+
+## Hero
+
+- Headline (5-9 words) about the experience being booked.
+- Subhead: one sentence on what the visitor gets when they book.
+- Primary CTA: "Check availability" or "Book now" — opens the booking form modal or scrolls to it.
+
+## Availability / Booking form
+
+- Date range picker (or single-date for appointments). Mobile-friendly is mandatory.
+- Guest info: name, email, phone, party size (if relevant), notes.
+- Validate server-side: no past dates, end after start, party size within room limits.
+- Loading state on submit. Success state with booking ID. Error state with clear message.
+
+## Rooms / Services
+
+- Pull entity list from the brief's `data_model.entities`. If a Room entity exists, list its fields visually.
+- Each unit: name, description (short), rate per night/hour, photo placeholder if `inputs/images/` has anything matching.
+- "Book this" CTA scrolls back to the booking form with the room pre-selected.
+
+## Deposit checkout (conditional)
+
+- Only render if `payments` addon is in the brief.
+- After successful booking submission, present a "Pay deposit to confirm" CTA.
+- Clicking opens Stripe Checkout via `/api/booking/deposit`.
+- On Checkout success, return to a `/booking/[id]/confirmed` page.
+- Webhook `/api/webhooks/stripe` updates `deposit_status='paid'`.
+
+## Confirmation emails
+
+- Guest receives: "Your booking request is in. We'll confirm within X hours. Booking ID: ABC123."
+- Admin receives: full booking details + a link to the admin route (TBD v2).
+- Use Resend. Plain text + HTML versions.
+
+## About / Amenities
+
+- Pull from the brief's `must_have_sections`. Echo the brief's vibe.
+- Photos from `inputs/images/` if any. Otherwise text-only placeholders.
+
+## Footer
+
+- Cancellation policy summary (1-2 sentences from the brief or a placeholder asking the operator).
+- Contact email + phone.
+- Year + copyright.

package/templates/profiles/lead-gen/.env.example.additions

@@ -0,0 +1,8 @@
+# --- lead-gen profile additions ---
+# Email notifications for contact-form submissions
+RESEND_API_KEY=
+CONTACT_TO_EMAIL=
+CONTACT_FROM_EMAIL=noreply@example.com
+
+# Optional: forward lead payloads to a CRM as JSON
+CRM_WEBHOOK_URL=

package/templates/profiles/lead-gen/README.md

@@ -0,0 +1,58 @@
+# Profile: lead-gen
+
+> Service-company site that captures contact requests. Resend for email, optional CRM webhook, local SEO basics.
+
+## Day-one scope
+
+| Section | Purpose | Required |
+|---|---|---|
+| Hero | Single value statement + primary CTA "Request a quote" or "Contact us" | yes |
+| Services | 3-8 service cards or list. Tap-to-call on mobile. | yes |
+| Service area | Map placeholder OR text list of cities / zip codes covered | yes |
+| Testimonials | 2-4 quotes (placeholders OK if brief has none) | yes |
+| FAQ | 4-8 questions, accordion or stacked | yes |
+| Contact form | Name, phone, email, message. Posts to /api/contact. | yes |
+| Footer | Phone, email, license number if applicable, year | yes |
+
+## Wired infrastructure
+
+- **Resend** for email notifications when a lead submits the form.
+- Optional **CRM webhook** (env: `CRM_WEBHOOK_URL`). If set, also POST the lead payload as JSON.
+- **JSON-LD LocalBusiness schema** in the head of every page.
+- Open Graph + Twitter metadata using `{{DISPLAY_NAME}}` and the brand summary.
+
+## Env additions
+
+See `.env.example.additions` for the variables this profile expects.
+
+## API contract for /api/contact
+
+```
+POST /api/contact
+Content-Type: application/json
+Body: { name: string, email: string, phone?: string, message: string }
+Response: { ok: boolean, id?: string }
+```
+
+The route:
+1. Validates required fields (name, email, message).
+2. Sends an email via Resend to `CONTACT_TO_EMAIL` from `CONTACT_FROM_EMAIL`.
+3. If `CRM_WEBHOOK_URL` is set, POSTs the lead payload there.
+4. Returns 200 with `{ ok: true }` on success; 400 on validation; 500 on send failure.
+
+No persistent storage v1. Leads live in the operator's email inbox.
+
+## Hard rules
+
+- Phone number on every page (mobile sticky CTA acceptable).
+- Service area is explicit. Do not claim to cover areas the brief does not mention.
+- No JS-heavy carousels. Stacked content reads better on phones.
+- Honor `constraints.must_avoid` strictly.
+
+## Acceptance
+
+- Visitor can submit the contact form, sees an inline success state.
+- Owner receives the lead by email at the address in `CONTACT_TO_EMAIL`.
+- JSON-LD LocalBusiness schema validates at https://search.google.com/test/rich-results.
+- Hero CTA above the fold at 420x900.
+- Lighthouse mobile Performance >= 90, Accessibility >= 95.

package/templates/profiles/lead-gen/section-prompts.md

@@ -0,0 +1,47 @@
+# Lead-gen profile section prompts
+
+Agent: build each section using the brief in `docs/brief.md`. Do not invent service offerings, prices, or testimonials.
+
+## Hero
+
+- Headline: 5-9 words. Echo the project summary in the operator's voice.
+- Subhead: one sentence on who it serves and what they get.
+- Primary CTA: "Request a quote" or "Contact us today" (use the brief's wording if it specifies).
+- Secondary trust signal: years in business, license number, or service area at a glance (only if in brief).
+
+## Services
+
+- List 3-8 services from the brief's `scope.must_have_sections` (filter out non-service sections like hero/footer/contact).
+- Each service card: short title + one or two sentences + (if available from brief) a starting-price hint.
+- Tap-to-call phone link visible on mobile.
+
+## Service area
+
+- If the brief mentions specific cities, towns, or zip codes, list them.
+- If only a general area, use that phrasing exactly.
+- If no specific area info: ask the operator to fill in `docs/brief.md` before building this section. Do NOT default to "nationwide."
+
+## Testimonials
+
+- 2-4 short quotes. If the brief has actual quotes, use them.
+- If none: use clear placeholders like `[Testimonial pending — operator to add]` and DO NOT fabricate.
+
+## FAQ
+
+- 4-8 questions tied to the services from the brief.
+- Suggested defaults: "How fast can you get here?", "Do you provide free estimates?", "Are you licensed and insured?", "Do you offer financing?". Match to the brief's business model.
+- Use an accordion or stacked Q/A. No JS framework needed.
+
+## Contact form
+
+- Fields: name (required), email (required), phone (optional), message (required).
+- POSTs to `/api/contact`.
+- Inline success message on submit: "Got it. We will be in touch within one business day."
+- On error: inline message with retry, never alert dialogs.
+- Form labels visible, not just placeholders (accessibility).
+
+## Footer
+
+- Phone, email, address (if relevant), license number (if relevant).
+- Current year, copyright.
+- Privacy / Terms links if the operator has them (otherwise omit; do not invent legalese).

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`.