shipd 0.1.0

package/docs-template/[slug]/page.tsx

@@ -0,0 +1,422 @@
+import DocsToc from "@/components/docs/docs-toc";
+import DocsCategoryPage, { type CategoryPageModel } from "@/components/docs/docs-category-page";
+
+const pages: Record<
+  string,
+  {
+    title: string;
+    updated: string;
+    toc: { id: string; title: string }[];
+    sections: { id: string; heading: string; body: string }[];
+  }
+> = {
+  authentication: {
+    title: "Authentication",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "better-auth", title: "Better Auth" },
+      { id: "supabase-auth", title: "Supabase Auth" },
+      { id: "nextauth", title: "NextAuth" },
+    ],
+    sections: [
+      { id: "better-auth", heading: "Better Auth", body: "Modern auth with database-backed sessions and provider linking." },
+      { id: "supabase-auth", heading: "Supabase Auth", body: "Use Supabase Auth for magic links, OAuth, and session management." },
+      { id: "nextauth", heading: "NextAuth", body: "Classic Next.js auth with OAuth providers and adapters." },
+    ],
+  },
+  payments: {
+    title: "Payments",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "stripe", title: "Stripe" },
+      { id: "lemon-squeezy", title: "Lemon Squeezy" },
+      { id: "polar", title: "Polar" },
+      { id: "webhooks", title: "Webhooks" },
+    ],
+    sections: [
+      { id: "stripe", heading: "Stripe", body: "Create checkout sessions and manage subscriptions with Stripe." },
+      { id: "lemon-squeezy", heading: "Lemon Squeezy", body: "Sell subscriptions and one-time payments with Lemon Squeezy." },
+      { id: "polar", heading: "Polar", body: "Subscriptions + customer portal with Polar (current default in this project)." },
+      { id: "webhooks", heading: "Webhooks", body: "Handle payment events to update user access and subscription state." },
+    ],
+  },
+  emails: {
+    title: "Emails",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "resend", title: "Resend" },
+      { id: "mailgun", title: "Mailgun" },
+      { id: "inbound-webhooks", title: "Inbound webhooks" },
+      { id: "dns", title: "DNS (DKIM/DMARC/SPF)" },
+    ],
+    sections: [
+      { id: "resend", heading: "Resend", body: "Send transactional emails with Resend and keep deliverability high." },
+      { id: "mailgun", heading: "Mailgun", body: "Send transactional emails with Mailgun and configure sending domains." },
+      { id: "inbound-webhooks", heading: "Inbound webhooks", body: "Receive inbound emails and forward them to your app/webhook endpoint." },
+      { id: "dns", heading: "DNS (DKIM/DMARC/SPF)", body: "Set up DNS records on a subdomain to avoid the spam folder." },
+    ],
+  },
+  database: {
+    title: "Database",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "supabase-postgres", title: "Supabase Postgres" },
+      { id: "neon-postgres", title: "Neon Postgres" },
+      { id: "mongodb", title: "MongoDB" },
+      { id: "schema", title: "Schema & migrations" },
+    ],
+    sections: [
+      { id: "supabase-postgres", heading: "Supabase Postgres", body: "Use Supabase’s hosted Postgres and connection strings." },
+      { id: "neon-postgres", heading: "Neon Postgres", body: "Use Neon serverless Postgres with Drizzle ORM." },
+      { id: "mongodb", heading: "MongoDB", body: "Use MongoDB with Mongoose schemas + useful plugins." },
+      { id: "schema", heading: "Schema & migrations", body: "Create tables/schemas and keep them in sync across environments." },
+    ],
+  },
+  seo: {
+    title: "SEO",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "blog", title: "Blog starter" },
+      { id: "metadata", title: "Meta tags" },
+      { id: "opengraph", title: "OpenGraph" },
+      { id: "sitemap", title: "Sitemap" },
+      { id: "structured-data", title: "Structured data" },
+    ],
+    sections: [
+      { id: "blog", heading: "Blog starter", body: "A starter blog structure and example posts." },
+      { id: "metadata", heading: "Meta tags", body: "Defaults for title/description and page-level overrides." },
+      { id: "opengraph", heading: "OpenGraph", body: "OpenGraph tags for beautiful social sharing previews." },
+      { id: "sitemap", heading: "Sitemap", body: "Automated sitemap generation for faster indexing." },
+      { id: "structured-data", heading: "Structured data", body: "Schema.org markup for rich snippets." },
+    ],
+  },
+  style: {
+    title: "Style",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "tailwind", title: "Tailwind CSS" },
+      { id: "daisyui", title: "daisyUI themes" },
+      { id: "dark-mode", title: "Automatic dark mode" },
+      { id: "components", title: "UI components" },
+    ],
+    sections: [
+      { id: "tailwind", heading: "Tailwind CSS", body: "Utility-first styling with a good default design system." },
+      { id: "daisyui", heading: "daisyUI themes", body: "Prebuilt themes to quickly re-skin the app." },
+      { id: "dark-mode", heading: "Automatic dark mode", body: "Theme toggle + persisted preference." },
+      { id: "components", heading: "UI components", body: "A component library with common sections, forms, and layout." },
+    ],
+  },
+  "production-checklist": {
+    title: "Production Checklist",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "overview", title: "Overview" },
+      { id: "environment-variables", title: "Environment variables" },
+      { id: "webhooks", title: "Webhooks" },
+    ],
+    sections: [
+      {
+        id: "overview",
+        heading: "Overview",
+        body: "A short checklist to make sure your SaaS is ready for production deployment.",
+      },
+      {
+        id: "environment-variables",
+        heading: "Environment variables",
+        body: "Set DATABASE_URL, BETTER_AUTH_SECRET, POLAR_WEBHOOK_SECRET, and any provider keys used by your selected features.",
+      },
+      {
+        id: "webhooks",
+        heading: "Webhooks",
+        body: "Verify Polar webhook endpoints, signature validation, and idempotency handling before launch.",
+      },
+    ],
+  },
+  "knowledge-base": {
+    title: "Knowledge Base",
+    updated: "December 18, 2025",
+    toc: [
+      { id: "common-issues", title: "Common issues" },
+      { id: "database-setup", title: "Database setup" },
+    ],
+    sections: [
+      { id: "common-issues", heading: "Common issues", body: "Troubleshooting notes and known gotchas." },
+      { id: "database-setup", heading: "Database setup", body: "How to configure DATABASE_URL for Neon or Supabase." },
+    ],
+  },
+  "build-your-applications": {
+    title: "Build your applications",
+    updated: "December 18, 2025",
+    toc: [{ id: "structure", title: "Project structure" }],
+    sections: [{ id: "structure", heading: "Project structure", body: "How the app is organized and where to extend." }],
+  },
+  "deploy-and-scale": {
+    title: "Deploy and scale",
+    updated: "December 18, 2025",
+    toc: [{ id: "vercel", title: "Vercel deploy" }],
+    sections: [{ id: "vercel", heading: "Vercel deploy", body: "Connect your repo, set env vars, deploy." }],
+  },
+  secure: {
+    title: "Secure your applications",
+    updated: "December 18, 2025",
+    toc: [{ id: "best-practices", title: "Best practices" }],
+    sections: [{ id: "best-practices", heading: "Best practices", body: "Security fundamentals for SaaS apps." }],
+  },
+};
+
+const categoryPages: Record<string, CategoryPageModel> = {
+  authentication: {
+    title: "Authentication",
+    subtitle: "Choose an auth provider and ship login, sessions, protected pages, and OAuth without reinventing the wheel.",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Login + signup UX", "OAuth support (e.g. Google)", "Protected routes and sessions"],
+      youConfigure: ["Auth provider keys", "Redirect URLs", "Session secret"],
+    },
+    quickStart: [
+      { title: "Add environment variables", description: "Add your auth secrets and OAuth keys to .env.local (BETTER_AUTH_SECRET, GOOGLE_CLIENT_ID, etc.)." },
+      { title: "Configure OAuth redirects", description: "Set allowed callback URLs in your provider dashboard (Google, GitHub, etc.)." },
+      { title: "Restart the dev server", description: "Restart npm run dev so environment variables are loaded." },
+      { title: "Test sign-in flow", description: "Visit /sign-up, create an account, then access a protected page to verify everything works." },
+    ],
+    variants: [
+      { title: "Better Auth", href: "/docs/authentication/better-auth", summary: "Default in the current scaffold. Database-backed sessions and provider linking.", status: "available" },
+      { title: "Supabase Auth", href: "/docs/authentication/supabase-auth", summary: "Magic links + OAuth via Supabase Auth, with a managed user system.", status: "coming_soon" },
+      { title: "NextAuth", href: "/docs/authentication/nextauth", summary: "Popular Next.js auth option with providers and adapter-based persistence.", status: "coming_soon" },
+    ],
+    snippets: [
+      {
+        title: "Scaffold a new app",
+        description: "Generate a new project and start the dev server.",
+        variant: "terminal",
+        code: `$ npx shipd init my-app\n$ cd my-app\n$ npm run dev`,
+      },
+      {
+        title: ".env.local (auth essentials)",
+        description: "Minimal keys you’ll set for Better Auth + Google OAuth.",
+        variant: "env",
+        code: `# Auth\nBETTER_AUTH_SECRET=\"please-change-me\"\nGOOGLE_CLIENT_ID=\"your-google-client-id\"\nGOOGLE_CLIENT_SECRET=\"your-google-client-secret\"`,
+      },
+    ],
+  },
+  payments: {
+    title: "Payments",
+    subtitle: "Add subscriptions and checkout flows with webhook-driven access control.",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Checkout flow", "Webhook handling", "Subscription state tracking"],
+      youConfigure: ["Payment provider keys", "Webhook secret", "Product IDs / price IDs"],
+    },
+    quickStart: [
+      { title: "Add payment provider keys", description: "Add your provider API keys and webhook secret to .env.local (POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, etc.)." },
+      { title: "Create subscription products", description: "Create your subscription tiers/prices in your provider dashboard (Polar.sh, Stripe, etc.)." },
+      { title: "Configure webhook endpoint", description: "Point webhooks to your app's /api/webhooks/[provider] route and verify signature validation is enabled." },
+      { title: "Test checkout flow", description: "Visit /pricing, select a plan, complete checkout, and verify subscription state updates in the dashboard." },
+    ],
+    variants: [
+      { title: "Polar", href: "/docs/payments/polar", summary: "Default in the current scaffold. Subscriptions + customer portal with Polar.", status: "available" },
+      { title: "Stripe", href: "/docs/payments/stripe", summary: "Industry standard payments. Subscriptions, invoices, coupons, and more.", status: "coming_soon" },
+      { title: "Lemon Squeezy", href: "/docs/payments/lemon-squeezy", summary: "Fast SaaS billing and digital products with a simple setup.", status: "coming_soon" },
+    ],
+    snippets: [
+      {
+        title: ".env.local (Polar)",
+        description: "Keys needed to enable checkout + webhook handling.",
+        variant: "env",
+        code: `# Polar\nPOLAR_ACCESS_TOKEN=\"your-polar-access-token\"\nPOLAR_WEBHOOK_SECRET=\"your-webhook-secret\"\nPOLAR_SUCCESS_URL=\"http://localhost:3000/success\"\nNEXT_PUBLIC_STARTER_TIER=\"your-starter-tier-id\"\nNEXT_PUBLIC_STARTER_SLUG=\"your-org-slug\"`,
+      },
+      {
+        title: "Run a local webhook test",
+        description: "Once deployed, you’ll point your provider’s webhook to your /api route.",
+        variant: "terminal",
+        code: `$ # provider dashboard → set webhook URL\n$ # verify signature validation is enabled`,
+      },
+    ],
+  },
+  emails: {
+    title: "Emails",
+    subtitle: "Send transactional email and configure DNS so your messages land in inboxes (not spam).",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Transactional sends", "Deliverability checklist", "Optional inbound webhooks"],
+      youConfigure: ["Provider API key", "Sending domain", "DKIM/DMARC/SPF DNS records"],
+    },
+    quickStart: [
+      { title: "Add email provider API key", description: "Add your provider API key to .env.local (RESEND_API_KEY, MAILGUN_API_KEY, etc.)." },
+      { title: "Verify sending domain", description: "Set up a subdomain (e.g., mg.yourdomain.com) and verify it in your provider dashboard." },
+      { title: "Configure DNS records", description: "Add DKIM, DMARC, and SPF records to your subdomain to avoid spam folders." },
+      { title: "Test email sending", description: "Trigger a transactional email (e.g., welcome email on signup) and verify it arrives in inbox." },
+    ],
+    variants: [
+      { title: "Resend", href: "/docs/emails/resend", summary: "Simple transactional email provider with a great developer experience.", status: "coming_soon" },
+      { title: "Mailgun", href: "/docs/emails/mailgun", summary: "Robust sending + optional inbound email processing capabilities.", status: "coming_soon" },
+      { title: "Inbound webhooks", href: "/docs/emails/inbound-webhooks", summary: "Receive and forward inbound email events to your app endpoint.", status: "coming_soon" },
+      { title: "DNS (DKIM/DMARC/SPF)", href: "/docs/emails/dns", summary: "Deliverability essentials—set these on a subdomain for best results.", status: "available" },
+    ],
+    snippets: [
+      {
+        title: ".env.local (email provider)",
+        description: "Example env vars (provider-specific).",
+        variant: "env",
+        code: `# Email\nEMAIL_PROVIDER_API_KEY=\"your-provider-api-key\"\nEMAIL_FROM=\"Your App <no-reply@mg.yourdomain.com>\"`,
+      },
+      {
+        title: "Deliverability checklist",
+        description: "Use a subdomain and configure DKIM/DMARC/SPF before you send.",
+        variant: "terminal",
+        code: `$ # DNS\n$ # DKIM + SPF + DMARC\n$ # verify domain in provider dashboard`,
+      },
+    ],
+  },
+  database: {
+    title: "Database",
+    subtitle: "Pick your database and start with schemas/tables and safe migration workflows.",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Schema starter", "Migrations workflow", "Connection-string based config"],
+      youConfigure: ["DATABASE_URL", "Provider-specific credentials", "Migration commands"],
+    },
+    quickStart: [
+      { title: "Set DATABASE_URL", description: "Add your database connection string to .env.local (e.g., from Neon or Supabase dashboard)." },
+      { title: "Run migrations", description: "Generate and apply schema changes with drizzle-kit (npx drizzle-kit generate && npx drizzle-kit push)." },
+      { title: "Restart the dev server", description: "Restart npm run dev so the database connection is loaded." },
+      { title: "Verify database connection", description: "Sign up a test user and confirm auth/session data is stored correctly in the database." },
+    ],
+    variants: [
+      { title: "Neon Postgres", href: "/docs/database/neon-postgres", summary: "Default in the current scaffold. Serverless Postgres + Drizzle ORM.", status: "available" },
+      { title: "Supabase Postgres", href: "/docs/database/supabase-postgres", summary: "Managed Postgres with Supabase dashboard and tooling.", status: "available" },
+      { title: "MongoDB", href: "/docs/database/mongodb", summary: "Document database option (planned) with Mongoose schemas/plugins.", status: "coming_soon" },
+      { title: "Schema & migrations", href: "/docs/database/schema-migrations", summary: "How to keep schema changes tracked and deployable.", status: "available" },
+    ],
+    snippets: [
+      {
+        title: ".env.local (DATABASE_URL)",
+        description: "Use Neon or Supabase Postgres connection strings.",
+        variant: "env",
+        code: `DATABASE_URL=\"postgresql://postgres:YOUR_PASSWORD@db.yourproject.supabase.co:5432/postgres\"`,
+      },
+      {
+        title: "Run migrations (Drizzle)",
+        description: "Generate and apply schema changes.",
+        variant: "terminal",
+        code: `$ npx drizzle-kit generate\n$ npx drizzle-kit push`,
+      },
+    ],
+  },
+  seo: {
+    title: "SEO",
+    subtitle: "Ship SEO basics so your landing pages and docs are discoverable and share well.",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Meta tags defaults", "OpenGraph tags", "Sitemap + structured data options"],
+      youConfigure: ["Site name/URL", "Social image", "Blog structure (optional)"],
+    },
+    quickStart: [
+      { title: "Set site metadata", description: "Update name/description and OpenGraph defaults." },
+      { title: "Add a blog (optional)", description: "Publish engineering/launch posts to rank for keywords." },
+      { title: "Generate sitemap", description: "Ensure pages are included and indexed quickly." },
+      { title: "Add structured data", description: "Use schema.org markup for richer snippets." },
+    ],
+    variants: [
+      { title: "Blog starter", href: "/docs/seo/blog", summary: "A simple blog structure you can extend.", status: "available" },
+      { title: "Meta tags", href: "/docs/seo/meta-tags", summary: "Title/description defaults and page overrides.", status: "available" },
+      { title: "OpenGraph", href: "/docs/seo/opengraph", summary: "Social sharing previews for links.", status: "available" },
+      { title: "Sitemap", href: "/docs/seo/sitemap", summary: "Automated sitemap generation.", status: "available" },
+      { title: "Structured data", href: "/docs/seo/structured-data", summary: "Schema.org markup for rich snippets.", status: "available" },
+    ],
+    snippets: [
+      {
+        title: "Metadata (Next.js)",
+        description: "Example page metadata with OpenGraph defaults.",
+        variant: "code",
+        code: `export const metadata = {\n  title: \"My SaaS\",\n  description: \"Launch fast with shipd\",\n  openGraph: {\n    title: \"My SaaS\",\n    description: \"Launch fast with shipd\",\n  },\n};`,
+      },
+    ],
+  },
+  style: {
+    title: "Style",
+    subtitle: "Start with a polished UI kit and theming so your SaaS looks great from day one.",
+    updated: "December 18, 2025",
+    atAGlance: {
+      whatYouGet: ["Component library", "Responsive layout patterns", "Theme/dark mode support"],
+      youConfigure: ["Brand colors", "Theme choice", "Typography tweaks"],
+    },
+    quickStart: [
+      { title: "Pick a base theme", description: "Start with Tailwind, then apply a theme system if needed." },
+      { title: "Customize tokens", description: "Adjust colors, radii, and spacing to match your brand." },
+      { title: "Enable dark mode", description: "Make sure theme preference persists across sessions." },
+      { title: "Reuse sections", description: "Use prebuilt sections for pricing, testimonials, FAQ, etc." },
+    ],
+    variants: [
+      { title: "Tailwind CSS", href: "/docs/style/tailwind", summary: "Utility-first styling with sensible defaults.", status: "available" },
+      { title: "daisyUI themes", href: "/docs/style/daisyui", summary: "Theme packs to re-skin your UI quickly (planned).", status: "coming_soon" },
+      { title: "Automatic dark mode", href: "/docs/style/dark-mode", summary: "Toggle + persisted preference out of the box.", status: "available" },
+      { title: "UI components", href: "/docs/style/ui-components", summary: "A starter component library for common flows and sections.", status: "available" },
+    ],
+    snippets: [
+      {
+        title: "Use a component",
+        description: "Example of a shadcn/ui button.",
+        variant: "code",
+        code: `import { Button } from \"@/components/ui/button\";\n\nexport function Example() {\n  return <Button>Get Started</Button>;\n}`,
+      },
+    ],
+  },
+};
+
+export default async function DocsPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const category = categoryPages[slug];
+  const page = pages[slug];
+
+  if (category) {
+    const toc = [
+      { id: "at-a-glance", title: "At a glance" },
+      { id: "quickstart", title: "Quickstart" },
+      { id: "providers", title: "Providers" },
+      ...(category.snippets?.length ? [{ id: "code", title: "Code" }] : []),
+    ];
+
+    return (
+      <div className="grid grid-cols-1 xl:grid-cols-[minmax(0,1fr)_240px] gap-10">
+        <DocsCategoryPage model={category} />
+        <aside className="hidden xl:block">
+          <DocsToc items={toc} />
+        </aside>
+      </div>
+    );
+  }
+
+  if (!page) {
+    return (
+      <div className="py-10">
+        <div className="text-3xl font-semibold tracking-tight">Not found</div>
+        <p className="mt-3 text-white/70">This docs page doesn’t exist yet.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid grid-cols-1 xl:grid-cols-[minmax(0,1fr)_240px] gap-10">
+      <article className="py-10">
+        <div className="text-[44px] leading-[1.1] font-semibold tracking-tight">{page.title}</div>
+        <div className="mt-4 text-sm text-white/60">Last updated {page.updated}</div>
+
+        <div className="mt-10 border-t border-white/10 pt-10 space-y-10">
+          {page.sections.map((s) => (
+            <section key={s.id} id={s.id} className="space-y-3">
+              <h2 className="text-2xl font-semibold tracking-tight">{s.heading}</h2>
+              <p className="text-white/70 leading-relaxed">{s.body}</p>
+            </section>
+          ))}
+        </div>
+      </article>
+
+      <aside className="hidden xl:block">
+        <DocsToc items={page.toc} />
+      </aside>
+    </div>
+  );
+}
+
+

