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

lib/__tests__/items-schema.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { createItemSchema } from "@/lib/items";
+
+describe("items API schema", () => {
+  it("accepts valid input (coerces numeric strings)", () => {
+    const result = createItemSchema.safeParse({ name: "Chair", quantity: "4" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ name: "Chair", quantity: 4 });
+    }
+  });
+
+  it("rejects empty name", () => {
+    const result = createItemSchema.safeParse({ name: "", quantity: 1 });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.flatten().fieldErrors.name).toBeTruthy();
+    }
+  });
+
+  it("rejects non-numeric quantity", () => {
+    const result = createItemSchema.safeParse({ name: "Chair", quantity: "abc" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects negative quantity", () => {
+    const result = createItemSchema.safeParse({ name: "Chair", quantity: -5 });
+    expect(result.success).toBe(false);
+  });
+});

lib/auth-client.ts

@@ -1,7 +1,8 @@
 import { createAuthClient } from "better-auth/react";
+import { env } from "@/lib/env";
 
 export const authClient = createAuthClient({
-  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL ?? "http://localhost:3000",
+  baseURL: env.NEXT_PUBLIC_BETTER_AUTH_URL,
 });
 
 export const { useSession, signIn, signUp, signOut } = authClient;

lib/env.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+const envSchema = z.object({
+  NEXT_PUBLIC_BETTER_AUTH_URL: z.string().url().default("http://localhost:3000"),
+});
+
+/**
+ * Validated public env vars. Uses .default() so missing vars don't throw at
+ * import time (keeps next build + CI safe); values fall back to dev defaults.
+ */
+const parsed = envSchema.safeParse({
+  NEXT_PUBLIC_BETTER_AUTH_URL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL,
+});
+
+export const env = parsed.success
+  ? parsed.data
+  : {
+      NEXT_PUBLIC_BETTER_AUTH_URL: "http://localhost:3000",
+    };
+
+export const isEnvValid = () => parsed.success;

lib/items.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export type Item = {
+  id: string;
+  name: string;
+  quantity: number;
+  createdAt: string;
+};
+
+export const createItemSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  quantity: z.coerce.number({ error: "Quantity must be a number" }).int().min(0).max(10000),
+});
+
+export type CreateItemInput = z.input<typeof createItemSchema>;
+export type CreateItemOutput = z.output<typeof createItemSchema>;
+
+export const MOCK_ITEMS: Item[] = [
+  { id: "1", name: "Ergonomic chair", quantity: 4, createdAt: "2026-09-01T08:00:00Z" },
+  { id: "2", name: "Mechanical keyboard", quantity: 12, createdAt: "2026-09-02T09:30:00Z" },
+  { id: "3", name: "USB-C dock", quantity: 7, createdAt: "2026-09-03T10:15:00Z" },
+  { id: "4", name: "Monitor arm", quantity: 3, createdAt: "2026-09-04T11:45:00Z" },
+];