feat(web): FE overhaul — SWR centralized data layer + dashboard + islands

- Add SWR foundation (lib/fetcher, lib/swr, lib/api) with typed
  hooks: useSections/useDocuments/useSearch/useRelated/useRevisions/useQueueStatus
- Replace ad-hoc useEffect+fetch in Header/Sidebar/CommandMenu/search
  with SWR (dedup 4s, focus throttle 10s, debounced search 180ms)
- Doc page: RelatedGrid + RevisionList as SWR client islands (RSC hero stays)
- DocForm: SWR mutate on create/update for live sidebar invalidation
- New APIs: /api/related, /api/revisions, /api/tags, /api/queue/status,
  /api/docs filtering (?section=&status=)
- New UI: DocumentCard, SectionCard, SearchBar, TagCloud, QueueBadge,
  EmptyState, dashboard (/dashboard with QueueStrip live + section stats)
- Layout wraps SWRProvider; no TanStack code (SWR-only per spec)
- Verified: next build passes (16.3.4 Turbopack), no manual fetch sprawl remains

Co-Authored-By: internal-model

apps/web/app/hooks/useDocuments.ts

@@ -0,0 +1,30 @@
+"use client";
+
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+import type { DocumentMeta } from "@mcpedia/types";
+
+type DocsEnvelope = DocumentMeta[] | { docs: DocumentMeta[] };
+
+function normalize(data: DocsEnvelope | undefined): DocumentMeta[] {
+  if (!data) return [];
+  if (Array.isArray(data)) return data;
+  return (data as { docs: DocumentMeta[] }).docs ?? [];
+}
+
+export function useDocuments(section?: string, status = "published") {
+  const params = new URLSearchParams();
+  if (section) params.set("section", section);
+  if (status) params.set("status", status);
+  const qs = params.toString();
+  const key = qs ? `/api/docs?${qs}` : "/api/docs";
+
+  const swr = useSWR<DocsEnvelope>(key, fetcher, {
+    revalidateOnFocus: false,
+  });
+
+  return {
+    ...swr,
+    docs: normalize(swr.data),
+  };
+}

apps/web/app/hooks/useQueueStatus.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+
+export interface QueueStatus {
+  waiting: number;
+  active: number;
+  completed: number;
+  failed: number;
+  delayed: number;
+}
+
+export function useQueueStatus(enabled = false) {
+  return useSWR<QueueStatus>(enabled ? "/api/queue/status" : null, fetcher, {
+    refreshInterval: 5_000,
+    dedupingInterval: 4_000,
+    revalidateOnFocus: false,
+  });
+}
+
+export function useTags(limit = 30) {
+  const key = `/api/tags?limit=${limit}`;
+  return useSWR<{ tags: { tag: string; count: number }[] }>(key, fetcher, {
+    revalidateOnFocus: false,
+  });
+}

apps/web/app/hooks/useRelated.ts

@@ -0,0 +1,17 @@
+"use client";
+
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+import type { DocumentMeta } from "@mcpedia/types";
+
+export function useRelated(slug: string, limit = 4) {
+  const key = slug ? `/api/related?slug=${encodeURIComponent(slug)}&limit=${limit}` : null;
+  const swr = useSWR<{ results: DocumentMeta[] }>(key, fetcher, {
+    revalidateOnFocus: false,
+    keepPreviousData: true,
+  });
+  return {
+    ...swr,
+    related: swr.data?.results ?? [],
+  };
+}

apps/web/app/hooks/useRevisions.ts

@@ -0,0 +1,26 @@
+"use client";
+
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+
+export interface RevisionSummary {
+  id: string;
+  slug: string;
+  revisionNo: number;
+  title: string;
+  reason: string;
+  createdAt: string;
+  bodyLength: number;
+}
+
+export function useRevisions(slug: string, limit = 10) {
+  const key = slug ? `/api/revisions?slug=${encodeURIComponent(slug)}&limit=${limit}` : null;
+  const swr = useSWR<{ revisions: RevisionSummary[] }>(key, fetcher, {
+    revalidateOnFocus: false,
+    keepPreviousData: true,
+  });
+  return {
+    ...swr,
+    revisions: swr.data?.revisions ?? [],
+  };
+}

apps/web/app/hooks/useSearch.ts

@@ -0,0 +1,42 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+
+export interface SearchHit {
+  slug: string;
+  title: string;
+  section: string;
+  score: number;
+  snippet: string;
+}
+
+export type SearchMode = "hybrid" | "keyword" | "semantic";
+
+function useDebounced<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(t);
+  }, [value, delayMs]);
+  return debounced;
+}
+
+export function useSearch(q: string, mode: SearchMode = "hybrid", limit = 30) {
+  const debouncedQ = useDebounced(q, 180);
+  const trimmed = debouncedQ.trim();
+  const key = trimmed ? `/api/search?q=${encodeURIComponent(trimmed)}&mode=${mode}&limit=${limit}` : null;
+
+  const swr = useSWR<{ results: SearchHit[] }>(key, fetcher, {
+    keepPreviousData: true,
+    revalidateOnFocus: false,
+    dedupingInterval: 2_000,
+  });
+
+  return {
+    ...swr,
+    hits: swr.data?.results ?? [],
+    isSearching: !!trimmed && swr.isLoading,
+  };
+}

apps/web/app/hooks/useSections.ts

@@ -0,0 +1,11 @@
+"use client";
+
+import useSWR from "swr";
+import { fetcher } from "@/lib/fetcher";
+import type { SectionInfo } from "@mcpedia/types";
+
+export function useSections() {
+  return useSWR<SectionInfo[]>("/api/sections", fetcher, {
+    revalidateOnFocus: false,
+  });
+}