@oaklandzoo/ostup 0.9.1 → 0.11.0

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

@@ -62,7 +62,17 @@ Confirm `.env.local` got the new keys. Common ones:
 npm install @vercel/<type>
 ```
 
-Create `src/lib/<type>.ts` with typed helpers. Example for blob:
+### Privacy mode check (before writing blob helpers)
+
+Before writing `src/lib/blob.ts`, check whether this project is in privacy mode by looking for `.ostup/private.json` at the project root OR a `# PART 20: PRIVACY DEFAULT-DENY` section in `CLAUDE.md`. If either is present:
+
+- Default the helper to `access: 'private'` (not `'public'`).
+- Also scaffold `app/api/blob/[...path]/route.ts` as the auth-checked proxy if it does not already exist (the `--private` applier may have already created it). Do NOT serve blob URLs directly to the client.
+- Skip the `vercel blob create-store --access public` flag from Step 3. Re-create the store without `--access public` if it was already created public.
+
+### Blob helper template
+
+Default (no privacy mode):
 
 ```typescript
 // src/lib/blob.ts
@@ -81,6 +91,26 @@ export async function deleteFile(url: string) {
 }
 ```
 
+Privacy mode:
+
+```typescript
+// src/lib/blob.ts
+import { put, list, del } from '@vercel/blob';
+
+export async function uploadFile(path: string, body: Blob | ArrayBuffer | string) {
+  // access: 'private' is mandatory in privacy mode. Serve via /api/blob/[...path] proxy.
+  return put(path, body, { access: 'private' as 'private' });
+}
+
+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

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/private/CLAUDE_PART_20.md

@@ -0,0 +1,30 @@
+
+---
+
+# PART 20: PRIVACY DEFAULT-DENY (--private mode)
+
+This project was scaffolded with `--private` (or `ostup private add` was later run on it). Default-deny is mandatory. Treat the rules below as hard rules per Part 3.
+
+## Hard rules
+
+1. **Do NOT widen the middleware matcher.** The `middleware.ts` matcher at the project root is intentionally strict. Adding paths to its exclusion list ungates them across the entire app. Any change MUST be reviewed for whether it accidentally exposes user content.
+
+2. **All `@vercel/blob` helpers default to `access: 'private'`.** Generated `src/lib/blob.ts` and any blob helper code uses `access: 'private'`. To serve a blob to authenticated users, route it through `app/api/blob/[...path]/route.ts` (the auth-checked proxy). Never set `access: 'public'` unless the file is truly safe to expose to the open internet.
+
+3. **Do NOT change `next.config.ts` -> `images.remotePatterns`.** It is intentionally empty (`[]`). Adding blob hosts would let `/_next/image?url=<blob-url>` proxy private blobs around auth.
+
+4. **`/_next/image` is auth-gated.** The matcher deliberately does NOT exclude `/_next/image`. This blocks public abuse of the image optimizer for any URL the matcher does not already allow.
+
+5. **Rate limiting is wired in middleware.** Default: `/api/*` 60 req/min/IP, everything else 600 req/min/IP. Adjust `src/lib/rate-limit.ts` constants. Removing the rate-limit call from middleware requires explicit operator review.
+
+6. **Audit log every blocked request.** Every 401/429 goes through `src/lib/audit.ts` -> `console.log` -> Vercel Logs. Do not silence the audit logger.
+
+7. **The audit-health endpoint at `/api/audit/health` is the only intentionally public route in privacy mode.** It confirms the audit pipeline is wired. Used by `ostup doctor --privacy` to verify the deploy.
+
+## Verification
+
+Run `ostup doctor --privacy <deployed-url>` after every deploy. It probes a list of suspicious paths without cookies and asserts they return 401 or 404. Any 200 is a privacy regression.
+
+## To undo
+
+If privacy mode is no longer needed, run `ostup private remove` from the project root. The applier captured original file contents in `.ostup/private.json`; remove will restore them.

package/templates/private/api-audit-health.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  return NextResponse.json({
+    ok: true,
+    pipeline: 'wired',
+    privacy: '--private',
+  });
+}

package/templates/private/api-blob-proxy.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+import { head } from '@vercel/blob';
+import { audit } from '@/lib/audit';
+
+const SESSION_COOKIE_NAMES = ['better-auth.session_token', 'authjs.session-token', 'session_token'];
+
+export async function GET(req: Request, { params }: { params: Promise<{ path: string[] }> }) {
+  const cookieHeader = req.headers.get('cookie') || '';
+  const hasSession = SESSION_COOKIE_NAMES.some((name) => cookieHeader.includes(`${name}=`));
+  if (!hasSession) {
+    audit({
+      ts: new Date().toISOString(),
+      path: new URL(req.url).pathname,
+      ip: req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || 'unknown',
+      method: 'GET',
+      ua: req.headers.get('user-agent') || '',
+      reason: 'no_session',
+      status: 401,
+    });
+    return new NextResponse('Unauthorized', { status: 401 });
+  }
+
+  const { path } = await params;
+  const blobPath = path.join('/');
+  try {
+    const blob = await head(blobPath);
+    if (!blob) return new NextResponse('Not Found', { status: 404 });
+    const upstream = await fetch(blob.url);
+    if (!upstream.ok || !upstream.body) return new NextResponse('Not Found', { status: 404 });
+    return new NextResponse(upstream.body, {
+      headers: {
+        'content-type': blob.contentType || 'application/octet-stream',
+        'cache-control': 'private, no-store',
+        'x-robots-tag': 'noindex, nofollow',
+      },
+    });
+  } catch {
+    return new NextResponse('Not Found', { status: 404 });
+  }
+}

package/templates/private/lib-audit.ts

@@ -0,0 +1,18 @@
+export type AuditEntry = {
+  ts: string;
+  path: string;
+  ip: string;
+  method: string;
+  ua: string;
+  reason: 'no_session' | 'rate_limit' | 'invalid_token';
+  status: number;
+};
+
+const IGNORE_PATHS: string[] = [
+  '/api/audit/health',
+];
+
+export function audit(entry: AuditEntry): void {
+  if (IGNORE_PATHS.some((p) => entry.path.startsWith(p))) return;
+  console.log(`[audit] ${JSON.stringify(entry)}`);
+}

package/templates/private/lib-rate-limit-kv.ts

@@ -0,0 +1,21 @@
+import { kv } from '@vercel/kv';
+
+const LIMITS: { test: (path: string) => boolean; perMin: number }[] = [
+  { test: (p) => p.startsWith('/api/'), perMin: 60 },
+  { test: () => true, perMin: 600 },
+];
+
+export async function rateLimit({ ip, path }: { ip: string; path: string }): Promise<{ ok: boolean; retryAfterSeconds: number }> {
+  const limit = LIMITS.find((l) => l.test(path))!;
+  const minute = Math.floor(Date.now() / 60_000);
+  const key = `rl:${ip}:${minute}:${limit.perMin}`;
+  const count = await kv.incr(key);
+  if (count === 1) {
+    await kv.expire(key, 65);
+  }
+  if (count > limit.perMin) {
+    const retryAfterSeconds = 60 - (Math.floor(Date.now() / 1000) % 60);
+    return { ok: false, retryAfterSeconds };
+  }
+  return { ok: true, retryAfterSeconds: 0 };
+}

package/templates/private/lib-rate-limit-memory.ts

@@ -0,0 +1,25 @@
+type Bucket = { count: number; resetAt: number };
+
+const buckets = new Map<string, Bucket>();
+
+const LIMITS: { test: (path: string) => boolean; perMin: number }[] = [
+  { test: (p) => p.startsWith('/api/'), perMin: 60 },
+  { test: () => true, perMin: 600 },
+];
+
+export async function rateLimit({ ip, path }: { ip: string; path: string }): Promise<{ ok: boolean; retryAfterSeconds: number }> {
+  const limit = LIMITS.find((l) => l.test(path))!;
+  const key = `${ip}::${limit.perMin}`;
+  const now = Date.now();
+  const bucket = buckets.get(key);
+
+  if (!bucket || bucket.resetAt < now) {
+    buckets.set(key, { count: 1, resetAt: now + 60_000 });
+    return { ok: true, retryAfterSeconds: 0 };
+  }
+  if (bucket.count >= limit.perMin) {
+    return { ok: false, retryAfterSeconds: Math.ceil((bucket.resetAt - now) / 1000) };
+  }
+  bucket.count += 1;
+  return { ok: true, retryAfterSeconds: 0 };
+}

package/templates/private/middleware.ts

@@ -0,0 +1,60 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { rateLimit } from '@/lib/rate-limit';
+import { audit } from '@/lib/audit';
+
+const SESSION_COOKIE_NAMES = ['better-auth.session_token', 'authjs.session-token', 'session_token'];
+
+function getIp(req: NextRequest): string {
+  const xff = req.headers.get('x-forwarded-for');
+  if (xff) return xff.split(',')[0].trim();
+  return req.headers.get('x-real-ip') || 'unknown';
+}
+
+export async function middleware(req: NextRequest) {
+  const ip = getIp(req);
+  const path = req.nextUrl.pathname;
+  const method = req.method;
+  const ua = req.headers.get('user-agent') || '';
+
+  const rl = await rateLimit({ ip, path });
+  if (!rl.ok) {
+    audit({ ts: new Date().toISOString(), path, ip, method, ua, reason: 'rate_limit', status: 429 });
+    return new NextResponse('Too Many Requests', {
+      status: 429,
+      headers: {
+        'retry-after': String(rl.retryAfterSeconds),
+        'x-robots-tag': 'noindex, nofollow',
+      },
+    });
+  }
+
+  const hasSession = SESSION_COOKIE_NAMES.some((name) => req.cookies.get(name)?.value);
+  if (!hasSession) {
+    audit({ ts: new Date().toISOString(), path, ip, method, ua, reason: 'no_session', status: 401 });
+    if (method === 'GET' && req.headers.get('accept')?.includes('text/html')) {
+      const url = req.nextUrl.clone();
+      url.pathname = '/sign-in';
+      url.searchParams.set('next', path);
+      return NextResponse.redirect(url);
+    }
+    return new NextResponse('Unauthorized', {
+      status: 401,
+      headers: { 'x-robots-tag': 'noindex, nofollow' },
+    });
+  }
+
+  const res = NextResponse.next();
+  res.headers.set('x-robots-tag', 'noindex, nofollow');
+  return res;
+}
+
+export const config = {
+  // Default-deny matcher.
+  // Bypassed: /login, /signup, /sign-in, /sign-up, /api/auth/*, /api/audit/health,
+  //           /_next/static/*, /favicon.ico, /robots.txt.
+  // NOTE: /_next/image is deliberately NOT excluded. The image optimizer must be
+  // auth-gated too. Otherwise /_next/image?url=<blob-url> would proxy private blobs
+  // around auth.
+  matcher: ['/((?!login|signup|sign-in|sign-up|api/auth|api/audit/health|_next/static|favicon\\.ico|robots\\.txt).*)'],
+};

package/templates/private/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  images: {
+    // Intentionally empty. The Next.js image optimizer cannot proxy any external
+    // host. This is required for privacy mode: if a private blob URL were added
+    // here, /_next/image?url=<blob-url> would serve the blob around auth.
+    //
+    // To serve user uploads with auth, use the /api/blob/[...path] proxy route.
+    remotePatterns: [],
+  },
+};
+
+export default nextConfig;

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"
+  }
+}