package/docs-template/api/page.tsx

@@ -0,0 +1,47 @@
+import DocsToc from "@/components/docs/docs-toc";
+
+const toc = [
+  { id: "overview", title: "Overview" },
+  { id: "authentication", title: "Authentication" },
+  { id: "webhooks", title: "Webhooks" },
+];
+
+export default function DocsApiPage() {
+  return (
+    <div className="grid grid-cols-1 xl:grid-cols-[minmax(0,1fr)_240px] gap-10">
+      <article className="py-10">
+        <div className="text-[44px] leading-[1.1] font-semibold tracking-tight">API Reference</div>
+        <div className="mt-4 text-sm text-white/60">Last updated December 18, 2025</div>
+
+        <div className="mt-10 border-t border-white/10 pt-10 space-y-10">
+          <section id="overview" className="space-y-3">
+            <h2 className="text-2xl font-semibold tracking-tight">Overview</h2>
+            <p className="text-white/70 leading-relaxed">
+              This section documents the HTTP endpoints provided by the shipd app (auth, billing, webhooks).
+            </p>
+          </section>
+
+          <section id="authentication" className="space-y-3">
+            <h2 className="text-2xl font-semibold tracking-tight">Authentication</h2>
+            <p className="text-white/70 leading-relaxed">
+              Better Auth routes are available under <span className="text-white">/api/auth</span>.
+            </p>
+          </section>
+
+          <section id="webhooks" className="space-y-3">
+            <h2 className="text-2xl font-semibold tracking-tight">Webhooks</h2>
+            <p className="text-white/70 leading-relaxed">
+              Configure your Polar webhook URL to point to <span className="text-white">/api/subscription</span>.
+            </p>
+          </section>
+        </div>
+      </article>
+
+      <aside className="hidden xl:block">
+        <DocsToc items={toc} />
+      </aside>
+    </div>
+  );
+}
+
+

