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 });
+}