feat(use-cases): clickable cards + per-case detail pages (#14)

Every use case on /use-cases is now a link to /use-cases/<slug>
with an auto-generated detail page. 104 cases, 104 pre-rendered
HTML files, no hand-authored content required.

Each detail page renders:
- Title + category + scenario (from frontmatter)
- "How to set it up" — one step per service in the case, with the
  exact curl call and a description of what that call gets you
- A final "wire it up" step pointing to the /claim flow
- "Why this is useful" — generic value prop bullets (zero
  ceremony, anonymous-first, real infrastructure not a sandbox,
  designed for agents)
- "Detail" — renders the case's optional body if present in the
  .md frontmatter file. Empty for all 104 cases today; will fill
  in via content-repo PRs over time.
- Footer with the primary curl + links to /use-cases, /docs,
  and openapi.json

Content shape upstream:
  use-cases.json (single file)  →  use-cases/<slug>.md (one per)
The dashboard's useCases.ts loader switched accordingly, with the
slug derived from filename (kebab-case of title, & → and). All 104
slugs unique.

Total static HTML files: 11 → 115 (104 new detail pages + 11
existing pages). Cards on /use-cases use react-router Link so
client-side navigation is instant after the first page load; SSG
output is fully indexable.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

scripts/prerender.mjs

@@ -51,9 +51,15 @@ async function loadRoutes() {
   // content repo automatically expands the prerender route list — no
   // change needed here.
   const blogDir = resolve(ROOT, '.content/blog')
-  const slugs = existsSync(blogDir)
+  const blogSlugs = existsSync(blogDir)
     ? readdirSync(blogDir).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''))
     : []
+
+  const useCaseDir = resolve(ROOT, '.content/use-cases')
+  const useCaseSlugs = existsSync(useCaseDir)
+    ? readdirSync(useCaseDir).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''))
+    : []
+
   return [
     '/',
     '/pricing',
@@ -62,7 +68,8 @@ async function loadRoutes() {
     '/docs',
     '/blog',
     '/use-cases',
-    ...slugs.map((s) => `/blog/${s}`),
+    ...blogSlugs.map((s) => `/blog/${s}`),
+    ...useCaseSlugs.map((s) => `/use-cases/${s}`),
   ]
 }
 

src/App.tsx

@@ -10,6 +10,7 @@ import { BlogPage } from './pages/BlogPage'
 import { BlogPostPage } from './pages/BlogPostPage'
 import { DocsPage } from './pages/DocsPage'
 import { UseCasesPage } from './pages/UseCasesPage'
+import { UseCaseDetailPage } from './pages/UseCaseDetailPage'
 
 // Auth surfaces
 import { LoginPage } from './pages/LoginPage'
@@ -61,6 +62,7 @@ export function AppRoutes() {
         <Route path="/blog/:slug" element={<BlogPostPage />} />
         <Route path="/docs" element={<DocsPage />} />
         <Route path="/use-cases" element={<UseCasesPage />} />
+        <Route path="/use-cases/:slug" element={<UseCaseDetailPage />} />
 
         {/* ─── auth surfaces (no chrome, dedicated layout) ───────── */}
         <Route path="/login" element={<LoginPage />} />

src/content/useCases.ts

@@ -1,40 +1,93 @@
 /* useCases.ts — loader for the /use-cases catalogue.
  *
- * Source of truth: InstaNode-dev/content/use-cases.json, fetched
- * into .content/ at build time by scripts/fetch-content.mjs.
+ * Source of truth: InstaNode-dev/content/use-cases/<slug>.md, cloned
+ * into .content/ at build time. Each file is a markdown document with
+ * YAML frontmatter:
  *
- * Vite handles JSON imports natively (no plugin, no loader); the
- * import.meta.glob form here keeps the load-time pattern identical
- * to posts.ts so a future move to many files (one per case) is a
- * one-line change. Adding a use case = one entry in the JSON file
- * in the content repo. */
+ *   ---
+ *   title: ...
+ *   category: ...
+ *   services: ["pg", "redis"]   # JSON-array syntax for arrays
+ *   scenario: ...
+ *   ---
+ *
+ *   (optional body: hand-authored "How to do it" / "Why this is useful")
+ *
+ * The slug is the filename without `.md`. Adding a use case = one
+ * markdown file in the content repo; no dashboard PR.
+ *
+ * Service is a closed union (platform-defined). Category is a plain
+ * string (content-defined). See PR #13 for the category type history. */
 
 export type Service = 'pg' | 'redis' | 'mongo' | 'nats' | 'minio' | 'webhook' | 'deploy'
-
-/* Category is intentionally a plain string. The content repo is the source
- * of truth for what categories exist, so the dashboard should accept
- * anything that lands there. The UseCasesPage renders categories in
- * alphabetical order and uses them as filter-chip labels — no code path
- * needs a closed union. Adding a new category = one entry in
- * use-cases.json; no dashboard PR. */
 export type Category = string
 
 export type UseCase = {
+  slug: string
   title: string
   category: Category
   scenario: string
   services: Service[]
+  body: string // "" if no hand-authored detail content yet
 }
 
-/* Vite inlines the JSON at build time. The glob form returns a map of
- * { path: parsedJson }; we have exactly one file, so flatten. */
-const RAW = import.meta.glob('../../.content/use-cases.json', {
+const RAW = import.meta.glob('../../.content/use-cases/*.md', {
   eager: true,
+  query: '?raw',
   import: 'default',
-}) as Record<string, unknown[]>
+}) as Record<string, string>
+
+export const USE_CASES: UseCase[] = Object.entries(RAW)
+  .map(([path, src]) => buildCase(path, src))
+  .filter((c): c is UseCase => c !== null)
+  .sort((a, b) => a.title.localeCompare(b.title))
+
+export function getUseCaseBySlug(slug: string): UseCase | undefined {
+  return USE_CASES.find((c) => c.slug === slug)
+}
 
-const ENTRIES = (Object.values(RAW)[0] ?? []) as Array<UseCase | { _comment: string }>
+function buildCase(path: string, src: string): UseCase | null {
+  const filename = path.split('/').pop()
+  if (!filename) return null
+  const slug = filename.replace(/\.md$/, '')
 
-export const USE_CASES: UseCase[] = ENTRIES.filter(
-  (e): e is UseCase => !('_comment' in e) && typeof (e as UseCase).title === 'string',
-)
+  const { meta, body } = parseFrontmatter(src)
+  if (!meta.title || !meta.category || !meta.scenario) return null
+
+  return {
+    slug,
+    title: meta.title,
+    category: meta.category,
+    scenario: meta.scenario,
+    services: parseServices(meta.services),
+    body: body.trim(),
+  }
+}
+
+/* parseServices — accepts JSON-array syntax in frontmatter, e.g.
+ *   services: ["pg", "redis"]
+ * Anything that doesn't parse as an array of strings becomes []. */
+function parseServices(raw: string | undefined): Service[] {
+  if (!raw) return []
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter((s): s is Service => typeof s === 'string') as Service[]
+  } catch {
+    return []
+  }
+}
+
+function parseFrontmatter(src: string): { meta: Record<string, string>; body: string } {
+  const m = src.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!m) return { meta: {}, body: src }
+  const meta: Record<string, string> = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const sep = line.indexOf(':')
+    if (sep < 0) continue
+    const key = line.slice(0, sep).trim()
+    const value = line.slice(sep + 1).trim()
+    if (key) meta[key] = value
+  }
+  return { meta, body: m[2] }
+}