@oaklandzoo/ostup 0.9.1 → 0.10.0

package/README.md

@@ -17,6 +17,13 @@ When you run this tool, it will:
 6. Create an `inputs/` folder inside the project where you can drop any
    prior materials (research, reference repos, screenshots, brand
    assets) you want the agent to have on hand
+7. If you ran `ostup brief` first (recommended), drop in **working code
+   for your profile**. The four industry profiles ship real Next.js
+   overlays: lead-gen (hero + services + contact form + Resend wiring),
+   booking (booking form + dates + email confirmation), saas-dashboard
+   (Better Auth + guarded dashboard + settings), blog (MDX posts + RSS
+   + sitemap). Your first deploy shows a working homepage and day-one
+   flow, not a blank Next.js welcome.
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.9.1",
+  "version": "0.10.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/scripts/verify-profile.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# verify-profile.sh: apply a profile overlay to a fresh temp dir and assert key files exist.
+#
+# Usage: bash scripts/verify-profile.sh <profile-name>
+#   profile-name: one of lead-gen, booking, saas-dashboard, blog
+#
+# This script does NOT run `next build` (that requires installing many deps and a
+# full Next.js scaffold). It verifies that the overlay APPLIES correctly and the
+# expected files land in the target directory. Full next-build verification is
+# the operator's job after `ostup init --brief`.
+
+set -euo pipefail
+
+PROFILE="${1:-}"
+if [[ -z "$PROFILE" ]]; then
+  echo "usage: $0 <profile-name>" >&2
+  echo "  profile-name: lead-gen | booking | saas-dashboard | blog" >&2
+  exit 2
+fi
+
+case "$PROFILE" in
+  lead-gen|booking|saas-dashboard|blog)
+    ;;
+  *)
+    echo "error: unknown profile '$PROFILE'. expected one of: lead-gen, booking, saas-dashboard, blog" >&2
+    exit 2
+    ;;
+esac
+
+OSTUP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_FILE="$OSTUP_ROOT/test/profile-$(echo "$PROFILE" | tr -d -)-overlay.test.mjs"
+
+# Map profile names to test file names: lead-gen -> profile-leadgen-overlay.test.mjs
+case "$PROFILE" in
+  lead-gen)        TEST_FILE="$OSTUP_ROOT/test/profile-leadgen-overlay.test.mjs" ;;
+  booking)         TEST_FILE="$OSTUP_ROOT/test/profile-booking-overlay.test.mjs" ;;
+  saas-dashboard)  TEST_FILE="$OSTUP_ROOT/test/profile-saas-overlay.test.mjs" ;;
+  blog)            TEST_FILE="$OSTUP_ROOT/test/profile-blog-overlay.test.mjs" ;;
+esac
+
+echo ">> verifying profile: $PROFILE"
+echo ">> running: node --test $TEST_FILE"
+cd "$OSTUP_ROOT"
+node --test "$TEST_FILE"
+
+echo ">> ok: $PROFILE overlay applies and asserts pass"

package/src/brief/profile-router.mjs

@@ -9,18 +9,11 @@ import { substitute } from '../substitute.mjs';
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
 
-/**
- * Returns the absolute path to the profile's template overlay folder.
- * Returns null if the profile has no overlay (yet).
- */
 export function profileTemplatePath(profile) {
   const p = resolve(TEMPLATES_ROOT, 'profiles', profile);
   return existsSync(p) ? p : null;
 }
 
