Comprehensive admin + user dashboards (production-ready)

app/(app)/episodes/[id]/loading.tsx

@@ -0,0 +1,23 @@
+export default function EpisodeLoading() {
+  return (
+    <div className="animate-pulse space-y-6">
+      <div className="space-y-2">
+        <div className="h-9 w-72 rounded-xl bg-secondary" />
+        <div className="h-4 w-48 rounded-lg bg-secondary/70" />
+      </div>
+      <div className="grid gap-6 lg:grid-cols-3">
+        <div className="space-y-6 lg:col-span-1">
+          <div className="aspect-square rounded-2xl border border-border bg-secondary" />
+          <div className="h-32 rounded-2xl border border-border bg-card" />
+          <div className="h-11 rounded-full bg-secondary" />
+        </div>
+        <div className="space-y-4 lg:col-span-2">
+          <div className="h-14 rounded-2xl border border-border bg-card" />
+          {Array.from({ length: 3 }).map((_, i) => (
+            <div key={i} className="h-40 rounded-2xl border border-border bg-card" />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

app/(app)/episodes/[id]/not-found.tsx

@@ -0,0 +1,22 @@
+import Link from "next/link";
+import { MicOff } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+export default function EpisodeNotFound() {
+  return (
+    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-5 text-center">
+      <div className="flex h-16 w-16 items-center justify-center rounded-2xl bg-secondary text-muted-foreground">
+        <MicOff className="h-7 w-7" />
+      </div>
+      <div className="space-y-1.5">
+        <h1 className="font-display text-2xl font-extrabold tracking-tight">Episode not found</h1>
+        <p className="max-w-sm text-sm text-muted-foreground">
+          This episode doesn&apos;t exist, or you don&apos;t have access to it.
+        </p>
+      </div>
+      <Button asChild>
+        <Link href="/episodes">Back to episodes</Link>
+      </Button>
+    </div>
+  );
+}

app/(app)/episodes/[id]/page.tsx

@@ -32,7 +32,11 @@ export default async function EpisodePage({ params }: { params: Promise<{ id: st
       <PageHeader
         title={episode.title}
         description={`${episode.format.replace("_", "-").toLowerCase()} · ${episode.language.toUpperCase()} · ${episode.targetLengthMin} min`}
-        action={!inProgress ? <EpisodeActions episodeId={episode.id} /> : undefined}
+        action={
+          !inProgress ? (
+            <EpisodeActions episodeId={episode.id} initialShareId={episode.shareId} />
+          ) : undefined
+        }
       />
 
       {episode.status === "FAILED" || inProgress ? (
@@ -68,6 +72,7 @@ export default async function EpisodePage({ params }: { params: Promise<{ id: st
                   <AudioPlayer
                     storageKey={episode.audioAsset.storageKey}
                     durationSec={episode.audioAsset.durationSec}
+                    episodeId={episode.id}
                   />
                 </CardContent>
               </Card>

app/(app)/episodes/actions.ts

@@ -1,13 +1,18 @@
 "use server";
 
+import { randomBytes } from "node:crypto";
 import { revalidatePath } from "next/cache";
 import { z } from "zod";
 import { getServerSession } from "@/lib/auth/guards";
 import { prisma } from "@/lib/db";
 import { getEffectivePlan } from "@/lib/billing/subscription";
-import { enforceLimit, LimitExceededError } from "@/lib/usage/limits";
+import { reserveLimit, LimitExceededError } from "@/lib/usage/limits";
+import { refundUsage } from "@/lib/usage/meter";
 import { enqueueEpisodeGeneration } from "@/lib/queue/pgboss";
 import { rateLimit, LIMITS } from "@/lib/ratelimit";
+import { isFlagEnabled } from "@/lib/flags";
+import { moderateText } from "@/lib/ai/moderation";
+import type { UsageMetric } from "@/lib/billing/plans";
 import type { GenerationType } from "@/lib/queue/jobs";
 import type { Prisma } from "@prisma/client";
 
@@ -42,6 +47,10 @@ export async function createEpisodeAction(input: CreateEpisodeInput): Promise<Cr
     return { ok: false, error: `Too many requests. Try again in ${rl.retryAfterSec}s.` };
   }
 
+  if (!(await isFlagEnabled("episode_generation_enabled"))) {
+    return { ok: false, error: "Episode generation is temporarily paused. Please try again shortly." };
+  }
+
   const parsed = createSchema.safeParse(input);
   if (!parsed.success) {
     return { ok: false, error: parsed.error.issues[0]?.message ?? "Invalid input." };
@@ -49,7 +58,7 @@ export async function createEpisodeAction(input: CreateEpisodeInput): Promise<Cr
   const data = parsed.data;
   const activeOrgId = session.session.activeOrganizationId;
 
-  const { plan } = await getEffectivePlan(session.user.id, activeOrgId);
+  const { plan, subjectId, subjectType } = await getEffectivePlan(session.user.id, activeOrgId);
   if (data.targetLengthMin > plan.limits.maxEpisodeMinutes) {
     return {
       ok: false,
@@ -58,10 +67,33 @@ export async function createEpisodeAction(input: CreateEpisodeInput): Promise<Cr
     };
   }
 
+  // Screen the requested topic before spending any quota or AI budget.
+  if (await isFlagEnabled("ai_moderation_enabled")) {
+    const mod = await moderateText([data.title, data.topic, data.audience].filter(Boolean).join("\n"));
+    if (mod.flagged) {
+      return {
+        ok: false,
+        error: "This topic may violate our content policy and can't be generated. Please revise it and try again.",
+      };
+    }
+  }
+
+  // Reserve quota atomically up front (a full generation consumes script,
+  // audio and art). The worker won't re-meter; we refund below if create/enqueue
+  // fails. See the metering invariant in lib/usage/meter.ts.
+  const reserved: UsageMetric[] = [];
+  const refundReserved = async () => {
+    for (const m of reserved) await refundUsage(subjectId, subjectType, m);
+  };
   try {
-    await enforceLimit(session.user.id, "script", activeOrgId);
-    await enforceLimit(session.user.id, "audio", activeOrgId);
+    await reserveLimit(session.user.id, "script", activeOrgId);
+    reserved.push("script");
+    await reserveLimit(session.user.id, "audio", activeOrgId);
+    reserved.push("audio");
+    await reserveLimit(session.user.id, "art", activeOrgId);
+    reserved.push("art");
   } catch (err) {
+    await refundReserved();
     if (err instanceof LimitExceededError) {
       return {
         ok: false,
@@ -72,38 +104,43 @@ export async function createEpisodeAction(input: CreateEpisodeInput): Promise<Cr
     throw err;
   }
 
-  const episode = await prisma.episode.create({
-    data: {
-      userId: session.user.id,
-      organizationId: activeOrgId ?? undefined,
-      title: data.title?.trim() || deriveTitle(data.topic),
-      topic: data.topic,
-      tone: data.tone,
-      format: data.format,
-      language: data.language,
-      targetLengthMin: data.targetLengthMin,
-      audience: data.audience,
-      status: "QUEUED",
-      stage: "Queued for generation",
-      speakers: {
-        create: data.speakers.map((s) => ({
-          speakerKey: s.speakerKey,
-          displayName: s.displayName,
-          elevenVoiceId: s.elevenVoiceId,
-        })),
+  try {
+    const episode = await prisma.episode.create({
+      data: {
+        userId: session.user.id,
+        organizationId: activeOrgId ?? undefined,
+        title: data.title?.trim() || deriveTitle(data.topic),
+        topic: data.topic,
+        tone: data.tone,
+        format: data.format,
+        language: data.language,
+        targetLengthMin: data.targetLengthMin,
+        audience: data.audience,
+        status: "QUEUED",
+        stage: "Queued for generation",
+        speakers: {
+          create: data.speakers.map((s) => ({
+            speakerKey: s.speakerKey,
+            displayName: s.displayName,
+            elevenVoiceId: s.elevenVoiceId,
+          })),
+        },
+        jobs: { create: { type: "full", status: "queued" } },
       },
-      jobs: { create: { type: "full", status: "queued" } },
-    },
-  });
+    });
 
-  await enqueueEpisodeGeneration(
-    { episodeId: episode.id, type: "full" },
-    { priority: plan.features.includes("priority_generation") ? 10 : 0 }
-  );
+    await enqueueEpisodeGeneration(
+      { episodeId: episode.id, type: "full" },
+      { priority: plan.features.includes("priority_generation") ? 10 : 0 }
+    );
 
-  revalidatePath("/episodes");
-  revalidatePath("/dashboard");
-  return { ok: true, episodeId: episode.id };
+    revalidatePath("/episodes");
+    revalidatePath("/dashboard");
+    return { ok: true, episodeId: episode.id };
+  } catch (err) {
+    await refundReserved();
+    throw err;
+  }
 }
 
 export async function regenerateAction(
@@ -113,6 +150,15 @@ export async function regenerateAction(
   const session = await getServerSession();
   if (!session) return { ok: false, error: "You must be signed in." };
 
+  const rl = await rateLimit("generation", session.user.id, LIMITS.generation);
+  if (!rl.ok) {
+    return { ok: false, error: `Too many requests. Try again in ${rl.retryAfterSec}s.` };
+  }
+
+  if (!(await isFlagEnabled("episode_generation_enabled"))) {
+    return { ok: false, error: "Episode generation is temporarily paused. Please try again shortly." };
+  }
+
   const episode = await prisma.episode.findUnique({
     where: { id: episodeId },
     select: { userId: true, organizationId: true },
@@ -122,24 +168,41 @@ export async function regenerateAction(
     return { ok: false, error: "Not allowed." };
   }
 
-  // Gate the metrics this regeneration will consume.
-  const metrics: ("script" | "audio" | "art")[] =
+  const activeOrgId = session.session.activeOrganizationId;
+  const { subjectId, subjectType } = await getEffectivePlan(session.user.id, activeOrgId);
+
+  // Reserve the metrics this regeneration will consume up front. The worker
+  // won't re-meter; refund below if enqueue fails. See meter.ts invariant.
+  const metrics: UsageMetric[] =
     type === "art" ? ["art"] : type === "audio" ? ["audio"] : ["script", "audio"];
+  const reserved: UsageMetric[] = [];
+  const refundReserved = async () => {
+    for (const m of reserved) await refundUsage(subjectId, subjectType, m);
+  };
   try {
-    for (const m of metrics) await enforceLimit(session.user.id, m, session.session.activeOrganizationId);
+    for (const m of metrics) {
+      await reserveLimit(session.user.id, m, activeOrgId);
+      reserved.push(m);
+    }
   } catch (err) {
+    await refundReserved();
     if (err instanceof LimitExceededError) {
       return { ok: false, error: `Monthly ${err.check.metric} limit reached on the ${err.check.plan} plan.` };
     }
     throw err;
   }
 
-  await prisma.episode.update({
-    where: { id: episodeId },
-    data: { status: "QUEUED", stage: "Queued for regeneration", errorMessage: null },
-  });
-  await prisma.generationJob.create({ data: { episodeId, type, status: "queued" } });
-  await enqueueEpisodeGeneration({ episodeId, type });
+  try {
+    await prisma.episode.update({
+      where: { id: episodeId },
+      data: { status: "QUEUED", stage: "Queued for regeneration", errorMessage: null },
+    });
+    await prisma.generationJob.create({ data: { episodeId, type, status: "queued" } });
+    await enqueueEpisodeGeneration({ episodeId, type });
+  } catch (err) {
+    await refundReserved();
+    throw err;
+  }
 
   revalidatePath(`/episodes/${episodeId}`);
   return { ok: true };
@@ -198,8 +261,16 @@ export async function regenerateSectionAction(
   }
   if (!episode.script) return { ok: false, error: "No script to edit yet." };
 
+  const rl = await rateLimit("generation", session.user.id, LIMITS.generation);
+  if (!rl.ok) {
+    return { ok: false, error: `Too many requests. Try again in ${rl.retryAfterSec}s.` };
+  }
+
+  const activeOrgId = session.session.activeOrganizationId;
+  // Reserve the script unit atomically up front. This synchronous action does
+  // NOT increment afterwards (that would double-count) — it refunds on failure.
   try {
-    await enforceLimit(session.user.id, "script", session.session.activeOrganizationId);
+    await reserveLimit(session.user.id, "script", activeOrgId);
   } catch (err) {
     if (err instanceof LimitExceededError) {
       return { ok: false, error: `Monthly script limit reached on the ${err.check.plan} plan.` };
@@ -207,10 +278,12 @@ export async function regenerateSectionAction(
     throw err;
   }
 
+  const ownerId = episode.organizationId ?? episode.userId;
+  const ownerType = episode.organizationId ? "organization" : "user";
+
   // Imported lazily so the AI SDK never reaches client bundles importing this file.
   const { scriptProvider } = await import("@/lib/ai/providers");
   const { recordCost, scriptCostUsd } = await import("@/lib/ai/cost");
-  const { incrementUsage } = await import("@/lib/usage/meter");
 
   const config = {
     title: episode.title,
@@ -227,20 +300,26 @@ export async function regenerateSectionAction(
     sections: { id: string; title: string; turns: { speakerKey: string; text: string }[] }[];
   };
 
-  const { section, usage } = await scriptProvider().regenerateSection(config, current, sectionId);
-  const updated = {
-    ...current,
-    sections: current.sections.map((s) => (s.id === sectionId ? section : s)),
-  };
+  let section: { id: string; title: string; turns: { speakerKey: string; text: string }[] };
+  let usage: { inputTokens: number; outputTokens: number };
+  try {
+    ({ section, usage } = await scriptProvider().regenerateSection(config, current, sectionId));
+    const updated = {
+      ...current,
+      sections: current.sections.map((s) => (s.id === sectionId ? section : s)),
+    };
 
-  await prisma.script.update({
-    where: { episodeId },
-    data: { content: updated as unknown as Prisma.InputJsonValue, version: { increment: 1 } },
-  });
+    await prisma.script.update({
+      where: { episodeId },
+      data: { content: updated as unknown as Prisma.InputJsonValue, version: { increment: 1 } },
+    });
+  } catch (err) {
+    // Generation/save failed — refund the script unit we reserved.
+    await refundUsage(ownerId, ownerType, "script");
+    throw err;
+  }
 
-  const ownerId = episode.organizationId ?? episode.userId;
-  const ownerType = episode.organizationId ? "organization" : "user";
-  await incrementUsage(ownerId, ownerType, "script");
+  // No incrementUsage here: the unit was already reserved above.
   await recordCost({
     provider: "openai",
     operation: "script",
@@ -270,8 +349,16 @@ export async function repurposeAction(
   }
   if (!episode.script) return { ok: false, error: "Generate the episode first." };
 
+  const rl = await rateLimit("repurpose", session.user.id, LIMITS.repurpose);
+  if (!rl.ok) {
+    return { ok: false, error: `Too many requests. Try again in ${rl.retryAfterSec}s.` };
+  }
+
+  const activeOrgId = session.session.activeOrganizationId;
+  // Reserve the repurpose unit atomically up front; refund on failure. This
+  // synchronous action does NOT increment afterwards (that would double-count).
   try {
-    await enforceLimit(session.user.id, "repurpose", session.session.activeOrganizationId);
+    await reserveLimit(session.user.id, "repurpose", activeOrgId);
   } catch (err) {
     if (err instanceof LimitExceededError) {
       return { ok: false, error: `Monthly repurpose limit reached on the ${err.check.plan} plan.` };
@@ -279,22 +366,30 @@ export async function repurposeAction(
     throw err;
   }
 
-  const { repurposeScript } = await import("@/lib/ai/pipeline/repurpose");
-  const { recordCost, scriptCostUsd } = await import("@/lib/ai/cost");
-  const { incrementUsage } = await import("@/lib/usage/meter");
-
-  const { content, usage } = await repurposeScript(
-    episode.script.content as unknown as Parameters<typeof repurposeScript>[0],
-    format
-  );
-
-  await prisma.repurposedContent.create({
-    data: { episodeId, type: format, content: content as unknown as Prisma.InputJsonValue },
-  });
-
   const ownerId = episode.organizationId ?? episode.userId;
   const ownerType = episode.organizationId ? "organization" : "user";
-  await incrementUsage(ownerId, ownerType, "repurpose");
+
+  const { repurposeScript } = await import("@/lib/ai/pipeline/repurpose");
+  const { recordCost, scriptCostUsd } = await import("@/lib/ai/cost");
+
+  let content: { title: string; body: string };
+  let usage: { inputTokens: number; outputTokens: number };
+  try {
+    ({ content, usage } = await repurposeScript(
+      episode.script.content as unknown as Parameters<typeof repurposeScript>[0],
+      format
+    ));
+
+    await prisma.repurposedContent.create({
+      data: { episodeId, type: format, content: content as unknown as Prisma.InputJsonValue },
+    });
+  } catch (err) {
+    // Generation/save failed — refund the repurpose unit we reserved.
+    await refundUsage(ownerId, ownerType, "repurpose");
+    throw err;
+  }
+
+  // No incrementUsage here: the unit was already reserved above.
   await recordCost({
     provider: "openai",
     operation: "repurpose",
@@ -323,6 +418,53 @@ export async function deleteEpisodeAction(episodeId: string): Promise<{ ok: bool
   return { ok: true };
 }
 
+/**
+ * Toggle public sharing for an episode. When enabled, mints a random url-safe
+ * `shareId` (reachable at /p/<shareId> with no auth) and stamps `sharedAt`;
+ * when disabled, clears both so the public page 404s. Ownership-checked.
+ */
+export async function setEpisodeShareAction(
+  episodeId: string,
+  enabled: boolean
+): Promise<{ ok: boolean; error?: string; shareId?: string | null }> {
+  const session = await getServerSession();
+  if (!session) return { ok: false, error: "You must be signed in." };
+
+  const episode = await prisma.episode.findUnique({
+    where: { id: episodeId },
+    select: { userId: true, shareId: true, status: true },
+  });
+  if (!episode || (episode.userId !== session.user.id && session.user.role !== "admin")) {
+    return { ok: false, error: "Not allowed." };
+  }
+
+  if (enabled) {
+    if (episode.status !== "READY") {
+      return { ok: false, error: "Finish generating the episode before sharing it." };
+    }
+    // Reuse an existing shareId if one was already minted (stable public URL).
+    const shareId = episode.shareId ?? randomShareId();
+    await prisma.episode.update({
+      where: { id: episodeId },
+      data: { shareId, sharedAt: new Date() },
+    });
+    revalidatePath(`/episodes/${episodeId}`);
+    return { ok: true, shareId };
+  }
+
+  await prisma.episode.update({
+    where: { id: episodeId },
+    data: { shareId: null, sharedAt: null },
+  });
+  revalidatePath(`/episodes/${episodeId}`);
+  return { ok: true, shareId: null };
+}
+
+/** url-safe base64 token (~22 chars, 128 bits) for public share links. */
+function randomShareId(): string {
+  return randomBytes(16).toString("base64url");
+}
+
 function deriveTitle(topic: string): string {
   const trimmed = topic.trim().replace(/\s+/g, " ");
   return trimmed.length <= 60 ? trimmed : trimmed.slice(0, 57) + "…";

app/(app)/episodes/loading.tsx

@@ -0,0 +1,14 @@
+import { HeaderSkeleton, EpisodeGridSkeleton, Skeleton } from "@/components/ui/skeleton";
+
+export default function EpisodesLoading() {
+  return (
+    <>
+      <HeaderSkeleton />
+      <div className="mb-6 flex flex-wrap gap-3">
+        <Skeleton className="h-10 w-full sm:max-w-xs" />
+        <Skeleton className="h-10 w-[150px]" />
+      </div>
+      <EpisodeGridSkeleton count={8} />
+    </>
+  );
+}

app/(app)/episodes/page.tsx

@@ -1,22 +1,55 @@
 import type { Metadata } from "next";
 import Link from "next/link";
 import { Mic2, Plus } from "lucide-react";
+import type { Prisma, EpisodeStatus } from "@prisma/client";
 import { requireAuth } from "@/lib/auth/guards";
 import { prisma } from "@/lib/db";
 import { PageHeader } from "@/components/app/page-header";
 import { EpisodeCard } from "@/components/app/episode-card";
+import { SearchInput, FilterSelect } from "@/components/admin/ui/table-controls";
 import { Button } from "@/components/ui/button";
+import { EmptyState } from "@/components/ui/empty-state";
 
 export const metadata: Metadata = { title: "Episodes" };
 
-export default async function EpisodesPage() {
+const STATUS_OPTIONS = [
+  { value: "DRAFT", label: "Draft" },
+  { value: "QUEUED", label: "Queued" },
+  { value: "SCRIPTING", label: "Writing script" },
+  { value: "SYNTHESIZING", label: "Recording audio" },
+  { value: "STITCHING", label: "Mixing audio" },
+  { value: "ART", label: "Designing art" },
+  { value: "SAVING", label: "Finalizing" },
+  { value: "READY", label: "Ready" },
+  { value: "FAILED", label: "Failed" },
+];
+
+const VALID_STATUSES = new Set(STATUS_OPTIONS.map((o) => o.value));
+
+export default async function EpisodesPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ q?: string; status?: string }>;
+}) {
   const session = await requireAuth();
+  const { q, status } = await searchParams;
+  const query = q?.trim();
+  const statusFilter = status && VALID_STATUSES.has(status) ? status : undefined;
+
+  const where: Prisma.EpisodeWhereInput = {
+    userId: session.user.id,
+    ...(query ? { title: { contains: query, mode: "insensitive" } } : {}),
+    ...(statusFilter ? { status: statusFilter as EpisodeStatus } : {}),
+  };
+
   const episodes = await prisma.episode.findMany({
-    where: { userId: session.user.id },
+    where,
     orderBy: { createdAt: "desc" },
     include: { coverArt: { select: { storageKey: true } } },
   });
 
+  const filtering = Boolean(query || statusFilter);
+
   return (
     <>
       <PageHeader
@@ -31,21 +64,32 @@ export default async function EpisodesPage() {
         }
       />
 
+      <div className="mb-6 flex flex-col gap-3 sm:flex-row sm:items-center">
+        <SearchInput placeholder="Search episodes…" />
+        <FilterSelect param="status" placeholder="Status" options={STATUS_OPTIONS} allLabel="All statuses" />
+      </div>
+
       {episodes.length === 0 ? (
-        <div className="flex flex-col items-center gap-3 rounded-2xl border border-dashed border-border py-16 text-center">
-          <span className="flex h-14 w-14 items-center justify-center rounded-2xl bg-brand/10 text-brand">
-            <Mic2 className="h-6 w-6" />
-          </span>
-          <div>
-            <p className="font-medium">No episodes yet</p>
-            <p className="text-sm text-muted-foreground">Create your first AI-produced episode.</p>
-          </div>
-          <Button asChild>
-            <Link href="/episodes/new">
-              <Plus className="h-4 w-4" /> New episode
-            </Link>
-          </Button>
-        </div>
+        filtering ? (
+          <EmptyState
+            icon={Mic2}
+            title="No matching episodes"
+            description="Try a different search term or status filter."
+          />
+        ) : (
+          <EmptyState
+            icon={Mic2}
+            title="No episodes yet"
+            description="Create your first AI-produced episode."
+            action={
+              <Button asChild>
+                <Link href="/episodes/new">
+                  <Plus className="h-4 w-4" /> New episode
+                </Link>
+              </Button>
+            }
+          />
+        )
       ) : (
         <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
           {episodes.map((ep) => (