package/docs-template/components/docs/docs-category-page.tsx

@@ -0,0 +1,162 @@
+import Link from "next/link";
+import { ArrowRight } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent } from "@/components/ui/card";
+import DocsCodeCard, { type DocsCodeCardProps } from "@/components/docs/docs-code-card";
+
+export type CategoryVariant = {
+  title: string;
+  href: string;
+  summary: string;
+  status: "available" | "coming_soon";
+};
+
+export type CategoryQuickStartStep = {
+  title: string;
+  description: string;
+};
+
+export type CategoryPageModel = {
+  title: string;
+  subtitle: string;
+  updated: string;
+  atAGlance: {
+    whatYouGet: string[];
+    youConfigure: string[];
+  };
+  quickStart: CategoryQuickStartStep[];
+  variants: CategoryVariant[];
+  snippets?: DocsCodeCardProps[];
+};
+
+function StatusBadge({ status }: { status: CategoryVariant["status"] }) {
+  if (status === "available") return <Badge className="bg-emerald-500/15 text-emerald-200 border-emerald-500/30">Available</Badge>;
+  return <Badge variant="secondary" className="bg-white/10 text-white/70 border-white/10">Coming soon</Badge>;
+}
+
+function BulletList({ items }: { items: string[] }) {
+  return (
+    <ul className="mt-3 space-y-2 text-sm text-white/70">
+      {items.map((t) => (
+        <li key={t} className="flex gap-2">
+          <span className="mt-[6px] h-1.5 w-1.5 rounded-full bg-white/40 shrink-0" />
+          <span>{t}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export default function DocsCategoryPage({ model }: { model: CategoryPageModel }) {
+  return (
+    <article className="py-10">
+      <div className="text-[44px] leading-[1.1] font-semibold tracking-tight">{model.title}</div>
+      <p className="mt-4 text-white/70 text-lg leading-relaxed max-w-3xl">{model.subtitle}</p>
+      <div className="mt-4 text-sm text-white/60">Last updated {model.updated}</div>
+
+      <div className="mt-10 border-t border-white/10 pt-10 space-y-12">
+        <section id="at-a-glance" className="space-y-5">
+          <h2 className="text-2xl font-semibold tracking-tight">At a glance</h2>
+
+          <div className="grid gap-6 lg:grid-cols-2">
+            <Card className="bg-white/5 border-white/10 shadow-none">
+              <CardContent className="px-6">
+                <div className="pt-4 text-sm font-semibold text-white">What you get</div>
+                <BulletList items={model.atAGlance.whatYouGet} />
+                <div className="pb-4" />
+              </CardContent>
+            </Card>
+
+            <Card className="bg-white/5 border-white/10 shadow-none">
+              <CardContent className="px-6">
+                <div className="pt-4 text-sm font-semibold text-white">You&apos;ll configure</div>
+                <BulletList items={model.atAGlance.youConfigure} />
+                <div className="pb-4" />
+              </CardContent>
+            </Card>
+          </div>
+        </section>
+
+        <section id="quickstart" className="space-y-5">
+          <h2 className="text-2xl font-semibold tracking-tight">Quickstart</h2>
+          <div className="space-y-3">
+            {model.quickStart.map((step, idx) => (
+              <div key={step.title} className="relative">
+                {/* Connector line */}
+                {idx < model.quickStart.length - 1 ? (
+                  <div className="absolute left-8 top-14 bottom-0 w-px bg-white/10" />
+                ) : null}
+
+                <Card className="bg-white/5 border-white/10 shadow-none">
+                  <CardContent className="px-6">
+                    <div className="pt-4 flex items-start gap-3">
+                      <div className="mt-0.5 flex items-center justify-center">
+                        <div className="h-9 w-9 rounded-full border border-white/10 bg-black/30 flex items-center justify-center text-sm font-semibold text-white/80">
+                          {idx + 1}
+                        </div>
+                      </div>
+                      <div className="min-w-0">
+                        <div className="text-base font-semibold text-white">{step.title}</div>
+                        <p className="mt-1 text-sm text-white/60 leading-relaxed">{step.description}</p>
+                      </div>
+                    </div>
+                    <div className="pb-4" />
+                  </CardContent>
+                </Card>
+              </div>
+            ))}
+          </div>
+        </section>
+
+        <section id="providers" className="space-y-5">
+          <h2 className="text-2xl font-semibold tracking-tight">Providers</h2>
+          <p className="text-white/60 text-sm max-w-3xl">
+            Pick an option below. Each provider has a short guide so you can implement without digging through docs.
+          </p>
+
+          <div className="space-y-3">
+            {model.variants.map((v) => (
+              <details
+                key={v.href}
+                className="group rounded-xl border border-white/10 bg-white/5 open:bg-white/[0.07] transition-colors"
+              >
+                <summary className="cursor-pointer list-none px-5 py-3.5 flex items-center gap-3">
+                  <div className="text-sm font-semibold text-white">{v.title}</div>
+                  <StatusBadge status={v.status} />
+                  <div className="ml-auto text-xs text-white/50 group-open:hidden">Expand</div>
+                  <div className="ml-auto text-xs text-white/50 hidden group-open:block">Collapse</div>
+                </summary>
+                <div className="px-5 pb-4">
+                  <p className="text-sm text-white/65 leading-relaxed">{v.summary}</p>
+                  <div className="mt-4">
+                    <Link
+                      href={v.href}
+                      className="inline-flex items-center gap-2 rounded-md bg-white text-black px-3 py-2 text-sm font-medium hover:bg-white/90 transition-colors"
+                    >
+                      Read guide <ArrowRight className="h-4 w-4" />
+                    </Link>
+                  </div>
+                </div>
+              </details>
+            ))}
+          </div>
+        </section>
+
+        {model.snippets?.length ? (
+          <section id="code" className="space-y-5">
+            <h2 className="text-2xl font-semibold tracking-tight">Code</h2>
+            <p className="text-white/60 text-sm max-w-3xl">
+              Copy/paste-friendly code blocks. Designed to get you working quickly without digging through long docs.
+            </p>
+            <div className="space-y-4">
+              {model.snippets.map((s) => (
+                <DocsCodeCard key={s.title} {...s} />
+              ))}
+            </div>
+          </section>
+        ) : null}
+      </div>
+    </article>
+  );
+}
+