feat: close remaining gaps — middleware, demo wiring, error UX, env validation

- Auth: middleware.ts guards /protected via better-auth session cookie;
  protected page reads session server-side (auth.api.getSession)
- Demo wiring (app/demo + components/demo): react-markdown + remark-gfm +
  shiki CodeBlock, RHF+zod form with react-query mutation + sonner toast,
  react-table items list (legacy API, table v9), /api/items GET+POST
  (zod v4 coercion, schema in lib/items.ts shared with unit tests)
- Error UX: app/error.tsx (retry + digest), not-found.tsx (404), loading.tsx
- Env: lib/env.ts zod-validated (no import-time throw), .env.example sync
  (NEXT_PUBLIC_BETTER_AUTH_URL), auth-client uses env
- Tooling: @vitest/coverage-v8 (test:coverage works), tsconfig cleanup
  (drop .next/dev/dev/types artifact), README rewrite, demo e2e specs

app/api/items/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from "next/server";
+import { createItemSchema, MOCK_ITEMS, type Item, type CreateItemOutput } from "@/lib/items";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return NextResponse.json({ items: MOCK_ITEMS });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json().catch(() => null);
+  const parsed = createItemSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return NextResponse.json(
+      {
+        error: "Validation failed",
+        details: parsed.error.flatten().fieldErrors,
+      },
+      { status: 400 }
+    );
+  }
+
+  const input: CreateItemOutput = parsed.data;
+  const item: Item = {
+    id: crypto.randomUUID(),
+    ...input,
+    createdAt: new Date().toISOString(),
+  };
+
+  // In a real app: persist to DB here. MOCK_ITEMS is module-scoped, so the
+  // created item lives only for the lifetime of the server process.
+  MOCK_ITEMS.unshift(item);
+
+  return NextResponse.json({ item }, { status: 201 });
+}

app/demo/page.tsx

@@ -0,0 +1,61 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { CodeBlock } from "@/components/ui/code-block";
+import { DemoClient } from "@/components/demo/demo-client";
+
+const SAMPLE_MD = `# Demo Page
+
+This page shows the core wiring of the template:
+
+- **Server component** renders this markdown via \`react-markdown\` + \`remark-gfm\`
+- **Shiki** highlights code blocks server-side
+- **React Query** fetches \`/api/items\`
+- **React Hook Form + Zod** validates the "Add item" form
+- **better-auth** session is read on the server below
+
+## Code sample
+
+\`\`\`ts
+export function getGreeting(name: string): string {
+  return \`Hello, \${name}!\`;
+}
+\`\`\`
+
+> Tip: copy this page as a starting point for real features.
+`;
+
+export default function DemoPage() {
+  return (
+    <main className="mx-auto flex w-full max-w-3xl flex-1 flex-col gap-8 p-8">
+      <article className="prose prose-sm dark:prose-invert">
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          components={{
+            code(props) {
+              const { children, className, ...rest } = props;
+              const match = /language-(\w+)/.exec(className ?? "");
+              if (match) {
+                return (
+                  <CodeBlock
+                    code={String(children).replace(/\n$/, "")}
+                    lang={match[1]}
+                    className="my-4 overflow-x-auto rounded-lg border text-sm"
+                  />
+                );
+              }
+              return (
+                <code className={className} {...rest}>
+                  {children}
+                </code>
+              );
+            },
+          }}
+        >
+          {SAMPLE_MD}
+        </ReactMarkdown>
+      </article>
+
+      <DemoClient />
+    </main>
+  );
+}

app/error.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useEffect } from "react";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    console.error(error);
+  }, [error]);
+
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-4 p-8">
+      <h1 className="text-2xl font-semibold">Something went wrong</h1>
+      <p className="max-w-md text-center text-sm text-muted-foreground">
+        {error.message || "An unexpected error occurred."}
+      </p>
+      {error.digest ? (
+        <p className="font-mono text-xs text-muted-foreground">Error ID: {error.digest}</p>
+      ) : null}
+      <button
+        type="button"
+        onClick={() => reset()}
+        className="rounded-lg border bg-background px-4 py-2 text-sm font-medium hover:bg-muted"
+      >
+        Try again
+      </button>
+    </main>
+  );
+}

app/loading.tsx

@@ -0,0 +1,10 @@
+export default function Loading() {
+  return (
+    <div className="flex flex-1 items-center justify-center p-8" role="status">
+      <div className="flex items-center gap-3 text-sm text-muted-foreground">
+        <span className="size-4 animate-spin rounded-full border-2 border-foreground/20 border-t-foreground" />
+        Loading…
+      </div>
+    </div>
+  );
+}

app/not-found.tsx

@@ -0,0 +1,19 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-4 p-8">
+      <p className="text-5xl font-bold text-muted-foreground">404</p>
+      <h1 className="text-2xl font-semibold">Page not found</h1>
+      <p className="max-w-md text-center text-sm text-muted-foreground">
+        The page you are looking for does not exist or has been moved.
+      </p>
+      <Link
+        href="/"
+        className="rounded-lg border bg-background px-4 py-2 text-sm font-medium hover:bg-muted"
+      >
+        Back to home
+      </Link>
+    </main>
+  );
+}

app/page.tsx

@@ -1,4 +1,5 @@
 import Image from "next/image";
+import Link from "next/link";
 
 export default function Home() {
   return (
@@ -37,6 +38,12 @@ export default function Home() {
             </a>{" "}
             center.
           </p>
+          <Link
+            href="/demo"
+            className="rounded-full border border-black/[.08] bg-foreground px-5 py-2 text-sm font-medium text-background transition-colors hover:bg-[#383838] dark:border-white/[.145] dark:hover:bg-[#1a1a1a]"
+          >
+            View the demo wiring →
+          </Link>
         </div>
         <div className="flex flex-col gap-4 text-base font-medium sm:flex-row">
           <a

app/protected/page.tsx

@@ -0,0 +1,31 @@
+import { headers } from "next/headers";
+import { auth } from "@/lib/auth";
+import Link from "next/link";
+
+export const dynamic = "force-dynamic";
+
+export default async function ProtectedPage() {
+  const session = await auth.api.getSession({ headers: await headers() });
+
+  return (
+    <main className="mx-auto flex max-w-2xl flex-1 flex-col items-center justify-center gap-4 p-8">
+      <h1 className="text-2xl font-semibold">Protected Page</h1>
+      {session ? (
+        <div className="flex flex-col items-center gap-2 rounded-lg border p-6">
+          <p className="text-lg">
+            Welcome, <span className="font-medium">{session.user.name}</span>!{" "}
+            <span className="text-muted-foreground">({session.user.email})</span>
+          </p>
+          <p className="text-sm text-muted-foreground">
+            Session expires: {new Date(session.session.expiresAt).toLocaleString()}
+          </p>
+        </div>
+      ) : (
+        <p className="text-muted-foreground">No session found.</p>
+      )}
+      <Link href="/" className="text-sm text-primary underline-offset-4 hover:underline">
+        ← Back home
+      </Link>
+    </main>
+  );
+}