feat(web-ui): overhaul docs index, doc page, and sidebar with card-based layout

- Docs index: hero section with search bar, card grid with metadata/tags, recent strip
- Doc page: section badges, card-style related docs, improved revision history
- Sidebar: section icons, active state highlighting, better typography

apps/web/app/[section]/[...slug]/page.tsx

@@ -15,6 +15,20 @@ interface DocPageProps {
   searchParams: Promise<{ edit?: string }>;
 }
 
+const SECTION_LABEL: Record<string, string> = {
+  docs: "Documentation",
+  writeups: "Writeup",
+  research: "Research",
+  notes: "Note",
+};
+
+const SECTION_ICON: Record<string, string> = {
+  docs: "📄",
+  writeups: "📝",
+  research: "🔬",
+  notes: "📌",
+};
+
 export default async function DocPage({ params, searchParams }: DocPageProps) {
   const { section, slug } = await params;
   const { edit } = await searchParams;
@@ -60,8 +74,9 @@ export default async function DocPage({ params, searchParams }: DocPageProps) {
   const revisions = await listRevisions(fullSlug, 10);
 
   return (
-    <article>
+    <article className="prose-lg">
-      <div className="mb-2 flex items-center gap-2 text-xs text-[#62666d]">
+      {/* Breadcrumb */}
+      <nav className="flex items-center gap-2 text-xs text-[#62666d] mb-6">
         <Link
           href="/"
           className="hover:text-[#d0d6e0] transition-colors"
@@ -75,70 +90,103 @@ export default async function DocPage({ params, searchParams }: DocPageProps) {
         >
           Docs
         </Link>
-        {canEdit && (
+        <span>/</span>
-          <>
+        <span className="text-[#8a8f98]">{doc.title}</span>
-            <span>/</span>
+      </nav>
-            <Link
-              href={`/${doc.slug}?edit=1`}
-              className="hover:text-[#d0d6e0] text-[#8a8f98] hover:text-[#5e6ad2] transition-colors"
-            >
-              Edit
-            </Link>
-          </>
-        )}
-      </div>
 
-      <h1 className="text-3xl font-light text-[#f7f8f8] mb-2">{doc.title}</h1>
+      {/* Header */}
-
+      <div className="mb-8">
-      <div className="flex items-center gap-3 text-xs text-[#62666d] mb-6">
+        <div className="flex items-center gap-2 mb-3">
-        <span>{doc.author || "unknown"}</span>
+          <span className="text-xl">{SECTION_ICON[doc.section] || "📄"}</span>
-        <span>•</span>
+          <span className="text-xs font-medium text-[#7170ff] uppercase">
-        <span>{new Date(doc.updatedAt).toLocaleDateString()}</span>
+            {SECTION_LABEL[doc.section] || doc.section}
-        {doc.tags.map((t) => (
-          <span
-            key={t}
-            className="px-2 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
-          >
-            #{t}
           </span>
-        ))}
+        </div>
+        <h1 className="text-4xl font-medium text-[#f7f8f8] mb-4 leading-tight">
+          {doc.title}
+        </h1>
+
+        <div className="flex flex-wrap items-center gap-3 text-xs text-[#62666d] mb-6">
+          <span className="text-[#d0d6e0]">{doc.author || "unknown"}</span>
+          <span>·</span>
+          <time dateTime={doc.updatedAt}>
+            Updated {new Date(doc.updatedAt).toLocaleDateString(undefined, {
+              month: "long",
+              day: "numeric",
+              year: "numeric",
+            })}
+          </time>
+          {doc.tags.map((t) => (
+            <span
+              key={t}
+              className="px-2 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
+            >
+              #{t}
+            </span>
+          ))}
+        </div>
       </div>
 
+      {/* Content + TOC */}
       <div className="mb-8">
         <TOC source={doc.body} />
         <Markdown source={doc.body} />
       </div>
 
+      {/* Related docs (card-style) */}
       {related.length > 0 && (
-        <aside className="mt-12 pt-6 border-t border-[#1f2022]">
+        <aside className="mt-12 pt-8 border-t border-[#1f2022]">
-          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-3">
+          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-5">
-            Related
+            Related Documents
           </h2>
-          <ul className="space-y-2">
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
             {related.map((r) => (
-              <li key={r.slug}>
+              <Link
-                <Link
+                key={r.slug}
-                  href={`/${r.slug}`}
+                href={`/${r.slug}`}
-                  className="text-[#d0d6e0] hover:text-[#f7f8f8] transition-colors"
+                className="group block bg-[#0f1011] border border-[#1f2022] rounded-lg p-4 hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all duration-200"
-                >
+              >
+                <div className="flex items-start gap-2 mb-2">
+                  <span className="text-xl">
+                    {SECTION_ICON[r.section] || "📄"}
+                  </span>
+                  <time className="text-xs text-[#62666d]">
+                    {new Date(r.updatedAt).toLocaleDateString(undefined, {
+                      month: "short",
+                      day: "numeric",
+                    })}
+                  </time>
+                </div>
+                <h3 className="font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1 mb-1">
                   {r.title}
-                </Link>
+                </h3>
-              </li>
+                <div className="flex flex-wrap gap-1 mt-2">
+                  {r.tags.slice(0, 3).map((t) => (
+                    <span
+                      key={t}
+                      className="text-xs px-1.5 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
+                    >
+                      #{t}
+                    </span>
+                  ))}
+                </div>
+              </Link>
             ))}
-          </ul>
+          </div>
         </aside>
       )}
 
+      {/* History */}
       {revisions.length > 0 && (
-        <aside className="mt-12 pt-6 border-t border-[#1f2022]">
+        <aside className="mt-12 pt-8 border-t border-[#1f2022]">
-          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-3">
+          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-4">
-            History
+            Revision History
           </h2>
-          <ul className="text-sm">
+          <ul className="space-y-2 text-sm">
             {revisions.map((rev) => (
               <li
                 key={rev.id}
-                className="flex items-center justify-between gap-3 py-1.5 border-b border-[#141516]"
+                className="flex items-center justify-between gap-3 py-2 border-b border-[#141516] last:border-0"
               >
                 <span className="text-[#8a8f98]">
                   #{rev.revisionNo} · {rev.reason} ·{" "}
@@ -148,7 +196,7 @@ export default async function DocPage({ params, searchParams }: DocPageProps) {
                   <input type="hidden" name="id" value={rev.id} />
                   <button
                     type="submit"
-                    className="text-xs text-[#d0d6e0] hover:text-[#5e6ad2] px-2 py-0.5 rounded border border-[#1f2022] hover:border-[#5e6ad2] transition-colors"
+                    className="text-xs text-[#d0d6e0] hover:text-[#7170ff] px-2 py-0.5 rounded border border-[#1f2022] hover:border-[#7170ff] transition-colors"
                   >
                     Restore
                   </button>

apps/web/app/components/Sidebar.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from "react";
 import Link from "next/link";
+import { usePathname } from "next/navigation";
 
 interface Doc {
   slug: string;
@@ -11,16 +12,17 @@ interface Doc {
 }
 
 const SECTIONS = [
-  { id: "docs", label: "Documentation" },
+  { id: "docs", label: "Documentation", icon: "📄" },
-  { id: "writeups", label: "Writeups" },
+  { id: "writeups", label: "Writeups", icon: "📝" },
-  { id: "research", label: "Research" },
+  { id: "research", label: "Research", icon: "🔬" },
-  { id: "notes", label: "Notes" },
+  { id: "notes", label: "Notes", icon: "📌" },
 ] as const;
 
 /** Client-side sidebar (fetches doc list via /api/docs at runtime).
  *  Client component so `next build` SSG doesn't hit Postgres (CI has no DB). */
 export default function Sidebar() {
   const [docs, setDocs] = useState<Doc[]>([]);
+  const pathname = usePathname();
 
   useEffect(() => {
     fetch("/api/docs")
@@ -41,12 +43,25 @@ export default function Sidebar() {
   return (
     <nav className="h-full overflow-y-auto py-6">
       <ul className="space-y-1 px-3 text-sm">
-        {SECTIONS.map(({ id, label }) => {
+        {SECTIONS.map(({ id, label, icon }) => {
           const sectionDocs = bySection[id] || [];
           if (sectionDocs.length === 0) return null;
+
+          // Check if any doc in this section is the active page
+          const isActive = sectionDocs.some(
+            (doc) => pathname === `/${doc.slug}` || pathname === `/${doc.section}`,
+          );
+
           return (
             <li key={id}>
-              <div className="text-xs font-medium text-[#62666d] uppercase mb-1 mt-4 first:mt-0">
+              <div
+                className={`text-xs font-medium mb-1 mt-4 first:mt-0 flex items-center gap-1.5 ${
+                  isActive
+                    ? "text-[#7170ff]"
+                    : "text-[#62666d]"
+                }`}
+              >
+                <span>{icon}</span>
                 {label}
               </div>
               <ul className="space-y-0.5">
@@ -59,11 +74,19 @@ export default function Sidebar() {
                     .join(" ");
                   const depth = doc.slug.split("/").length;
                   const indent = depth - 1;
+                  const isDocActive = pathname === `/${doc.slug}`;
                   return (
-                    <li key={doc.slug} style={{ marginLeft: `${indent * 12}px` }}>
+                    <li
+                      key={doc.slug}
+                      style={{ marginLeft: `${indent * 12}px` }}
+                    >
                       <Link
                         href={`/${doc.slug}`}
-                        className="block text-[#d0d6e0] hover:text-[#f7f8f8] hover:bg-[#191a1b] rounded px-2 py-0.5 transition-colors"
+                        className={`block text-xs py-0.5 rounded transition-all ${
+                          isDocActive
+                            ? "text-[#7170ff] bg-[#191a1b]"
+                            : "text-[#d0d6e0] hover:text-[#f7f8f8] hover:bg-[#191a1b]"
+                        }`}
                         title={doc.title}
                       >
                         {formatted || doc.slug}

apps/web/app/docs/page.tsx

@@ -1,51 +1,185 @@
 import Link from "next/link";
 import { listDocuments } from "@mcpedia/core";
+import type { DocSection } from "@mcpedia/core";
 
 export const dynamic = "force-dynamic";
 
-const SECTIONS = [
+const SECTIONS: { id: DocSection; label: string }[] = [
   { id: "docs", label: "Documentation" },
   { id: "writeups", label: "Writeups" },
   { id: "research", label: "Research" },
   { id: "notes", label: "Notes" },
-] as const;
+];
+
+const SECTION_ICONS: Record<DocSection, string> = {
+  docs: "📄",
+  writeups: "📝",
+  research: "🔬",
+  notes: "📌",
+};
 
 export default async function DocsIndexPage() {
   const all = await listDocuments();
+
+  // Group by section, sort by updatedAt desc for recency
   const bySection = SECTIONS.map((section) => ({
     section,
-    docs: all.filter((d) => d.section === section.id),
+    docs: all
+      .filter((d) => d.section === section.id)
+      .sort(
+        (a, b) =>
+          new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+      ),
   }));
 
-  return (
+  // Flatten + sort all docs by updatedAt for the hero "recent" strip
-    <div>
+  const recent = [...all]
-      <h1 className="text-2xl font-light text-[#f7f8f8] mb-6">All Documents</h1>
+    .sort(
+      (a, b) =>
+        new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+    )
+    .slice(0, 6);
 
+  return (
+    <>
+      {/* Hero */}
+      <section className="mb-12">
+        <h1 className="text-4xl font-medium text-[#f7f8f8] mb-3">
+          MCPedia Knowledge Base
+        </h1>
+        <p className="text-lg text-[#8a8f98] max-w-2xl leading-relaxed">
+          A content-first knowledge base for humans and AI agents. Documents
+          covering MCP protocol, TypeScript, infrastructure, and security.
+        </p>
+
+        {/* Search bar */}
+        <div className="mt-8 relative max-w-2xl">
+          <svg
+            className="absolute left-3 top-1/2 -translate-y-1/2 w-5 h-5 text-[#62666d]"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+            />
+          </svg>
+          <input
+            type="text"
+            placeholder="Search documents, tags, authors..."
+            readOnly
+            className="w-full pl-10 pr-4 py-3 bg-[#191a1b] border border-[#1f2022] rounded-lg text-[#e2e4e7] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2]/30 transition-colors"
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && e.currentTarget.value) {
+                window.location.href = `/search?q=${encodeURIComponent(e.currentTarget.value)}`;
+              }
+            }}
+          />
+          <kbd className="absolute right-3 top-1/2 -translate-y-1/2 text-xs text-[#62666d] bg-[#0f1011] border border-[#1f2022] rounded px-1.5 py-0.5">
+            ↵
+          </kbd>
+        </div>
+
+        {/* Recent strip */}
+        {recent.length > 0 && (
+          <div className="mt-8 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+            {recent.map((d) => (
+              <Link
+                key={d.slug}
+                href={`/${d.slug}`}
+                className="group block bg-[#0f1011] border border-[#1f2022] rounded-lg p-4 hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all duration-200"
+              >
+                <div className="flex items-start justify-between gap-2 mb-2">
+                  <span className="text-2xl">
+                    {SECTION_ICONS[d.section] || "📄"}
+                  </span>
+                  <time className="text-xs text-[#62666d]">
+                    {new Date(d.updatedAt).toLocaleDateString(undefined, {
+                      month: "short",
+                      day: "numeric",
+                    })}
+                  </time>
+                </div>
+                <h3 className="font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1">
+                  {d.title}
+                </h3>
+                <div className="mt-2 flex flex-wrap gap-1">
+                  {d.tags.slice(0, 3).map((t) => (
+                    <span
+                      key={t}
+                      className="text-xs px-1.5 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
+                    >
+                      #{t}
+                    </span>
+                  ))}
+                </div>
+              </Link>
+            ))}
+          </div>
+        )}
+      </section>
+
+      {/* Sections */}
       {bySection.map(({ section, docs }) => {
         if (docs.length === 0) return null;
         return (
-          <section key={section.id} className="mb-10">
+          <section key={section.id} className="mb-12">
-            <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-4">
+            <div className="flex items-baseline justify-between mb-4">
-              {section.label}
+              <h2 className="text-sm font-medium text-[#d0d6e0] uppercase">
-            </h2>
+                {section.label}
-            <ul className="space-y-2">
+              </h2>
+              <Link
+                href={`/${section.id}`}
+                className="text-xs text-[#62666d] hover:text-[#7170ff] transition-colors"
+              >
+                View all ({docs.length})
+              </Link>
+            </div>
+
+            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
               {docs.map((d) => (
-                <li key={d.slug}>
+                <Link
-                  <Link
+                  key={d.slug}
-                    href={`/${d.slug}`}
+                  href={`/${d.slug}`}
-                    className="text-[#d0d6e0] hover:text-[#f7f8f8] transition-colors"
+                  className="group block bg-[#0f1011] border border-[#1f2022] rounded-lg p-5 hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all duration-200"
-                  >
+                >
+                  <div className="flex items-start justify-between gap-2 mb-3">
+                    <span className="text-2xl">
+                      {SECTION_ICONS[section.id] || "📄"}
+                    </span>
+                    <time className="text-xs text-[#62666d]">
+                      {new Date(d.updatedAt).toLocaleDateString(undefined, {
+                        month: "short",
+                        day: "numeric",
+                      })}
+                    </time>
+                  </div>
+                  <h3 className="font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1 mb-2">
                     {d.title}
-                  </Link>
+                  </h3>
-                  <span className="text-xs text-[#62666d] ml-2">
+                  <p className="text-xs text-[#8a8f98] mb-3 line-clamp-2">
+                    {d.author && `by ${d.author} · `}
                     {d.tags.slice(0, 2).map((t) => `#${t}`).join(" ") || "—"}
-                  </span>
+                  </p>
-                </li>
+                  <div className="flex flex-wrap gap-1">
+                    {d.tags.slice(0, 4).map((t) => (
+                      <span
+                        key={t}
+                        className="text-xs px-1.5 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
+                      >
+                        #{t}
+                      </span>
+                    ))}
+                  </div>
+                </Link>
               ))}
-            </ul>
+            </div>
           </section>
         );
       })}
-    </div>
+    </>
   );
 }