-/**
- * Recursively list every file in a directory, returning relative paths.
- */
 async function listFiles(dir, base = dir, out = []) {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -34,19 +27,51 @@ async function listFiles(dir, base = dir, out = []) {
   return out;
 }
 
-/**
- * Apply a profile overlay to the target directory.
- * - Reads every file in templates/profiles/<profile>/
- * - Substitutes tokens
- * - Writes to <targetDir>/<relative-path>
- *
- * Skip rules:
- *   - .DS_Store
- *   - any path containing /node_modules/
- *
- * Files with name suffix `.additions` are appended to the existing file at the
- * destination (used for .env.example.additions). All others are written.
- */
+function mergeJsonObjects(target, source) {
+  const out = { ...target };
+  for (const key of Object.keys(source)) {
+    const sv = source[key];
+    const tv = out[key];
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      out[key] = { ...tv, ...sv };
+    } else {
+      out[key] = sv;
+    }
+  }
+  return out;
+}
+
+export async function mergePackageJsonAdditions(destPath, additionsText) {
+  let additions;
+  try {
+    additions = JSON.parse(additionsText);
+  } catch (err) {
+    throw new Error(`Invalid JSON in package.json.additions: ${err.message}`);
+  }
+  let existing = {};
+  if (existsSync(destPath)) {
+    const raw = await readFile(destPath, 'utf8');
+    try {
+      existing = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Invalid JSON in target package.json at ${destPath}: ${err.message}`);
+    }
+  }
+  const merged = mergeJsonObjects(existing, additions);
+  await writeFile(destPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+
+export async function mergeNextConfigAdditions(destPath, additionsText) {
+  const marker = '--- added by ostup profile overlay ---';
+  if (existsSync(destPath)) {
+    const existing = await readFile(destPath, 'utf8');
+    if (existing.includes(marker)) return;
+    await writeFile(destPath, existing + `\n// ${marker}\n` + additionsText, 'utf8');
+  } else {
+    await writeFile(destPath, `// next.config.mjs (created by ostup profile overlay)\n` + additionsText, 'utf8');
+  }
+}
+
 export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun = false } = {}) {
   const overlayPath = profileTemplatePath(profile);
   if (!overlayPath) {
@@ -59,12 +84,19 @@ export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun =
   const actions = [];
   for (const rel of filtered) {
     const src = join(overlayPath, rel);
-    const isAddition = rel.endsWith('.additions');
-    const dest = isAddition
-      ? join(targetDir, rel.replace(/\.additions$/, ''))
-      : join(targetDir, rel);
-
-    actions.push({ rel, src, dest, isAddition });
+    let kind = 'copy';
+    let dest = join(targetDir, rel);
+    if (rel.endsWith('package.json.additions')) {
+      kind = 'package-merge';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    } else if (rel.endsWith('next.config.mjs.additions')) {
+      kind = 'next-config-merge';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    } else if (rel.endsWith('.additions')) {
+      kind = 'append';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    }
+    actions.push({ rel, src, dest, kind });
   }
 
   if (dryRun) {
@@ -75,9 +107,12 @@ export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun =
     const raw = await readFile(a.src, 'utf8');
     const out = substitute(raw, tokens);
     await mkdir(dirname(a.dest), { recursive: true });
-    if (a.isAddition && existsSync(a.dest)) {
+    if (a.kind === 'package-merge') {
+      await mergePackageJsonAdditions(a.dest, out);
+    } else if (a.kind === 'next-config-merge') {
+      await mergeNextConfigAdditions(a.dest, out);
+    } else if (a.kind === 'append' && existsSync(a.dest)) {
       const existing = await readFile(a.dest, 'utf8');
-      // Append with a separator if not already present
       const sep = existing.endsWith('\n') ? '' : '\n';
       await writeFile(a.dest, existing + sep + '\n# --- added by ostup profile overlay ---\n' + out, 'utf8');
     } else {

package/templates/START_HERE.md

@@ -41,7 +41,7 @@ That is the whole jump-in. The agent reads, asks, proposes, you approve, it buil
 | `docs/brief.md` | Operator brief (only if you scaffolded with `ostup brief`). Source of truth for scope, brand, constraints. | Both |
 | `docs/brief.json` | Machine-readable brief (same trigger). Used by downstream commands. | Agent |
 | `tasks/prd-initial-build.md` | Auto-seeded first PRD from the brief (same trigger). | Both |
-| `templates/profiles/<profile>/` | (if applicable) Profile-specific guidance the agent reads on day one. | Agent |
+| Profile overlay files at the project root (`app/page.tsx`, `app/api/*`, `components/*`, `lib/*`, plus `README.md` + `section-prompts.md`) | (if you ran `ostup brief`) Working code for your profile: hero, day-one flow, API routes. Agent extends from here instead of building from scratch. | Both |
 | `.claude/commands/` | Slash command definitions. | Agent |
 
 ## Slash commands

package/templates/profiles/blog/README.md

@@ -1,32 +1,38 @@
 # Profile: blog
 
-> Content engine. MDX posts, RSS, sitemap, tag/author pages. SEO-first. No CMS v1.
+> Content engine. MDX posts, RSS, sitemap. SEO-first. No CMS v1.
+
+## What this profile ships (v1)
+
+The overlay drops a working blog into your new project. After `vercel --prod` you have:
+
+- A homepage at `/` listing all posts in `content/posts/`.
+- Individual post pages at `/posts/[slug]` rendering MDX via `next-mdx-remote`.
+- `/feed.xml` (RSS 2.0) and `/sitemap.xml`.
+- Three starter posts in `content/posts/*.mdx` with frontmatter (title, date, summary, author).
+- `Article` + `Organization` JSON-LD schema injected per post page.
+
+## Pro upgrades (not shipped in v1)
+
+- Tag index / tag pages.
+- Author pages (multi-author).
+- Newsletter integration.
+- Editorial dashboard.
+- Image optimization for inline post images.
 
 ## Day-one scope
 
 | Section | Purpose | Required |
 |---|---|---|
-| Homepage | Latest 6-10 posts, intro paragraph | yes |
+| Homepage | Latest posts sorted desc by date | 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 |
+| RSS feed | `/feed.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.
+| Starter content | 3 MDX posts in `content/posts/` | yes |
 
 ## Env additions
 
-See `.env.example.additions` (mostly empty for blog v1).
+See `.env.example.additions`. The blog needs `NEXT_PUBLIC_APP_URL` for absolute URLs in RSS + sitemap.
 
 ## File contracts
 
@@ -34,37 +40,36 @@ See `.env.example.additions` (mostly empty for blog v1).
 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."
+  summary: "One-sentence summary for SEO."
+  author: "Author name"
   ---
-  
-  Body in MDX.
 
-content/authors/<author>.mdx (optional)
-  ---
-  name: "GG"
-  bio: "One-paragraph bio."
-  social: { x: "@goodshin", github: "DubsFan" }
-  ---
+  Body in MDX.
 ```
 
 ## 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`.
+- RSS + sitemap regenerate at build time (statically rendered).
+- Reading width capped around 720px for body comfort.
+- Light theme by default. Dark mode is operator-add.
 
 ## 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).
+- Homepage shows all posts sorted by date desc.
+- Individual post page renders MDX.
+- `/feed.xml` validates at https://validator.w3.org/feed/.
+- `/sitemap.xml` includes every post.
+- Lighthouse Performance >= 95 (static content).
+
+## Visual verification
+
+After deploy, run:
+
+```bash
+bash scripts/screenshot.sh <your-vercel-url>
+bash scripts/screenshot.sh <your-vercel-url>/posts/welcome
+```
+
+Read the resulting PNGs to confirm the post list and an individual post render as expected.

package/templates/profiles/blog/app/feed.xml/route.ts

@@ -0,0 +1,41 @@
+import { getAllPosts } from '@/lib/posts';
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+export async function GET() {
+  const siteUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000';
+  const posts = await getAllPosts();
+  const items = posts
+    .map(
+      (p) => `
+    <item>
+      <title>${escapeXml(p.title)}</title>
+      <link>${siteUrl}/posts/${p.slug}</link>
+      <guid>${siteUrl}/posts/${p.slug}</guid>
+      <pubDate>${new Date(p.date).toUTCString()}</pubDate>
+      <description>${escapeXml(p.summary)}</description>
+    </item>`,
+    )
+    .join('');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>{{DISPLAY_NAME}}</title>
+    <link>${siteUrl}</link>
+    <description>{{PROJECT_PURPOSE_ONE_SENTENCE}}</description>
+    <language>en</language>${items}
+  </channel>
+</rss>`;
+
+  return new Response(xml, {
+    headers: { 'content-type': 'application/xml; charset=utf-8' },
+  });
+}

package/templates/profiles/blog/app/page.tsx

@@ -0,0 +1,30 @@
+import Link from 'next/link';
+import { getAllPosts } from '@/lib/posts';
+
+export default async function HomePage() {
+  const posts = await getAllPosts();
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-16">
+      <header className="border-b border-slate-200 pb-8">
+        <h1 className="text-4xl font-bold tracking-tight">{`{{DISPLAY_NAME}}`}</h1>
+        <p className="mt-2 text-lg text-slate-600">{`{{PROJECT_PURPOSE_ONE_SENTENCE}}`}</p>
+      </header>
+      <ul className="mt-10 space-y-10">
+        {posts.map((post) => (
+          <li key={post.slug}>
+            <article>
+              <Link href={`/posts/${post.slug}`}>
+                <h2 className="text-2xl font-semibold tracking-tight hover:underline">{post.title}</h2>
+              </Link>
+              <p className="mt-1 text-sm text-slate-500">
+                {new Date(post.date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}
+              </p>
+              <p className="mt-3 text-slate-700">{post.summary}</p>
+            </article>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/templates/profiles/blog/app/posts/[slug]/page.tsx

@@ -0,0 +1,51 @@
+import { notFound } from 'next/navigation';
+import { MDXRemote } from 'next-mdx-remote/rsc';
+import { getAllPosts, getPostBySlug } from '@/lib/posts';
+
+export async function generateStaticParams() {
+  const posts = await getAllPosts();
+  return posts.map((p) => ({ slug: p.slug }));
+}
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await getPostBySlug(slug);
+  if (!post) notFound();
+
+  const siteUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000';
+
+  const articleSchema = {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: post.title,
+    description: post.summary,
+    datePublished: post.date,
+    author: { '@type': 'Person', name: post.author },
+    publisher: {
+      '@type': 'Organization',
+      name: '{{DISPLAY_NAME}}',
+      url: siteUrl,
+    },
+  };
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-16">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(articleSchema) }}
+      />
+      <article>
+        <header className="border-b border-slate-200 pb-6">
+          <h1 className="text-4xl font-bold tracking-tight">{post.title}</h1>
+          <p className="mt-2 text-sm text-slate-500">
+            {new Date(post.date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}
+            {post.author ? ` - ${post.author}` : ''}
+          </p>
+        </header>
+        <div className="prose prose-slate mt-8 max-w-none">
+          <MDXRemote source={post.body} />
+        </div>
+      </article>
+    </main>
+  );
+}

package/templates/profiles/blog/app/sitemap.xml/route.ts

@@ -0,0 +1,21 @@
+import { getAllPosts } from '@/lib/posts';
+
+export async function GET() {
+  const siteUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000';
+  const posts = await getAllPosts();
+
+  const urls = [
+    `<url><loc>${siteUrl}</loc><changefreq>weekly</changefreq></url>`,
+    ...posts.map(
+      (p) =>
+        `<url><loc>${siteUrl}/posts/${p.slug}</loc><lastmod>${new Date(p.date).toISOString()}</lastmod></url>`,
+    ),
+  ].join('');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}</urlset>`;
+
+  return new Response(xml, {
+    headers: { 'content-type': 'application/xml; charset=utf-8' },
+  });
+}

package/templates/profiles/blog/content/posts/getting-started.mdx

@@ -0,0 +1,16 @@
+---
+title: Getting started, the boring version
+date: 2026-05-21
+summary: A simple checklist anyone can use to start something new without overthinking it.
+author: {{OWNER_OR_CLIENT}}
+---
+
+Most "getting started" guides are aspirational. This one is boring on purpose.
+
+1. Decide one outcome that would count as done.
+2. Block thirty minutes on the calendar this week.
+3. Write the smallest thing that moves you toward the outcome.
+4. Tell one person what you did.
+5. Repeat next week.
+
+That is the whole list. The trick is not finding a better list. The trick is doing the list when you do not feel like it.

package/templates/profiles/blog/content/posts/intro.mdx

@@ -0,0 +1,14 @@
+---
+title: What this blog covers
+date: 2026-05-22
+summary: The topics I plan to write about and why they matter.
+author: {{OWNER_OR_CLIENT}}
+---
+
+A few things I plan to write about here:
+
+- The work behind the work. Not the highlight reel, the actual decisions.
+- Small lessons that compound. The kind of thing you wish someone had told you a year ago.
+- Reading notes, recommendations, and the occasional review.
+
+I would rather publish ten honest posts than one perfect one, so expect mistakes. I will correct them in public when I find them.

package/templates/profiles/blog/content/posts/welcome.mdx

@@ -0,0 +1,12 @@
+---
+title: Welcome to {{DISPLAY_NAME}}
+date: 2026-05-23
+summary: A short note on why this blog exists and what to expect.
+author: {{OWNER_OR_CLIENT}}
+---
+
+Welcome. This is the first post on {{DISPLAY_NAME}}.
+
+I started this site to share what I learn and to give readers a single place to follow along. New posts will appear here regularly.
+
+If you have a question or a suggestion, the contact link in the footer is the best way to reach me.

package/templates/profiles/blog/lib/posts.ts

@@ -0,0 +1,43 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+
+const POSTS_DIR = join(process.cwd(), 'content', 'posts');
+
+export type Post = {
+  slug: string;
+  title: string;
+  date: string;
+  summary: string;
+  author: string;
+  body: string;
+};
+
+async function readPostFile(filename: string): Promise<Post | null> {
+  if (!filename.endsWith('.mdx')) return null;
+  const slug = filename.replace(/\.mdx$/, '');
+  const raw = await readFile(join(POSTS_DIR, filename), 'utf8');
+  const { data, content } = matter(raw);
+  return {
+    slug,
+    title: String(data.title || slug),
+    date: String(data.date || new Date().toISOString()),
+    summary: String(data.summary || ''),
+    author: String(data.author || ''),
+    body: content,
+  };
+}
+
+export async function getAllPosts(): Promise<Post[]> {
+  if (!existsSync(POSTS_DIR)) return [];
+  const files = await readdir(POSTS_DIR);
+  const posts = (await Promise.all(files.map(readPostFile))).filter((p): p is Post => p !== null);
+  return posts.sort((a, b) => (a.date < b.date ? 1 : -1));
+}
+
+export async function getPostBySlug(slug: string): Promise<Post | null> {
+  const filename = `${slug}.mdx`;
+  if (!existsSync(join(POSTS_DIR, filename))) return null;
+  return readPostFile(filename);
+}

package/templates/profiles/blog/next.config.mjs.additions

@@ -0,0 +1,9 @@
+// MDX is handled at runtime via next-mdx-remote (see app/posts/[slug]/page.tsx).
+// No next.config.mjs changes are required for the v1 blog overlay.
+//
+// If you later switch to compile-time MDX (@next/mdx) you will need to:
+//   1. npm install @next/mdx @mdx-js/loader @mdx-js/react
+//   2. Wrap your next.config.mjs export with createMDX({})
+//   3. Add "mdx" to pageExtensions
+//
+// This file is shipped as a placeholder so the convention is visible.

package/templates/profiles/blog/package.json.additions

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "next-mdx-remote": "^5.0.0",
+    "gray-matter": "^4.0.3"
+  }
+}

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

@@ -1,16 +1,8 @@
 # --- booking profile additions ---
-# Database for Booking entity (Neon recommended; any Postgres works)
-DATABASE_URL=
-
-# Email confirmation
+# Email confirmation (guest + admin) via Resend
 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=
+RESEND_FROM_EMAIL=noreply@example.com
+ADMIN_EMAIL=
 
 # Public app URL (Vercel sets this for production)
 NEXT_PUBLIC_APP_URL=http://localhost:3000