feat(ui): overhaul UI/UX with CommandMenu, modern Linear design, interactive TOC, and live preview

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

@@ -6,11 +6,11 @@ import { WEBHOOK_SECRET } from "@mcpedia/config";
 import Markdown from "@/components/Markdown";
 import DocForm from "@/components/DocForm";
 import TOC from "@/components/TOC";
+import DocActions from "@/components/DocActions";
 import { classifyPath, extractFoldersForSection } from "@mcpedia/core";
 import { SECTIONS_BY_ID } from "@mcpedia/config/sections";
 import type { DocumentMeta } from "@mcpedia/core";
 
-// Render at request time (content in Postgres, not available at build time).
 export const dynamic = "force-dynamic";
 
 interface DocPageProps {
@@ -18,9 +18,6 @@ interface DocPageProps {
   searchParams: Promise<{ edit?: string }>;
 }
 
-/**
- * Get section label and icon from the centralized config.
- */
 function getSectionInfo(section: string) {
   const info = SECTIONS_BY_ID.get(section);
   if (!info) {
@@ -35,12 +32,12 @@ function getSectionInfo(section: string) {
   };
 }
 
-/**
+function calculateReadingTime(text: string): string {
- * Render any extra/custom frontmatter fields as labeled badges.
+  const words = text.trim().split(/\s+/).length;
- * This makes the system dynamic — the content creator decides what metadata
+  const minutes = Math.ceil(words / 200);
- * to include. Standard fields (title, author, tags, etc.) are handled
+  return `${minutes} min read`;
- * explicitly; any OTHER keys in frontmatter become badges here.
+}
- */
+
 function CustomFieldBadges({
   doc,
   standardKeys,
@@ -57,61 +54,49 @@ function CustomFieldBadges({
   if (customEntries.length === 0) return null;
 
   return (
-    <div className="flex flex-wrap items-center gap-2 mt-4 pt-3 border-t border-[#1f2022]">
+    <div className="flex flex-wrap items-center gap-2 mt-4 pt-3.5 border-t border-[#1f2022]">
       {customEntries.map(([key, value]) => {
         const label = key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, " ");
-        let colorClass = "bg-[#191a1b] border-[#23252a] text-[#d0d6e0]";
+        let colorClass = "bg-[#141517] border-[#23252a] text-[#d0d6e0]";
+        let icon = "🏷️";
         let displayValue: string;
 
-        // --- Auto-detect styling based on VALUE TYPE + VALUE CONTENTS ---
-        // (NOT key name — content creators determine appearance via values,
-        //  not by using specific key names)
-
         if (typeof value === "number") {
           colorClass = "bg-[#5e6ad2]/10 border-[#5e6ad2]/30 text-[#7170ff]";
-          displayValue = `${value}`;
+          icon = "🎯";
+          displayValue = `${value} pts`;
         } else if (typeof value === "boolean") {
           colorClass = value
-            ? "bg-green-500/15 border-green-500/25 text-green-400"
+            ? "bg-emerald-500/10 border-emerald-500/30 text-emerald-400"
-            : "bg-red-500/15 border-red-500/25 text-red-400";
+            : "bg-rose-500/10 border-rose-500/30 text-rose-400";
-          displayValue = value ? "Yes" : "No";
+          icon = value ? "✓" : "✕";
+          displayValue = value ? "Solved" : "Pending";
         } else if (Array.isArray(value)) {
           colorClass = "bg-[#5e6ad2]/10 border-[#5e6ad2]/30 text-[#7170ff]";
+          icon = "🗂️";
           displayValue = value.join(", ");
-        } else if (typeof value === "object" && value !== null) {
-          displayValue = JSON.stringify(value).slice(0, 40) +
-            (JSON.stringify(value).length > 40 ? "…" : "");
         } else {
           const v = String(value).toLowerCase();
-
+          if (/^(easy|simple|beginner)/i.test(v)) {
-          const diffMatch = v.match(
+            colorClass = "bg-emerald-500/10 border-emerald-500/30 text-emerald-400";
-            /^(easy|simple|beginner)\b|^(medium|intermediate)\b|^(hard|expert|advanced)\b/i,
+            icon = "🟢";
-          );
+            displayValue = "Easy";
-          if (diffMatch) {
+          } else if (/^(medium|intermediate)/i.test(v)) {
-            if (/^easy|simple|beginner/i.test(v))
+            colorClass = "bg-amber-500/10 border-amber-500/30 text-amber-400";
-              colorClass = "bg-green-500/10 border-green-500/30 text-green-400";
+            icon = "🟡";
-            else if (/^medium|intermediate/i.test(v))
+            displayValue = "Medium";
-              colorClass = "bg-yellow-500/10 border-yellow-500/30 text-yellow-400";
+          } else if (/^(hard|expert|advanced)/i.test(v)) {
-            else if (/^hard|expert|advanced/i.test(v))
+            colorClass = "bg-rose-500/10 border-rose-500/30 text-rose-400";
-              colorClass = "bg-red-500/10 border-red-500/30 text-red-400";
+            icon = "🔴";
-            displayValue = diffMatch[0];
+            displayValue = "Hard";
-          } else if (/ctf|def.?con|hack|game|competition|tournament|qualifier/i.test(v)) {
+          } else if (/^(pwn|web|crypto|misc|forensic|reverse|binary)/i.test(v)) {
+            colorClass = "bg-indigo-500/10 border-indigo-500/30 text-indigo-300";
+            icon = "⚡";
+            displayValue = v.toUpperCase();
+          } else if (/ctf|def.?con|event/i.test(v)) {
             colorClass = "bg-[#5e6ad2]/10 border-[#5e6ad2]/30 text-[#7170ff]";
+            icon = "🏆";
             displayValue = String(value);
-          } else if (/(\d+)\s*pts?$/i.test(v)) {
-            const match = v.match(/(\d+)\s*pts?$/i);
-            colorClass = "bg-[#5e6ad2]/10 border-[#5e6ad2]/30 text-[#7170ff]";
-            displayValue = match ? `${match[1]} pts` : String(value);
-          } else if (/^(pwn|web|crypto|misc|forensic|reverse|pwnable|binary|webexploit)$/i.test(v)) {
-            colorClass = "bg-orange-500/15 border-orange-500/25 text-orange-400";
-            displayValue = v.charAt(0).toUpperCase() + v.slice(1);
-          } else if (/^(solved|pending|wip|in.?progress|completed|todo)$/i.test(v)) {
-            colorClass = v.includes("solved") || v.includes("completed")
-              ? "bg-green-500/10 border-green-500/30 text-green-400"
-              : v.includes("wip") || v.includes("progress")
-                ? "bg-yellow-500/10 border-yellow-500/30 text-yellow-400"
-                : "bg-red-500/10 border-red-500/30 text-red-400";
-            displayValue = v.charAt(0).toUpperCase() + v.slice(1);
           } else {
             displayValue = String(value);
           }
@@ -120,10 +105,11 @@ function CustomFieldBadges({
         return (
           <span
             key={key}
-            className={`px-2 py-0.5 border rounded text-xs ${colorClass}`}
+            className={`inline-flex items-center gap-1.5 px-2.5 py-1 border rounded-md text-xs font-mono transition-colors ${colorClass}`}
-            title={label}
           >
-            {displayValue}
+            <span className="text-[10px] opacity-70">{icon}</span>
+            <span className="text-[#8a8f98] font-sans">{label}:</span>
+            <span className="font-medium">{displayValue}</span>
           </span>
         );
       })}
@@ -131,10 +117,6 @@ function CustomFieldBadges({
   );
 }
 
-/**
- * Folder index page — lists all docs (and subfolders) whose path starts with
- * the given prefix. This enables GitHub-style nested folder browsing.
- */
 function FolderIndexPage({
   section,
   slug,
@@ -153,7 +135,6 @@ function FolderIndexPage({
     }))
     .sort((a, b) => a.rel.localeCompare(b.rel));
 
-  // Group into immediate children: folders vs leaf docs
   const immediateFolders = new Map<string, { docCount: number }>();
   const immediateDocs: DocumentMeta[] = [];
 
@@ -170,129 +151,136 @@ function FolderIndexPage({
   }
 
   const folders = [...immediateFolders.entries()].sort(([a], [b]) => a.localeCompare(b));
-
   const sectionInfo = getSectionInfo(section);
+  const folderName = slug.split("/").pop()!.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 
   return (
     <div>
       {/* Breadcrumb */}
-      <nav className="flex items-center gap-2 text-xs text-[#62666d] mb-6">
+      <nav className="flex items-center gap-2 text-xs text-[#62666d] mb-6 flex-wrap">
         <Link href="/" className="hover:text-[#d0d6e0] transition-colors">
           MCPedia
         </Link>
         <span>/</span>
-        <Link
+        <Link href={`/${section}`} className="hover:text-[#d0d6e0] transition-colors">
-          href={`/${section}`}
-          className="hover:text-[#d0d6e0] transition-colors"
-        >
           {sectionInfo.label}
         </Link>
         {slug.split("/").map((part, i) => {
           const path = `${section}/${slug.split("/").slice(0, i + 1).join("/")}`;
           const isLast = i === slug.split("/").length - 1;
-          const label = part
+          const label = part.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-            .split(/[-_]/)
-            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-            .join(" ");
           return (
-            <>
+            <span key={path} className="flex items-center gap-2">
               <span>/</span>
-              <span
+              <span className={isLast ? "text-[#8a8f98] font-medium" : "hover:text-[#d0d6e0]"}>
-                key={path}
-                className={isLast ? "text-[#8a8f98]" : "hover:text-[#d0d6e0]"}
-              >
                 {label}
               </span>
-            </>
+            </span>
           );
         })}
       </nav>
 
-      {/* Header */}
+      {/* Header card */}
-      <div className="flex items-center gap-2 mb-8">
+      <div className="bg-[#0f1011] border border-[#1f2022] rounded-xl p-6 mb-8">
-        <span className="text-2xl">📁</span>
+        <div className="flex items-center justify-between gap-4">
-        <h1 className="text-3xl font-medium text-[#f7f8f8]">
+          <div className="flex items-center gap-3">
-          {slug.split("/").pop()!.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
+            <div className="w-10 h-10 rounded-lg bg-[#141517] border border-[#23252a] flex items-center justify-center text-xl">
-        </h1>
+              📁
-        <span className="text-xs text-[#62666d] bg-[#191a1b] px-2 py-0.5 rounded">
+            </div>
-          {immediateDocs.length + folders.length} item{folders.length + immediateDocs.length !== 1 ? "s" : ""}
+            <div>
-        </span>
+              <h1 className="text-2xl sm:text-3xl font-semibold text-[#f7f8f8] tracking-tight">
+                {folderName}
+              </h1>
+              <p className="text-xs text-[#8a8f98] mt-0.5">
+                Directory path: <code className="text-[#7170ff] font-mono">{section}/{slug}</code>
+              </p>
+            </div>
+          </div>
+          <span className="text-xs font-mono text-[#8a8f98] bg-[#141517] border border-[#23252a] px-2.5 py-1 rounded-md">
+            {immediateDocs.length + folders.length} item{folders.length + immediateDocs.length !== 1 ? "s" : ""}
+          </span>
+        </div>
       </div>
 
-      {(folders.length > 0 || immediateDocs.length > 0) ? (
+      {/* Subfolders */}
+      {folders.length > 0 && (
+        <div className="mb-8">
+          <h2 className="text-xs font-semibold text-[#8a8f98] uppercase mb-3 tracking-wider flex items-center gap-2">
+            <span>Subfolders</span>
+            <span className="text-[10px] text-[#62666d]">({folders.length})</span>
+          </h2>
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+            {folders.map(([folder, info]) => (
+              <Link
+                key={folder}
+                href={`/${section}/${slug}/${folder}`.replace(/\/+/g, "/")}
+                className="group flex items-center gap-3 p-3.5 bg-[#0f1011] hover:bg-[#141517] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-lg transition-all shadow-sm"
+              >
+                <span className="text-2xl group-hover:scale-110 transition-transform">📁</span>
+                <div className="flex-1 min-w-0">
+                  <div className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors truncate">
+                    {folder.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
+                  </div>
+                  <div className="text-xs text-[#62666d] mt-0.5 font-mono">
+                    {info.docCount} document{info.docCount !== 1 ? "s" : ""}
+                  </div>
+                </div>
+              </Link>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Documents */}
+      {immediateDocs.length > 0 && (
         <div>
-          {folders.length > 0 && (
+          <h2 className="text-xs font-semibold text-[#8a8f98] uppercase mb-3 tracking-wider flex items-center gap-2">
-            <div className="mb-8">
+            <span>Documents</span>
-              <h2 className="text-xs font-medium text-[#8a8f98] uppercase mb-3 tracking-wider">
+            <span className="text-[10px] text-[#62666d]">({immediateDocs.length})</span>
-                Subfolders
+          </h2>
-              </h2>
+          <div className="space-y-2">
-              <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+            {immediateDocs.map((doc) => (
-                {folders.map(([folder, info]) => (
+              <Link
-                  <Link
+                key={doc.slug}
-                    key={folder}
+                href={`/${doc.slug}`}
-                    href={`/${section}/${slug}/${folder}`.replace(/\/+/g, "/")}
+                className="group flex items-center justify-between gap-4 p-4 bg-[#0f1011] hover:bg-[#141517] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-lg transition-all shadow-sm"
-                    className="group flex items-center gap-3 p-3 bg-[#0f1011] border border-[#1f2022] rounded-lg hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all"
+              >
-                  >
+                <div className="flex items-center gap-3 min-w-0">
-                    <span className="text-2xl">📁</span>
+                  <span className="text-xl opacity-70 group-hover:opacity-100">📄</span>
-                    <div className="flex-1 min-w-0">
+                  <div className="min-w-0">
-                      <div className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors">
+                    <div className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors truncate">
-                        {folder.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
+                      {doc.title}
-                      </div>
-                      <div className="text-xs text-[#62666d] mt-0.5">
-                        {info.docCount} document{info.docCount !== 1 ? "s" : ""}
-                      </div>
                     </div>
-                  </Link>
+                    {doc.tags.length > 0 && (
-                ))}
+                      <div className="flex flex-wrap gap-1.5 mt-1.5">
-              </div>
+                        {doc.tags.slice(0, 4).map((t) => (
-            </div>
+                          <span
-          )}
+                            key={t}
-          {immediateDocs.length > 0 && (
+                            className="text-[11px] px-1.5 py-0.25 bg-[#141517] border border-[#23252a] rounded text-[#8a8f98]"
-            <div>
+                          >
-              <h2 className="text-xs font-medium text-[#8a8f98] uppercase mb-3 tracking-wider">
+                            #{t}
-                Documents
+                          </span>
-              </h2>
+                        ))}
-              <div className="space-y-2">
-                {immediateDocs.map((doc) => (
-                  <Link
-                    key={doc.slug}
-                    href={`/${doc.slug}`}
-                    className="group flex items-center justify-between gap-3 p-3 bg-[#0f1011] border border-[#1f2022] rounded-lg hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all"
-                  >
-                    <div className="flex items-center gap-3 min-w-0">
-                      <span className="text-xl">📄</span>
-                      <div className="min-w-0">
-                        <div className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1">
-                          {doc.title}
-                        </div>
-                        {doc.tags.length > 0 && (
-                          <div className="flex flex-wrap gap-1 mt-1">
-                            {doc.tags.slice(0, 3).map((t) => (
-                              <span
-                                key={t}
-                                className="text-xs px-1.5 py-0.25 bg-[#191a1b] border border-[#23252a] rounded text-[#8a8f98]"
-                              >
-                                #{t}
-                              </span>
-                            ))}
-                          </div>
-                        )}
                       </div>
-                    </div>
+                    )}
-                    <time className="text-xs text-[#62666d] flex-shrink-0">
+                  </div>
-                      {new Date(doc.updatedAt).toLocaleDateString(undefined, {
+                </div>
-                        month: "short",
+                <time className="text-xs text-[#62666d] shrink-0 font-mono">
-                        day: "numeric",
+                  {new Date(doc.updatedAt).toLocaleDateString(undefined, {
-                      })}
+                    month: "short",
-                    </time>
+                    day: "numeric",
-                  </Link>
+                  })}
-                ))}
+                </time>
-              </div>
+              </Link>
-            </div>
+            ))}
-          )}
+          </div>
+        </div>
+      )}
+
+      {folders.length === 0 && immediateDocs.length === 0 && (
+        <div className="text-center py-12 border border-[#1f2022] rounded-xl bg-[#0f1011]">
+          <p className="text-sm text-[#8a8f98]">No documents found in this directory.</p>
         </div>
-      ) : (
-        <p className="text-sm text-[#62666d]">No documents found in this folder.</p>
       )}
     </div>
   );
@@ -303,44 +291,37 @@ export default async function DocPage({ params, searchParams }: DocPageProps) {
   const { edit } = await searchParams;
   const fullSlug = `${section}/${slug.join("/")}`;
 
-  // Fetch all docs to classify the path as "doc" or "folder"
   const allDocs = await listDocuments();
   const docPaths = allDocs.map((d) => d.path);
-
   const classification = classifyPath(docPaths, fullSlug);
 
-  // If the slug path is a folder (not a leaf doc), render the folder index
   if (classification === "folder") {
     return <FolderIndexPage section={section} slug={slug.join("/")} allDocs={allDocs} />;
   }
 
-  // Otherwise, treat as a document (existing behavior)
   const doc = await getDocument(fullSlug);
   if (!doc) notFound();
 
   const cookieStore = await cookies();
   const canEdit = cookieStore.get("mcpedia_admin")?.value != null;
 
-  // Standard frontmatter keys that are rendered explicitly in the template.
-  // Any other key in the document metadata becomes a dynamic badge.
   const STANDARD_KEYS = new Set([
     "id", "slug", "title", "type", "section", "status",
     "author", "tags", "path", "createdAt", "updatedAt",
     "extraFields", "body",
   ]);
 
-  // Edit mode: inline form
   if (edit === "1" && canEdit) {
     const existingFolders = extractFoldersForSection(docPaths, doc.section);
     return (
       <div>
         <Link
           href={`/${doc.slug}`}
-          className="text-xs text-[#8a8f98] hover:text-[#d0d6e0] mb-4 inline-block"
+          className="inline-flex items-center gap-1 text-xs text-[#8a8f98] hover:text-[#d0d6e0] mb-4 transition-colors"
         >
-          ← Back to {doc.title}
+          <span>← Back to document</span>
         </Link>
-        <h1 className="text-2xl font-light text-[#f7f8f8] mb-6">
+        <h1 className="text-2xl font-semibold text-[#f7f8f8] mb-6">
           Edit: {doc.title}
         </h1>
         <DocForm
@@ -365,189 +346,199 @@ export default async function DocPage({ params, searchParams }: DocPageProps) {
     );
   }
 
-  const related = await getRelated(fullSlug, 5);
+  const related = await getRelated(fullSlug, 4);
   const revisions = await listRevisions(fullSlug, 10);
-
   const sectionInfo = getSectionInfo(doc.section);
+  const readingTime = calculateReadingTime(doc.body);
 
   return (
-    <article>
+    <div className="flex items-start gap-8">
-      {/* Breadcrumb — dynamic based on the doc's actual path */}
+      {/* Main Content Column */}
-      <nav className="flex items-center gap-2 text-xs text-[#62666d] mb-6">
+      <article className="flex-1 min-w-0">
-        <Link
+        {/* Breadcrumb */}
-          href="/"
+        <nav className="flex items-center gap-2 text-xs text-[#62666d] mb-4 flex-wrap">
-          className="hover:text-[#d0d6e0] transition-colors"
+          <Link href="/" className="hover:text-[#d0d6e0] transition-colors">
-        >
+            MCPedia
-          MCPedia
+          </Link>
-        </Link>
+          {doc.slug.split("/").map((part, i) => {
-        {doc.slug.split("/").map((part, i) => {
+            const crumbPath = doc.slug.split("/").slice(0, i + 1).join("/");
-          const crumbPath = doc.slug.split("/").slice(0, i + 1).join("/");
+            const isLast = i === doc.slug.split("/").length - 1;
-          const isLast = i === doc.slug.split("/").length - 1;
+            const label = i === 0
-          const label = i === 0
+              ? sectionInfo.label
-            ? sectionInfo.label
+              : part.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-            : part
+            return (
-                .split(/[-_]/)
+              <span key={crumbPath} className="flex items-center gap-2">
-                .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                <span>/</span>
-                .join(" ");
-          return (
-            <>
-              <span>/</span>
-              <Link
-                key={crumbPath}
-                href={`/${crumbPath}`}
-                className={
-                  isLast
-                    ? "text-[#8a8f98]"
-                    : "hover:text-[#d0d6e0] transition-colors"
-                }
-              >
-                {label}
-              </Link>
-            </>
-          );
-        })}
-      </nav>
-
-      {/* Metadata Card */}
-      <div className="bg-[#0f1011] border border-[#1f2022] rounded-lg p-6 mb-8">
-        <div className="flex items-start gap-3 mb-4">
-          <span className="text-2xl">
-            {sectionInfo.icon}
-          </span>
-          <div className="flex-1 min-w-0">
-            <div className="flex items-center gap-2 mb-2">
-              <span className="text-xs font-medium text-[#7170ff] uppercase">
-                {sectionInfo.label}
-              </span>
-              <span className="text-xs text-[#62666d]">·</span>
-              <span className="text-xs text-[#62666d]">
-                {doc.type}
-              </span>
-            </div>
-            <h1 className="text-3xl font-medium text-[#f7f8f8] leading-tight">
-              {doc.title}
-            </h1>
-          </div>
-        </div>
-
-        {/* Author + date + tags */}
-        <div className="flex flex-wrap items-center gap-3 text-xs text-[#62666d] mb-3">
-          {doc.author && (
-            <>
-              <span className="text-[#d0d6e0]">by {doc.author}</span>
-              <span>·</span>
-            </>
-          )}
-          <span className="text-[#d0d6e0]">
-            updated {new Date(doc.updatedAt).toLocaleDateString(undefined, {
-              month: "long",
-              day: "numeric",
-              year: "numeric",
-            })}
-          </span>
-          {doc.tags.length > 0 && (
-            <>
-              <span>·</span>
-              <div className="flex flex-wrap gap-1">
-                {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>
-
-        {/* Dynamic custom field badges — content creator controls what shows */}
-        <CustomFieldBadges doc={{ ...doc }} standardKeys={STANDARD_KEYS} />
-      </div>
-
-      {/* Content + TOC */}
-      <div className="mb-12">
-        <TOC source={doc.body} />
-        <Markdown source={doc.body} />
-      </div>
-
-      {/* Related docs (card-style) */}
-      {related.length > 0 && (
-        <aside className="mt-12 pt-8 border-t border-[#1f2022]">
-          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-5">
-            Related Documents
-          </h2>
-          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-            {related.map((r) => {
-              const rInfo = getSectionInfo(r.section);
-              return (
                 <Link
-                  key={r.slug}
+                  href={`/${crumbPath}`}
-                  href={`/${r.slug}`}
+                  className={isLast ? "text-[#8a8f98] font-medium" : "hover:text-[#d0d6e0] 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">
+                  {label}
-                    <span className="text-xl">
-                      {rInfo.icon}
-                    </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}
-                  </h3>
-                  <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>
-              );
+              </span>
-            })}
+            );
-          </div>
+          })}
-        </aside>
+        </nav>
-      )}
 
-      {/* History */}
+        {/* Hero Metadata Card */}
-      {revisions.length > 0 && (
+        <div className="bg-[#0f1011] border border-[#1f2022] rounded-xl p-6 mb-8 shadow-sm">
-        <aside className="mt-12 pt-8 border-t border-[#1f2022]">
+          <div className="flex flex-col sm:flex-row sm:items-start justify-between gap-4 mb-4">
-          <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-4">
+            <div className="flex-1 min-w-0">
-            Revision History
+              <div className="flex items-center gap-2 mb-2 flex-wrap">
-          </h2>
+                <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded text-xs font-mono font-medium bg-[#5e6ad2]/15 text-[#7170ff] border border-[#5e6ad2]/30">
-          <ul className="space-y-2 text-sm">
+                  <span>{sectionInfo.icon}</span>
-            {revisions.map((rev) => (
+                  <span className="uppercase">{sectionInfo.label}</span>
-              <li
-                key={rev.id}
-                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} ·{" "}
-                  {new Date(rev.createdAt).toLocaleString()}
                 </span>
-                <form action="/api/revisions/restore" method="post">
+                <span className="text-xs text-[#62666d]">·</span>
-                  <input type="hidden" name="id" value={rev.id} />
+                <span className="text-xs text-[#8a8f98] capitalize">
-                  <button
+                  {doc.type}
-                    type="submit"
+                </span>
-                    className="text-xs text-[#d0d6e0] hover:text-[#7170ff] px-2 py-0.5 rounded border border-[#1f2022] hover:border-[#7170ff] transition-colors"
+                <span className="text-xs text-[#62666d]">·</span>
+                <span className="text-xs text-[#8a8f98] font-mono">
+                  {readingTime}
+                </span>
+              </div>
+              <h1 className="text-2xl sm:text-3xl font-semibold text-[#f7f8f8] tracking-tight leading-tight">
+                {doc.title}
+              </h1>
+            </div>
+
+            {/* Quick Actions */}
+            <DocActions slug={doc.slug} body={doc.body} canEdit={canEdit} />
+          </div>
+
+          {/* Author + Date + Tags */}
+          <div className="flex flex-wrap items-center gap-3 text-xs text-[#8a8f98] pt-3 border-t border-[#1a1b1d]">
+            {doc.author && (
+              <div className="flex items-center gap-1.5">
+                <div className="w-4 h-4 rounded-full bg-[#5e6ad2] text-white flex items-center justify-center text-[10px] font-bold">
+                  {doc.author.charAt(0).toUpperCase()}
+                </div>
+                <span className="text-[#d0d6e0]">{doc.author}</span>
+                <span className="text-[#62666d]">·</span>
+              </div>
+            )}
+            <span>
+              Updated {new Date(doc.updatedAt).toLocaleDateString(undefined, {
+                month: "long",
+                day: "numeric",
+                year: "numeric",
+              })}
+            </span>
+            {doc.tags.length > 0 && (
+              <>
+                <span className="text-[#62666d]">·</span>
+                <div className="flex flex-wrap gap-1">
+                  {doc.tags.map((t) => (
+                    <span
+                      key={t}
+                      className="px-2 py-0.5 bg-[#141517] border border-[#23252a] rounded text-[#8a8f98] text-[11px]"
+                    >
+                      #{t}
+                    </span>
+                  ))}
+                </div>
+              </>
+            )}
+          </div>
+
+          {/* Dynamic Badges */}
+          <CustomFieldBadges doc={{ ...doc }} standardKeys={STANDARD_KEYS} />
+        </div>
+
+        {/* Mobile TOC (rendered inline on smaller screens) */}
+        <div className="xl:hidden mb-6 p-4 bg-[#0f1011] border border-[#1f2022] rounded-lg">
+          <TOC source={doc.body} />
+        </div>
+
+        {/* Markdown content */}
+        <div className="mb-14">
+          <Markdown source={doc.body} />
+        </div>
+
+        {/* Related Documents */}
+        {related.length > 0 && (
+          <aside className="mt-12 pt-8 border-t border-[#1f2022]">
+            <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider mb-4 flex items-center gap-2">
+              <span>Related Knowledge</span>
+            </h2>
+            <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
+              {related.map((r) => {
+                const rInfo = getSectionInfo(r.section);
+                return (
+                  <Link
+                    key={r.slug}
+                    href={`/${r.slug}`}
+                    className="group block bg-[#0f1011] hover:bg-[#141517] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-lg p-4 transition-all shadow-sm"
                   >
-                    Restore
+                    <div className="flex items-center justify-between gap-2 mb-2">
-                  </button>
+                      <span className="text-xs text-[#7170ff] font-mono uppercase">
-                </form>
+                        {rInfo.icon} {r.section}
-              </li>
+                      </span>
-            ))}
+                      <time className="text-[11px] text-[#62666d] font-mono">
-          </ul>
+                        {new Date(r.updatedAt).toLocaleDateString(undefined, {
-        </aside>
+                          month: "short",
-      )}
+                          day: "numeric",
-    </article>
+                        })}
+                      </time>
+                    </div>
+                    <h3 className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1 mb-1">
+                      {r.title}
+                    </h3>
+                  </Link>
+                );
+              })}
+            </div>
+          </aside>
+        )}
+
+        {/* Revision History */}
+        {revisions.length > 0 && (
+          <aside className="mt-10 pt-8 border-t border-[#1f2022]">
+            <div className="flex items-center justify-between mb-4">
+              <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider">
+                Revision History ({revisions.length})
+              </h2>
+            </div>
+            <div className="space-y-2">
+              {revisions.map((rev) => (
+                <div
+                  key={rev.id}
+                  className="flex items-center justify-between gap-3 p-3 bg-[#0f1011] border border-[#1f2022] rounded-lg text-xs"
+                >
+                  <div className="flex items-center gap-2 min-w-0">
+                    <span className="font-mono text-[#7170ff] bg-[#5e6ad2]/10 px-1.5 py-0.5 rounded border border-[#5e6ad2]/30">
+                      v{rev.revisionNo}
+                    </span>
+                    <span className="text-[#d0d6e0] truncate">
+                      {rev.reason || "Updated document"}
+                    </span>
+                    <span className="text-[#62666d] hidden sm:inline">
+                      · {new Date(rev.createdAt).toLocaleString()}
+                    </span>
+                  </div>
+                  {canEdit && (
+                    <form action="/api/revisions/restore" method="post">
+                      <input type="hidden" name="id" value={rev.id} />
+                      <button
+                        type="submit"
+                        className="text-xs text-[#d0d6e0] hover:text-white bg-[#141517] hover:bg-[#23252a] px-2.5 py-1 rounded border border-[#23252a] hover:border-[#5e6ad2] transition-colors"
+                      >
+                        Restore
+                      </button>
+                    </form>
+                  )}
+                </div>
+              ))}
+            </div>
+          </aside>
+        )}
+      </article>
+
+      {/* Desktop Sticky Table of Contents Column */}
+      <aside className="hidden xl:block w-64 shrink-0 sticky top-20 max-h-[calc(100vh-6rem)] overflow-y-auto pl-6 border-l border-[#1f2022]">
+        <TOC source={doc.body} />
+      </aside>
+    </div>
   );
 }

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

@@ -13,16 +13,12 @@ interface DocMeta {
   path: string;
 }
 
-/**
- * Build a hierarchical folder tree from a flat list of documents.
- * Each node is either a folder (has children) or a leaf doc.
- */
 interface TreeNode {
   name: string;
   slug: string;
   doc?: DocMeta;
   children: TreeNode[];
-  docCount: number; // total docs in subtree
+  docCount: number;
 }
 
 function buildFolderTree(docs: DocMeta[], section: string): TreeNode[] {
@@ -62,7 +58,6 @@ function buildFolderTree(docs: DocMeta[], section: string): TreeNode[] {
     }
   }
 
-  // Recursively compute docCount for folder nodes
   function countDocs(node: TreeNode): number {
     if (node.doc) return 1;
     return node.children.reduce((sum, child) => sum + countDocs(child), 0);
@@ -77,7 +72,7 @@ function buildFolderTree(docs: DocMeta[], section: string): TreeNode[] {
 
 function renderTree(nodes: TreeNode[], pathname: string) {
   return (
-    <ul className="space-y-0.5">
+    <ul className="space-y-1">
       {nodes.map((node) => {
         const isFolder = node.children.length > 0;
         const isActive = pathname === `/${node.slug}`;
@@ -87,26 +82,26 @@ function renderTree(nodes: TreeNode[], pathname: string) {
           <li key={node.slug}>
             <Link
               href={`/${node.slug}`}
-              className={`flex items-center justify-between gap-2 text-xs py-1 px-2 rounded transition-all ${
+              className={`flex items-center justify-between gap-2 text-xs py-1.5 px-2.5 rounded-lg transition-all ${
                 isActive
-                  ? "text-[#7170ff] bg-[#191a1b]"
+                  ? "text-[#7170ff] bg-[#5e6ad2]/15 font-medium border border-[#5e6ad2]/30"
                   : hasActiveChild
-                    ? "text-[#d0d6e0]"
+                    ? "text-[#d0d6e0] bg-[#141517]"
-                    : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#191a1b]"
+                    : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#141517]"
               }`}
             >
-              <span className="flex items-center gap-1.5">
+              <span className="flex items-center gap-2 truncate">
                 <span>{isFolder ? "📁" : "📄"}</span>
-                {node.doc?.title || node.name}
+                <span className="truncate">{node.doc?.title || node.name}</span>
               </span>
               {isFolder && (
-                <span className="text-[#62666d] bg-[#191a1b] px-1.5 py-0.25 rounded">
+                <span className="text-[10px] text-[#62666d] bg-[#191a1b] px-1.5 py-0.5 rounded font-mono">
-                  {node.docCount}
+                  {node.docCount} docs
                 </span>
               )}
             </Link>
             {node.children.length > 0 && (
-              <div className="ml-4 mt-0.5">
+              <div className="ml-4 border-l border-[#1f2022] pl-2 mt-1">
                 {renderTree(node.children, pathname)}
               </div>
             )}
@@ -127,8 +122,9 @@ export default async function SectionIndexPage({
   const sectionInfo = SECTIONS.find((s) => s.id === section);
   if (!sectionInfo) {
     return (
-      <div>
+      <div className="py-12 text-center">
-        <h1 className="text-2xl font-medium text-[#f7f8f8]">Unknown section</h1>
+        <h1 className="text-2xl font-semibold text-[#f7f8f8]">Unknown section</h1>
+        <p className="text-sm text-[#8a8f98] mt-2">Section &quot;{section}&quot; does not exist.</p>
       </div>
     );
   }
@@ -138,34 +134,66 @@ export default async function SectionIndexPage({
   const tree = buildFolderTree(allDocs, section);
 
   return (
-    <div>
+    <div className="space-y-10">
-      <div className="flex items-center gap-2 mb-6">
+      {/* Breadcrumb */}
-        <span className="text-2xl">{sectionInfo.icon}</span>
+      <nav className="flex items-center gap-2 text-xs text-[#62666d]">
-        <h1 className="text-3xl font-medium text-[#f7f8f8]">{sectionInfo.label}</h1>
+        <Link href="/" className="hover:text-[#d0d6e0] transition-colors">
-        <span className="text-xs text-[#62666d] bg-[#191a1b] px-2 py-0.5 rounded">
+          MCPedia
-          {sectionDocs.length} document{sectionDocs.length !== 1 ? "s" : ""}
+        </Link>
-        </span>
+        <span>/</span>
+        <span className="text-[#8a8f98] font-medium">{sectionInfo.label}</span>
+      </nav>
+
+      {/* Hero Card */}
+      <div className="bg-[#0f1011] border border-[#1f2022] rounded-xl p-6 shadow-sm">
+        <div className="flex flex-col sm:flex-row sm:items-start justify-between gap-4 mb-3">
+          <div className="flex items-center gap-3">
+            <div className="w-12 h-12 rounded-xl bg-[#141517] border border-[#23252a] flex items-center justify-center text-2xl shadow-inner">
+              {sectionInfo.icon}
+            </div>
+            <div>
+              <h1 className="text-2xl sm:text-3xl font-bold text-[#f7f8f8] tracking-tight">
+                {sectionInfo.label}
+              </h1>
+              <p className="text-xs text-[#8a8f98] mt-0.5 font-mono uppercase">
+                Section: {section}
+              </p>
+            </div>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <span className="text-xs font-mono text-[#7170ff] bg-[#5e6ad2]/10 border border-[#5e6ad2]/25 px-2.5 py-1 rounded-md">
+              {sectionDocs.length} document{sectionDocs.length !== 1 ? "s" : ""}
+            </span>
+            <Link
+              href="/create"
+              className="inline-flex items-center gap-1 text-xs bg-[#5e6ad2] hover:bg-[#6a75e0] text-white px-3 py-1 rounded-md font-medium transition-all"
+            >
+              <span>+ Create</span>
+            </Link>
+          </div>
+        </div>
+
+        <p className="text-sm text-[#8a8f98] leading-relaxed max-w-2xl mt-2">
+          {sectionInfo.desc}
+        </p>
       </div>
 
-      <p className="text-sm text-[#8a8f98] mb-8 max-w-2xl">
+      {/* Hierarchical Folder Directory */}
-        {sectionInfo.desc}
+      {tree.length > 0 && (
-      </p>
+        <section className="bg-[#0c0d0e] border border-[#1f2022] rounded-xl p-6">
-
+          <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider mb-4 flex items-center gap-2">
-      {tree.length > 0 ? (
+            <span>Folder Structure</span>
-        <div className="mb-12">
-          <h2 className="text-xs font-medium text-[#8a8f98] uppercase mb-3 tracking-wider">
-            Folder structure
           </h2>
           {renderTree(tree, section)}
-        </div>
+        </section>
-      ) : (
-        <p className="text-sm text-[#62666d] mb-8">No documents found in this section.</p>
       )}
 
-      {sectionDocs.length > 0 && (
+      {/* Document List */}
-        <div>
+      {sectionDocs.length > 0 ? (
-          <h2 className="text-xs font-medium text-[#8a8f98] uppercase mb-3 tracking-wider">
+        <section>
-            Recently updated
+          <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider mb-4">
+            All Documents in {sectionInfo.label}
           </h2>
           <div className="space-y-2">
             {[...sectionDocs]
@@ -177,20 +205,42 @@ export default async function SectionIndexPage({
                 <Link
                   key={d.slug}
                   href={`/${d.slug}`}
-                  className="group flex items-center justify-between gap-3 py-2 border-b border-[#141516] last:border-0"
+                  className="group flex items-center justify-between gap-4 p-4 bg-[#0f1011] hover:bg-[#141517] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-xl transition-all shadow-sm"
                 >
-                  <span className="text-sm text-[#d0d6e0] group-hover:text-[#7170ff] transition-colors line-clamp-1">
+                  <div className="flex items-center gap-3 min-w-0">
-                    {d.title}
+                    <span className="text-lg opacity-70 group-hover:opacity-100">📄</span>
-                  </span>
+                    <div className="min-w-0">
-                  <time className="text-xs text-[#62666d] flex-shrink-0">
+                      <h3 className="text-sm font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors truncate">
+                        {d.title}
+                      </h3>
+                      {d.tags.length > 0 && (
+                        <div className="flex flex-wrap gap-1 mt-1.5">
+                          {d.tags.slice(0, 4).map((t) => (
+                            <span
+                              key={t}
+                              className="text-[10px] px-1.5 py-0.25 bg-[#141517] border border-[#23252a] rounded text-[#8a8f98]"
+                            >
+                              #{t}
+                            </span>
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                  </div>
+                  <time className="text-xs text-[#62666d] font-mono shrink-0">
                     {new Date(d.updatedAt).toLocaleDateString(undefined, {
                       month: "short",
                       day: "numeric",
+                      year: "numeric",
                     })}
                   </time>
                 </Link>
               ))}
           </div>
+        </section>
+      ) : (
+        <div className="text-center py-12 border border-[#1f2022] rounded-xl bg-[#0f1011]">
+          <p className="text-sm text-[#8a8f98]">No documents in this section yet.</p>
         </div>
       )}
     </div>

apps/web/app/components/CommandMenu.tsx

@@ -0,0 +1,211 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+
+interface Hit {
+  slug: string;
+  title: string;
+  section: string;
+  snippet?: string;
+  score: number;
+}
+
+export default function CommandMenu() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<Hit[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const router = useRouter();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Global shortcut ⌘K or /
+  useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      } else if (e.key === "/" && !["INPUT", "TEXTAREA"].includes((e.target as HTMLElement)?.tagName)) {
+        e.preventDefault();
+        setOpen(true);
+      } else if (e.key === "Escape" && open) {
+        setOpen(false);
+      }
+    }
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [open]);
+
+  useEffect(() => {
+    if (open) {
+      setTimeout(() => inputRef.current?.focus(), 50);
+      setQuery("");
+      setResults([]);
+      setSelectedIndex(0);
+    }
+  }, [open]);
+
+  // Debounced search
+  useEffect(() => {
+    if (!query.trim()) {
+      setResults([]);
+      return;
+    }
+    const timer = setTimeout(async () => {
+      setLoading(true);
+      try {
+        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}&limit=8`);
+        const data = await res.json();
+        setResults(data.results || []);
+        setSelectedIndex(0);
+      } catch {
+        setResults([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 150);
+    return () => clearTimeout(timer);
+  }, [query]);
+
+  function handleNavigate(slug: string) {
+    setOpen(false);
+    router.push(`/${slug}`);
+  }
+
+  function handleKeyNavigation(e: React.KeyboardEvent) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setSelectedIndex((prev) => (results.length > 0 ? (prev + 1) % results.length : 0));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setSelectedIndex((prev) => (results.length > 0 ? (prev - 1 + results.length) % results.length : 0));
+    } else if (e.key === "Enter" && results[selectedIndex]) {
+      e.preventDefault();
+      handleNavigate(results[selectedIndex].slug);
+    }
+  }
+
+  if (!open) {
+    return (
+      <button
+        onClick={() => setOpen(true)}
+        className="hidden md:flex items-center gap-2 px-3 py-1.5 bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] hover:border-[#383b42] text-xs text-[#8a8f98] hover:text-[#d0d6e0] rounded-lg transition-all shadow-inner"
+      >
+        <svg className="w-3.5 h-3.5 text-[#62666d]" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+        </svg>
+        <span>Search documentation...</span>
+        <kbd className="ml-2 font-mono bg-[#08090a] px-1.5 py-0.5 rounded border border-[#1f2022] text-[10px] text-[#62666d]">
+          ⌘K
+        </kbd>
+      </button>
+    );
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-start justify-center pt-20 px-4">
+      {/* Backdrop */}
+      <div
+        className="fixed inset-0 bg-black/70 backdrop-blur-sm transition-opacity"
+        onClick={() => setOpen(false)}
+      />
+
+      {/* Modal */}
+      <div className="relative w-full max-w-2xl bg-[#0f1011] border border-[#27292d] rounded-xl shadow-2xl overflow-hidden animate-fade-in">
+        {/* Search input bar */}
+        <div className="flex items-center gap-3 px-4 py-3.5 border-b border-[#1f2022] bg-[#141517]">
+          <svg className="w-5 h-5 text-[#7170ff] shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <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
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyNavigation}
+            placeholder="Type to search (titles, keywords, concepts)..."
+            className="w-full bg-transparent text-[#f7f8f8] placeholder-[#62666d] text-sm focus:outline-none"
+          />
+          {loading && (
+            <div className="w-4 h-4 border-2 border-[#5e6ad2] border-t-transparent rounded-full animate-spin shrink-0" />
+          )}
+          <button
+            onClick={() => setOpen(false)}
+            className="text-xs text-[#62666d] hover:text-[#d0d6e0] bg-[#1b1d20] px-1.5 py-0.5 rounded border border-[#27292d]"
+          >
+            ESC
+          </button>
+        </div>
+
+        {/* Results / Suggestions */}
+        <div className="max-h-96 overflow-y-auto p-2">
+          {query.trim() === "" ? (
+            <div className="px-3 py-6 text-center">
+              <p className="text-xs text-[#8a8f98]">Search full-text, semantic embeddings, and CTF writeups.</p>
+              <div className="flex justify-center gap-2 mt-3 text-[11px] text-[#62666d]">
+                <span>Navigation: <kbd className="bg-[#141517] px-1 py-0.5 rounded border border-[#1f2022]">↑</kbd> <kbd className="bg-[#141517] px-1 py-0.5 rounded border border-[#1f2022]">↓</kbd></span>
+                <span>Select: <kbd className="bg-[#141517] px-1 py-0.5 rounded border border-[#1f2022]">↵</kbd></span>
+              </div>
+            </div>
+          ) : results.length === 0 && !loading ? (
+            <div className="px-4 py-8 text-center text-xs text-[#8a8f98]">
+              No documents matching &quot;{query}&quot;
+            </div>
+          ) : (
+            <ul className="space-y-1">
+              {results.map((hit, index) => {
+                const isSelected = index === selectedIndex;
+                return (
+                  <li
+                    key={hit.slug}
+                    onClick={() => handleNavigate(hit.slug)}
+                    onMouseEnter={() => setSelectedIndex(index)}
+                    className={`flex items-start justify-between gap-3 px-3 py-2.5 rounded-lg cursor-pointer transition-all ${
+                      isSelected
+                        ? "bg-[#5e6ad2]/15 border border-[#5e6ad2]/40 text-[#f7f8f8]"
+                        : "hover:bg-[#141517] text-[#d0d6e0] border border-transparent"
+                    }`}
+                  >
+                    <div className="min-w-0 flex-1">
+                      <div className="flex items-center gap-2">
+                        <span className="text-xs px-1.5 py-0.25 bg-[#191a1b] border border-[#23252a] rounded text-[#7170ff] font-mono">
+                          {hit.section}
+                        </span>
+                        <span className={`text-sm font-medium ${isSelected ? "text-[#7170ff]" : "text-[#f7f8f8]"} truncate`}>
+                          {hit.title}
+                        </span>
+                      </div>
+                      {hit.snippet && (
+                        <p
+                          className="text-xs text-[#8a8f98] mt-1 line-clamp-1 [&>mark]:bg-[#5e6ad2]/30 [&>mark]:text-[#f7f8f8] [&>mark]:rounded [&>mark]:px-0.5"
+                          dangerouslySetInnerHTML={{ __html: hit.snippet }}
+                        />
+                      )}
+                    </div>
+                    <span className="text-[11px] text-[#62666d] shrink-0 self-center">
+                      {hit.slug}
+                    </span>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between px-4 py-2.5 border-t border-[#1f2022] bg-[#0c0d0e] text-[11px] text-[#62666d]">
+          <span>Tip: Press <kbd className="bg-[#141517] px-1 py-0.5 rounded border border-[#1f2022]">Hybrid</kbd> search is enabled by default</span>
+          <Link
+            href={`/search?q=${encodeURIComponent(query)}`}
+            onClick={() => setOpen(false)}
+            className="hover:text-[#7170ff] transition-colors"
+          >
+            Open full search page →
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/app/components/DocActions.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+
+interface DocActionsProps {
+  slug: string;
+  body: string;
+  canEdit: boolean;
+}
+
+export default function DocActions({ slug, body, canEdit }: DocActionsProps) {
+  const [copiedMd, setCopiedMd] = useState(false);
+  const [copiedLink, setCopiedLink] = useState(false);
+
+  function handleCopyMarkdown() {
+    navigator.clipboard.writeText(body);
+    setCopiedMd(true);
+    setTimeout(() => setCopiedMd(false), 2000);
+  }
+
+  function handleCopyLink() {
+    navigator.clipboard.writeText(window.location.href);
+    setCopiedLink(true);
+    setTimeout(() => setCopiedLink(false), 2000);
+  }
+
+  return (
+    <div className="flex items-center gap-1.5 shrink-0 flex-wrap">
+      {/* Copy Markdown */}
+      <button
+        onClick={handleCopyMarkdown}
+        type="button"
+        title="Copy raw markdown content"
+        className="inline-flex items-center gap-1 px-2.5 py-1 text-xs bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] hover:border-[#383b42] text-[#8a8f98] hover:text-[#f7f8f8] rounded-md transition-all"
+      >
+        {copiedMd ? (
+          <>
+            <svg className="w-3.5 h-3.5 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+            </svg>
+            <span className="text-emerald-400">Copied MD</span>
+          </>
+        ) : (
+          <>
+            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 7v8a2 2 0 002 2h6M8 7V5a2 2 0 012-2h4.586a1 1 0 01.707.293l4.414 4.414a1 1 0 01.293.707V15a2 2 0 01-2 2h-2M8 7H6a2 2 0 00-2 2v10a2 2 0 002 2h8a2 2 0 002-2v-2" />
+            </svg>
+            <span>Raw MD</span>
+          </>
+        )}
+      </button>
+
+      {/* Copy Link */}
+      <button
+        onClick={handleCopyLink}
+        type="button"
+        title="Copy link to document"
+        className="inline-flex items-center gap-1 px-2.5 py-1 text-xs bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] hover:border-[#383b42] text-[#8a8f98] hover:text-[#f7f8f8] rounded-md transition-all"
+      >
+        {copiedLink ? (
+          <>
+            <svg className="w-3.5 h-3.5 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+            </svg>
+            <span className="text-emerald-400">Copied</span>
+          </>
+        ) : (
+          <>
+            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1" />
+            </svg>
+            <span>Share</span>
+          </>
+        )}
+      </button>
+
+      {/* Edit Link */}
+      <Link
+        href={canEdit ? `/${slug}?edit=1` : `/login?redirect=/${slug}`}
+        className="inline-flex items-center gap-1 px-2.5 py-1 text-xs bg-[#5e6ad2]/15 hover:bg-[#5e6ad2]/25 border border-[#5e6ad2]/30 hover:border-[#5e6ad2]/60 text-[#7170ff] hover:text-white rounded-md transition-all"
+      >
+        <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
+        </svg>
+        <span>{canEdit ? "Edit" : "Edit"}</span>
+      </Link>
+    </div>
+  );
+}

apps/web/app/components/DocForm.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useRef } from "react";
 import { useRouter } from "next/navigation";
+import Markdown from "./Markdown";
 
 interface DocFormProps {
   mode: "create" | "edit";
@@ -23,6 +24,14 @@ interface DocFormProps {
 const SECTION_OPTIONS = ["docs", "writeups", "research", "notes"] as const;
 const TYPE_OPTIONS = ["documentation", "writeup", "research", "note"] as const;
 
+const PRESET_FIELDS = [
+  { key: "difficulty", value: "medium" },
+  { key: "points", value: "100" },
+  { key: "category", value: "pwn" },
+  { key: "event", value: "DEF CON Quals 2024" },
+  { key: "solved", value: "true" },
+];
+
 export default function DocForm({
   mode,
   slug,
@@ -33,6 +42,7 @@ export default function DocForm({
   const router = useRouter();
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState<"write" | "preview">("write");
 
   const [title, setTitle] = useState(initial?.title ?? "");
   const [slugInput, setSlugInput] = useState("");
@@ -44,10 +54,10 @@ export default function DocForm({
   const [author, setAuthor] = useState(initial?.author ?? "");
   const [parentFolder, setParentFolder] = useState("");
 
-  // Extract existing custom fields from initial for edit mode
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
-  const [customFields, setCustomFields] = useState<
+
-    Array<{ key: string; value: string }>
+  // Extract existing custom fields
-  >(() => {
+  const [customFields, setCustomFields] = useState<Array<{ key: string; value: string }>>(() => {
     if (initial?.extraFields) {
       return Object.entries(initial.extraFields)
         .filter(([k, v]) => k !== "slug" && v !== undefined && v !== null)
@@ -72,12 +82,10 @@ export default function DocForm({
   const availableFolders = existingFolders?.[section] ?? [];
 
   const baseInputCls =
-    "w-full px-3 py-2 bg-[#0f1011] border border-[#23252a] rounded text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2]";
+    "w-full px-3.5 py-2 bg-[#0f1011] border border-[#23252a] hover:border-[#383b42] rounded-lg text-sm text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2] transition-colors";
 
-  const baseSelectCls = baseInputCls;
+  function addCustomField(key = "", value = "") {
-
+    setCustomFields([...customFields, { key, value }]);
-  function addCustomField() {
-    setCustomFields([...customFields, { key: "", value: "" }]);
   }
 
   function updateCustomField(index: number, field: "key" | "value", value: string) {
@@ -90,6 +98,24 @@ export default function DocForm({
     setCustomFields(customFields.filter((_, i) => i !== index));
   }
 
+  function insertMarkdown(prefix: string, suffix = "") {
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+
+    const start = textarea.selectionStart;
+    const end = textarea.selectionEnd;
+    const selection = body.substring(start, end);
+    const replacement = `${prefix}${selection || "text"}${suffix}`;
+
+    const newBody = body.substring(0, start) + replacement + body.substring(end);
+    setBody(newBody);
+
+    setTimeout(() => {
+      textarea.focus();
+      textarea.setSelectionRange(start + prefix.length, start + replacement.length - suffix.length);
+    }, 10);
+  }
+
   async function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     setLoading(true);
@@ -158,52 +184,53 @@ export default function DocForm({
   return (
     <form onSubmit={handleSubmit} className="space-y-6 max-w-4xl">
       {error && (
-        <div className="p-3 rounded border border-[#274360] text-[#fca5a5] text-sm">
+        <div className="p-3.5 rounded-lg border border-rose-500/30 bg-rose-500/10 text-rose-400 text-sm">
           {error}
         </div>
       )}
 
       {/* Title */}
       <div>
-        <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+        <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
-          Title
+          Document Title *
         </label>
         <input
           type="text"
           value={title}
           onChange={(e) => setTitle(e.target.value)}
-          className={baseInputCls}
+          placeholder="e.g. DEF CON Quals 2024 — pwn-100 Writeup"
+          className={`${baseInputCls} text-base`}
           required
         />
       </div>
 
       {/* Section + Type + Status */}
-      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+      <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
             Section
           </label>
           <select
             value={section}
             onChange={(e) => setSection(e.target.value as typeof section)}
-            className={baseSelectCls}
+            className={baseInputCls}
             disabled={isEdit}
           >
             {SECTION_OPTIONS.map((s) => (
               <option key={s} value={s}>
-                {s}
+                {s.toUpperCase()}
               </option>
             ))}
           </select>
         </div>
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
             Type
           </label>
           <select
             value={type}
             onChange={(e) => setType(e.target.value as typeof type)}
-            className={baseSelectCls}
+            className={baseInputCls}
           >
             {TYPE_OPTIONS.map((t) => (
               <option key={t} value={t}>
@@ -213,13 +240,13 @@ export default function DocForm({
           </select>
         </div>
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
             Status
           </label>
           <select
             value={status}
             onChange={(e) => setStatus(e.target.value as typeof status)}
-            className={baseSelectCls}
+            className={baseInputCls}
           >
             <option value="published">Published</option>
             <option value="draft">Draft</option>
@@ -228,71 +255,68 @@ export default function DocForm({
       </div>
 
       {/* Folder + Slug */}
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
-            Parent folder (optional)
+            Parent Folder
           </label>
           <select
             value={parentFolder}
             onChange={(e) => setParentFolder(e.target.value)}
-            className={baseSelectCls}
+            className={baseInputCls}
             disabled={isEdit}
           >
-            <option value="">(root of section)</option>
+            <option value="">(Root of section)</option>
             {availableFolders.map((folder) => (
               <option key={folder} value={folder}>
-                {folder}
+                /{folder}
               </option>
             ))}
           </select>
-          <p className="text-xs text-[#62666d] mt-1">
-            Place inside an existing folder.
-          </p>
         </div>
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
-            {isEdit ? "Full slug" : "Slug (file name)"}
+            {isEdit ? "Full Slug" : "Slug (File name) *"}
           </label>
           {isEdit ? (
             <input
               type="text"
               value={slug ?? ""}
               readOnly
-              className="w-full px-3 py-2 bg-[#191a1b] border border-[#23252a] rounded text-[#8a8f98]"
+              className="w-full px-3.5 py-2 bg-[#141517] border border-[#23252a] rounded-lg text-sm text-[#8a8f98] font-mono"
             />
           ) : (
             <input
               type="text"
               value={slugInput}
               onChange={(e) => setSlugInput(e.target.value)}
-              className={baseInputCls}
+              className={`${baseInputCls} font-mono`}
-              placeholder="my-document-slug"
+              placeholder="my-new-post"
               required
             />
           )}
-          <p className="text-xs text-[#62666d] mt-1">
+          <p className="text-[11px] text-[#62666d] mt-1 font-mono">
-            Resolved: <code className="bg-[#191a1b] px-1 py-0.25 rounded">{effectiveSlug || section}</code>
+            Path: <span className="text-[#7170ff]">{effectiveSlug || section}</span>
           </p>
         </div>
       </div>
 
       {/* Tags + Author */}
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
-            Tags
+            Tags (comma separated)
           </label>
           <input
             type="text"
             value={tags}
             onChange={(e) => setTags(e.target.value)}
             className={baseInputCls}
-            placeholder="comma, separated, tags"
+            placeholder="ctf, pwn, reverse, tutorial"
           />
         </div>
         <div>
-          <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+          <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
             Author
           </label>
           <input
@@ -300,83 +324,196 @@ export default function DocForm({
             value={author}
             onChange={(e) => setAuthor(e.target.value)}
             className={baseInputCls}
+            placeholder="asep"
           />
         </div>
       </div>
 
-      {/* Custom fields */}
+      {/* Custom Metadata Fields */}
-      <div>
+      <div className="p-4 bg-[#0c0d0e] border border-[#1f2022] rounded-xl space-y-3">
-        <label className="block text-xs font-medium text-[#d0d6e0] mb-2">
+        <div className="flex items-center justify-between">
-          Custom metadata fields
+          <div>
-        </label>
+            <h3 className="text-xs font-semibold uppercase tracking-wider text-[#8a8f98]">
-        <p className="text-xs text-[#62666d] mb-3">
+              Dynamic Custom Metadata
-          Add extra frontmatter fields. Any field you add will be rendered as
+            </h3>
-          an auto-styled badge on the doc page based on its value.
+            <p className="text-[11px] text-[#62666d] mt-0.5">
-        </p>
+              Add custom key-values (event, difficulty, points, etc.) rendered as styled badges.
-        {customFields.length > 0 && (
+            </p>
-          <div className="space-y-3 mb-3">
+          </div>
-            {customFields.map((field, i) => (
+
-              <div key={i} className="flex gap-2 items-center">
+          <div className="flex items-center gap-1.5 flex-wrap">
-                <input
+            <span className="text-[11px] text-[#62666d]">Presets:</span>
-                  type="text"
+            {PRESET_FIELDS.map((preset) => (
-                  placeholder="field name"
+              <button
-                  value={field.key}
+                key={preset.key}
-                  onChange={(e) => updateCustomField(i, "key", e.target.value)}
+                type="button"
-                  className={baseInputCls}
+                onClick={() => addCustomField(preset.key, preset.value)}
-                />
+                className="px-2 py-0.5 text-[11px] bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] text-[#8a8f98] hover:text-[#d0d6e0] rounded transition-colors"
-                <input
+              >
-                  type="text"
+                +{preset.key}
-                  placeholder="value"
+              </button>
-                  value={field.value}
-                  onChange={(e) => updateCustomField(i, "value", e.target.value)}
-                  className={baseInputCls}
-                />
-                <button
-                  type="button"
-                  onClick={() => removeCustomField(i)}
-                  className="text-xs text-[#fca5a5] hover:text-[#ff6b6b] px-2 py-1 rounded hover:bg-[#191a1b] transition-colors"
-                >
-                  ✕
-                </button>
-              </div>
             ))}
           </div>
-        )}
+        </div>
+
+        {customFields.map((field, i) => (
+          <div key={i} className="flex gap-2 items-center">
+            <input
+              type="text"
+              placeholder="Field name (e.g. event)"
+              value={field.key}
+              onChange={(e) => updateCustomField(i, "key", e.target.value)}
+              className={`${baseInputCls} text-xs font-mono`}
+            />
+            <input
+              type="text"
+              placeholder="Value (e.g. DEF CON 2024)"
+              value={field.value}
+              onChange={(e) => updateCustomField(i, "value", e.target.value)}
+              className={`${baseInputCls} text-xs font-mono`}
+            />
+            <button
+              type="button"
+              onClick={() => removeCustomField(i)}
+              className="p-2 text-[#fca5a5] hover:text-rose-400 rounded hover:bg-[#191a1b] transition-colors"
+              title="Remove field"
+            >
+              ✕
+            </button>
+          </div>
+        ))}
+
         <button
           type="button"
-          onClick={addCustomField}
+          onClick={() => addCustomField()}
-          className="text-xs text-[#7170ff] hover:text-[#828fff] px-3 py-1.5 rounded border border-[#5e6ad2]/30 hover:border-[#5e6ad2]/60 transition-colors"
+          className="text-xs text-[#7170ff] hover:text-[#828fff] px-3 py-1.5 rounded-lg border border-[#5e6ad2]/30 hover:border-[#5e6ad2]/60 bg-[#5e6ad2]/5 transition-colors"
         >
-          + Add field
+          + Add Custom Field
         </button>
       </div>
 
-      {/* Body */}
+      {/* Body with Write / Preview Tabs */}
-      <div>
+      <div className="border border-[#1f2022] rounded-xl overflow-hidden bg-[#0c0d0e]">
-        <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+        {/* Editor Toolbar */}
-          Body (Markdown)
+        <div className="flex items-center justify-between px-3 py-2 bg-[#141517] border-b border-[#1f2022] flex-wrap gap-2">
-        </label>
+          {/* Tabs */}
-        <textarea
+          <div className="flex items-center gap-1">
-          value={body}
+            <button
-          onChange={(e) => setBody(e.target.value)}
+              type="button"
-          className="w-full h-96 px-3 py-2 bg-[#0f1011] border border-[#23252a] rounded text-[#f7f8f8] placeholder-[#62666d] font-mono text-sm focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2]"
+              onClick={() => setActiveTab("write")}
-          placeholder="# Heading&#10;&#10;Content here..."
+              className={`px-3 py-1 text-xs rounded-md font-medium transition-all ${
-        />
+                activeTab === "write"
+                  ? "bg-[#5e6ad2] text-white"
+                  : "text-[#8a8f98] hover:text-[#d0d6e0]"
+              }`}
+            >
+              Write
+            </button>
+            <button
+              type="button"
+              onClick={() => setActiveTab("preview")}
+              className={`px-3 py-1 text-xs rounded-md font-medium transition-all ${
+                activeTab === "preview"
+                  ? "bg-[#5e6ad2] text-white"
+                  : "text-[#8a8f98] hover:text-[#d0d6e0]"
+              }`}
+            >
+              Live Preview
+            </button>
+          </div>
+
+          {/* Markdown Action Shortcuts */}
+          {activeTab === "write" && (
+            <div className="flex items-center gap-1 text-xs text-[#8a8f98]">
+              <button
+                type="button"
+                onClick={() => insertMarkdown("**", "**")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0]"
+                title="Bold"
+              >
+                <b>B</b>
+              </button>
+              <button
+                type="button"
+                onClick={() => insertMarkdown("*", "*")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0]"
+                title="Italic"
+              >
+                <i>I</i>
+              </button>
+              <button
+                type="button"
+                onClick={() => insertMarkdown("## ")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0]"
+                title="Heading 2"
+              >
+                H2
+              </button>
+              <button
+                type="button"
+                onClick={() => insertMarkdown("```\n", "\n```")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0] font-mono"
+                title="Code Block"
+              >
+                {"</>"}
+              </button>
+              <button
+                type="button"
+                onClick={() => insertMarkdown("[", "](https://)")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0]"
+                title="Link"
+              >
+                Link
+              </button>
+              <button
+                type="button"
+                onClick={() => insertMarkdown("> [!NOTE]\n> ")}
+                className="px-2 py-0.5 hover:bg-[#23252a] rounded text-[#d0d6e0]"
+                title="Note Callout"
+              >
+                Note
+              </button>
+            </div>
+          )}
+        </div>
+
+        {/* Tab content */}
+        {activeTab === "write" ? (
+          <textarea
+            ref={textareaRef}
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            className="w-full h-96 p-4 bg-transparent text-[#f7f8f8] placeholder-[#62666d] font-mono text-sm focus:outline-none resize-y leading-relaxed"
+            placeholder="# Write your markdown document here..."
+            required
+          />
+        ) : (
+          <div className="p-6 h-96 overflow-y-auto bg-[#08090a]">
+            {body.trim() ? (
+              <Markdown source={body} />
+            ) : (
+              <p className="text-xs text-[#62666d] italic">Nothing to preview yet.</p>
+            )}
+          </div>
+        )}
       </div>
 
-      {/* Submit */}
+      {/* Actions */}
-      <div className="flex gap-3">
+      <div className="flex items-center gap-3">
         <button
           type="submit"
           disabled={loading}
-          className="px-4 py-2 bg-[#5e6ad2] text-white rounded hover:bg-[#7170ff] disabled:opacity-50 font-medium text-sm"
+          className="px-6 py-2.5 bg-[#5e6ad2] hover:bg-[#6a75e0] text-white rounded-lg font-medium text-sm transition-all shadow-md shadow-[#5e6ad2]/20 disabled:opacity-50 flex items-center gap-2"
         >
-          {loading ? "Saving..." : mode === "create" ? "Create" : "Update"}
+          {loading && (
+            <div className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin" />
+          )}
+          <span>{loading ? "Saving document..." : mode === "create" ? "Create Document" : "Save Changes"}</span>
         </button>
         <button
           type="button"
           onClick={() => router.back()}
-          className="px-4 py-2 border border-[#23252a] rounded text-[#d0d6e0] hover:text-[#f7f8f8] hover:border-[#3e3e44] transition-colors text-sm"
+          className="px-4 py-2.5 border border-[#23252a] hover:border-[#383b42] text-[#8a8f98] hover:text-[#d0d6e0] rounded-lg text-sm transition-colors"
         >
           Cancel
         </button>

apps/web/app/components/Header.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { SECTIONS } from "@mcpedia/config/sections";
+import ThemeToggle from "@/components/ThemeToggle";
+import CommandMenu from "@/components/CommandMenu";
+
+export default function Header() {
+  const pathname = usePathname();
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  return (
+    <header className="sticky top-0 z-30 border-b border-[#1f2022] glass-nav">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 h-14 flex items-center justify-between gap-4">
+        {/* Brand */}
+        <div className="flex items-center gap-3">
+          <Link href="/" className="flex items-center gap-2 group">
+            <div className="w-7 h-7 rounded-lg bg-gradient-to-br from-[#5e6ad2] to-[#7170ff] flex items-center justify-center text-white font-bold text-xs shadow-md shadow-[#5e6ad2]/20 group-hover:scale-105 transition-transform">
+              M
+            </div>
+            <span className="font-semibold text-[#f7f8f8] text-base tracking-tight group-hover:text-white transition-colors">
+              MCPedia
+            </span>
+          </Link>
+          <span className="hidden sm:inline-block text-[10px] uppercase font-mono px-1.5 py-0.5 rounded bg-[#141517] border border-[#23252a] text-[#8a8f98]">
+            v0.1.0
+          </span>
+        </div>
+
+        {/* Desktop Nav */}
+        <nav className="hidden md:flex items-center gap-1">
+          {SECTIONS.map((s) => {
+            const isActive = pathname === `/${s.id}` || pathname.startsWith(`/${s.id}/`);
+            return (
+              <Link
+                key={s.id}
+                href={`/${s.id}`}
+                className={`px-3 py-1.5 rounded-md text-xs font-medium transition-all ${
+                  isActive
+                    ? "text-[#f7f8f8] bg-[#141517] border border-[#23252a]"
+                    : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#141517]/50"
+                }`}
+              >
+                <span className="mr-1.5 opacity-70">{s.icon}</span>
+                {s.label}
+              </Link>
+            );
+          })}
+        </nav>
+
+        {/* Right tools */}
+        <div className="flex items-center gap-2.5">
+          <CommandMenu />
+
+          <Link
+            href="/search"
+            className="md:hidden p-1.5 text-[#8a8f98] hover:text-[#f7f8f8] rounded-lg hover:bg-[#141517] transition-colors"
+            title="Search"
+          >
+            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+            </svg>
+          </Link>
+
+          <Link
+            href="/create"
+            className="hidden sm:inline-flex items-center gap-1.5 px-3 py-1 bg-[#5e6ad2] hover:bg-[#7170ff] text-white text-xs font-medium rounded-lg transition-all shadow-sm hover:shadow-[#5e6ad2]/20"
+          >
+            <span>+</span>
+            <span>New Doc</span>
+          </Link>
+
+          <Link
+            href="/login"
+            className={`px-2.5 py-1 text-xs rounded-lg transition-colors ${
+              pathname === "/login"
+                ? "text-[#f7f8f8] bg-[#141517]"
+                : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#141517]"
+            }`}
+          >
+            Login
+          </Link>
+
+          <div className="border-l border-[#1f2022] pl-2.5 flex items-center">
+            <ThemeToggle />
+          </div>
+
+          {/* Mobile menu toggle */}
+          <button
+            onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+            className="md:hidden p-1 text-[#8a8f98] hover:text-[#f7f8f8]"
+            aria-label="Toggle navigation"
+          >
+            <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              {mobileMenuOpen ? (
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+              ) : (
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
+              )}
+            </svg>
+          </button>
+        </div>
+      </div>
+
+      {/* Mobile Drawer */}
+      {mobileMenuOpen && (
+        <div className="md:hidden border-t border-[#1f2022] bg-[#0c0d0e] px-4 py-3 space-y-1 animate-fade-in">
+          {SECTIONS.map((s) => (
+            <Link
+              key={s.id}
+              href={`/${s.id}`}
+              onClick={() => setMobileMenuOpen(false)}
+              className="flex items-center gap-2 px-3 py-2 rounded-lg text-sm text-[#d0d6e0] hover:bg-[#141517] hover:text-[#f7f8f8]"
+            >
+              <span>{s.icon}</span>
+              <span>{s.label}</span>
+            </Link>
+          ))}
+          <div className="pt-2 border-t border-[#1f2022] flex gap-2">
+            <Link
+              href="/search"
+              onClick={() => setMobileMenuOpen(false)}
+              className="flex-1 text-center py-2 text-xs bg-[#141517] text-[#d0d6e0] rounded-lg"
+            >
+              Search
+            </Link>
+            <Link
+              href="/create"
+              onClick={() => setMobileMenuOpen(false)}
+              className="flex-1 text-center py-2 text-xs bg-[#5e6ad2] text-white rounded-lg font-medium"
+            >
+              + Create
+            </Link>
+          </div>
+        </div>
+      )}
+    </header>
+  );
+}

apps/web/app/components/Markdown.tsx

@@ -1,32 +1,101 @@
+"use client";
+
+import React, { useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import rehypeSlug from "rehype-slug";
 
+function CodeBlock({ children, className, ...props }: React.HTMLAttributes<HTMLElement>) {
+  const [copied, setCopied] = useState(false);
+  const textContent = String(children).replace(/\n$/, "");
+  const match = /language-(\w+)/.exec(className || "");
+  const language = match ? match[1] : "";
+
+  // If inline code
+  if (!className && typeof children === "string" && !children.includes("\n")) {
+    return (
+      <code className={className} {...props}>
+        {children}
+      </code>
+    );
+  }
+
+  function handleCopy() {
+    navigator.clipboard.writeText(textContent);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }
+
+  return (
+    <div className="relative group my-4 rounded-lg overflow-hidden border border-[#23252a] bg-[#0c0d0e]">
+      {/* Code block header bar */}
+      <div className="flex items-center justify-between px-3.5 py-1.5 bg-[#141517] border-b border-[#1f2022] text-[11px] text-[#8a8f98] font-mono">
+        <span>{language || "text"}</span>
+        <button
+          onClick={handleCopy}
+          type="button"
+          className="flex items-center gap-1 text-[#8a8f98] hover:text-[#f7f8f8] bg-[#1a1b1d] hover:bg-[#23252a] px-2 py-0.5 rounded border border-[#27292d] transition-all"
+        >
+          {copied ? (
+            <>
+              <svg className="w-3 h-3 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+              </svg>
+              <span className="text-emerald-400 font-sans">Copied!</span>
+            </>
+          ) : (
+            <>
+              <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+              </svg>
+              <span className="font-sans">Copy</span>
+            </>
+          )}
+        </button>
+      </div>
+
+      <pre className="!m-0 !bg-transparent p-4 overflow-x-auto text-sm text-[#e2e4e7] font-mono leading-relaxed">
+        <code className={className} {...props}>
+          {children}
+        </code>
+      </pre>
+    </div>
+  );
+}
+
 export default function Markdown({ source }: { source: string }) {
   return (
     <div
-      className="prose prose-lg max-w-none
+      className="prose prose-invert max-w-none
-      prose-headings:text-[#f7f8f8] prose-headings:font-light prose-headings:mb-4
+      prose-headings:text-[#f7f8f8] prose-headings:font-medium prose-headings:tracking-tight
-      prose-p:text-[#d0d6e0] prose-p:mb-4
+      prose-h1:text-2xl prose-h1:mb-6 prose-h1:mt-8 prose-h1:pb-2 prose-h1:border-b prose-h1:border-[#1f2022]
-      prose-a:text-[#7170ff] prose-a:no-underline hover:prose-a:text-[#828fff]
+      prose-h2:text-xl prose-h2:mb-4 prose-h2:mt-8
-      prose-code:text-[#d0d6e0] prose-code:bg-[#191a1b] prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:before:content-none prose-code:after:content-none
+      prose-h3:text-base prose-h3:mb-3 prose-h3:mt-6
-      prose-pre:bg-[#191a1b] prose-pre:border prose-pre:border-[#23252a] prose-pre:rounded-lg
+      prose-p:text-[#d0d6e0] prose-p:leading-relaxed prose-p:mb-4
-      prose-pre code:bg-transparent prose-pre code:p-0 prose-pre code:text-sm
+      prose-a:text-[#7170ff] prose-a:no-underline hover:prose-a:underline hover:prose-a:text-[#828fff]
-      prose-blockquote:border-l-[#23252a] prose-blockquote:text-[#a0a4a8]
+      prose-ul:text-[#d0d6e0] prose-ul:my-3 prose-li:my-1
-      prose-ul:text-[#d0d6e0] prose-ol:text-[#d0d6e0]
+      prose-ol:text-[#d0d6e0] prose-ol:my-3
-      prose-table:border-collapse [&>_table]:overflow-x-auto
+      prose-strong:text-[#f7f8f8] prose-strong:font-semibold
-      prose-th:bg-[#191a1b] prose-th:text-[#f7f8f8] prose-th:font-medium
+      prose-hr:border-[#1f2022] prose-hr:my-8"
-      prose-td:border-[#1f2022] prose-th:border-[#1f2022]"
     >
       <ReactMarkdown
         remarkPlugins={[remarkGfm]}
         rehypePlugins={[rehypeSlug]}
         components={{
+          code: CodeBlock as any,
+          pre: ({ children }) => <>{children}</>,
           table: ({ node, ...props }) => (
-            <div className="overflow-x-auto">
+            <div className="overflow-x-auto my-6 border border-[#1f2022] rounded-lg">
               <table className="w-full border-collapse" {...props} />
             </div>
           ),
+          blockquote: ({ children }) => {
+            return (
+              <blockquote className="border-l-4 border-[#5e6ad2] bg-[#141517]/60 pl-4 py-2 my-4 rounded-r text-[#a0a4a8] not-italic">
+                {children}
+              </blockquote>
+            );
+          },
         }}
       >
         {source}

apps/web/app/components/McpConfigSnippet.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import { useState } from "react";
+
+const CONFIGS = [
+  {
+    id: "claude",
+    label: "Claude Desktop",
+    filename: "~/Library/Application Support/Claude/claude_desktop_config.json",
+    content: `{
+  "mcpServers": {
+    "mcpedia": {
+      "command": "bun",
+      "args": ["run", "/path/to/mcpedia/apps/mcp/src/index.ts"],
+      "env": {
+        "DATABASE_URL": "postgresql://...",
+        "OPENROUTER_API_KEY": "sk-or-v1-..."
+      }
+    }
+  }
+}`,
+  },
+  {
+    id: "http",
+    label: "Remote HTTP (SSE)",
+    filename: "Streamable HTTP Endpoint",
+    content: `{
+  "mcpServers": {
+    "mcpedia-remote": {
+      "url": "https://mcp.asepharyana.my.id/mcp",
+      "headers": {
+        "x-webhook-secret": "your-secret-here"
+      }
+    }
+  }
+}`,
+  },
+  {
+    id: "cli",
+    label: "CLI Client",
+    filename: "Terminal One-Shot / REPL",
+    content: `# One-shot question
+bun run apps/mcp-client/src/ask.ts "How does ret2win stack alignment work?"
+
+# Interactive REPL
+bun run apps/mcp-client/src/index.ts`,
+  },
+];
+
+export default function McpConfigSnippet() {
+  const [activeTab, setActiveTab] = useState("claude");
+  const [copied, setCopied] = useState(false);
+
+  const current = CONFIGS.find((c) => c.id === activeTab) || CONFIGS[0];
+
+  function handleCopy() {
+    navigator.clipboard.writeText(current.content);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }
+
+  return (
+    <div className="bg-[#0c0d0e] border border-[#1f2022] rounded-xl overflow-hidden shadow-lg">
+      {/* Header bar with tabs */}
+      <div className="flex items-center justify-between px-4 py-2.5 bg-[#141517] border-b border-[#1f2022] flex-wrap gap-2">
+        <div className="flex items-center gap-1.5">
+          {CONFIGS.map((c) => (
+            <button
+              key={c.id}
+              onClick={() => setActiveTab(c.id)}
+              className={`px-3 py-1 text-xs rounded-md font-medium transition-all ${
+                activeTab === c.id
+                  ? "bg-[#5e6ad2] text-white shadow-sm"
+                  : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#1b1d20]"
+              }`}
+            >
+              {c.label}
+            </button>
+          ))}
+        </div>
+
+        <button
+          onClick={handleCopy}
+          type="button"
+          className="flex items-center gap-1.5 text-xs text-[#8a8f98] hover:text-white bg-[#1a1b1d] hover:bg-[#23252a] px-2.5 py-1 rounded border border-[#27292d] transition-all"
+        >
+          {copied ? (
+            <>
+              <svg className="w-3.5 h-3.5 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+              </svg>
+              <span className="text-emerald-400 font-medium">Copied!</span>
+            </>
+          ) : (
+            <>
+              <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+              </svg>
+              <span>Copy Config</span>
+            </>
+          )}
+        </button>
+      </div>
+
+      {/* Code preview */}
+      <pre className="p-4 text-xs font-mono text-[#d0d6e0] overflow-x-auto leading-relaxed">
+        <code>{current.content}</code>
+      </pre>
+
+      <div className="px-4 py-2 bg-[#090a0b] border-t border-[#1a1b1d] text-[11px] text-[#62666d]">
+        Config location: <span className="font-mono text-[#8a8f98]">{current.filename}</span>
+      </div>
+    </div>
+  );
+}

apps/web/app/components/Sidebar.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useState, useMemo } from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { SECTIONS } from "@mcpedia/config/sections";
@@ -12,17 +12,13 @@ interface Doc {
   tags: string[];
 }
 
-/**
- * Build a hierarchical folder tree from flat document slugs.
- * Each node is either a folder (has children) or a leaf doc.
- */
 interface TreeNode {
   name: string;
   slug: string;
   title: string;
   children: TreeNode[];
   isLeaf: boolean;
-  docCount: number; // total docs in subtree
+  docCount: number;
 }
 
 function buildFolderTree(docs: Doc[], section: string): TreeNode[] {
@@ -30,7 +26,6 @@ function buildFolderTree(docs: Doc[], section: string): TreeNode[] {
 
   for (const doc of docs.filter((d) => d.section === section)) {
     const parts = doc.slug.split("/");
-    // parts[0] is the section; skip it
     let current = root;
 
     for (let i = 1; i < parts.length; i++) {
@@ -63,7 +58,6 @@ function buildFolderTree(docs: Doc[], section: string): TreeNode[] {
     }
   }
 
-  // Recursively compute docCount
   function countDocs(node: TreeNode): number {
     if (node.isLeaf) return 1;
     return node.children.reduce((sum, child) => sum + countDocs(child), 0);
@@ -73,15 +67,15 @@ function buildFolderTree(docs: Doc[], section: string): TreeNode[] {
     node.docCount = countDocs(node);
   }
 
-  // Sort: folders first, then docs, alphabetically
   function sortNodes(nodes: TreeNode[]): TreeNode[] {
     return nodes.sort((a, b) => {
       const aFolder = a.children.length > 0 ? 0 : 1;
       const bFolder = b.children.length > 0 ? 0 : 1;
       if (aFolder !== bFolder) return aFolder - bFolder;
-      return a.title.localeCompare(b.title);
+      return (a.title || a.name).localeCompare(b.title || b.name);
     });
   }
+
   for (const node of root) {
     sortNodes(node.children);
   }
@@ -89,55 +83,96 @@ function buildFolderTree(docs: Doc[], section: string): TreeNode[] {
   return sortNodes(root);
 }
 
-/**
+function TreeNodeItem({
- * Recursively render the folder tree with proper depth styling.
+  node,
- * Each level gets a 20px left margin + subtle border for visual hierarchy.
+  depth,
- */
+  pathname,
-function renderTreeNode(
+  collapsedMap,
-  node: TreeNode,
+  toggleCollapse,
-  depth: number,
+}: {
-  pathname: string,
+  node: TreeNode;
-): React.ReactElement {
+  depth: number;
+  pathname: string;
+  collapsedMap: Record<string, boolean>;
+  toggleCollapse: (slug: string) => void;
+}) {
   const isFolder = node.children.length > 0;
   const isActive = pathname === `/${node.slug}`;
-  const hasActiveChild = pathname.startsWith(`/${node.slug}/`);
+  const isParentOfActive = pathname.startsWith(`/${node.slug}/`);
+  const isCollapsed = collapsedMap[node.slug] ?? false;
 
   return (
-    <li key={node.slug} className={depth > 0 ? "ml-5 border-l border-[#1f2022] pl-2" : ""}>
+    <li className={`select-none ${depth > 0 ? "ml-3 pl-2 border-l border-[#1f2022]" : ""}`}>
-      <Link
+      <div
-        href={`/${node.slug}`}
+        className={`group flex items-center justify-between gap-1.5 text-xs py-1.5 px-2 rounded-md transition-all ${
-        className={`flex items-center justify-between gap-1.5 text-xs py-1 px-2 rounded transition-all ${
           isActive
-            ? "text-[#7170ff] bg-[#191a1b]"
+            ? "text-[#7170ff] bg-[#5e6ad2]/15 font-medium border border-[#5e6ad2]/30 shadow-sm"
-            : hasActiveChild
+            : isParentOfActive
-              ? "text-[#d0d6e0]"
+              ? "text-[#d0d6e0] bg-[#141517]/80"
-              : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#191a1b]"
+              : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#141517]"
         }`}
-        title={node.title}
       >
-        <span className="flex items-center gap-1.5 truncate">
+        <Link
-          <span>{isFolder ? "📁" : "📄"}</span>
+          href={`/${node.slug}`}
-          {node.title || node.name}
+          className="flex items-center gap-2 min-w-0 flex-1 py-0.5"
-        </span>
+          title={node.title || node.name}
-        {isFolder && node.docCount > 0 && (
+        >
-          <span className="ml-auto text-[#62666d] bg-[#191a1b] px-1 py-0 rounded">
+          <span className="text-xs shrink-0 opacity-80 group-hover:opacity-100">
-            {node.docCount}
+            {isFolder ? "📁" : "📄"}
           </span>
+          <span className="truncate">{node.title || node.name}</span>
+        </Link>
+
+        {isFolder && (
+          <div className="flex items-center gap-1 shrink-0">
+            <span className="text-[10px] text-[#62666d] bg-[#191a1b] px-1 py-0.2 rounded font-mono">
+              {node.docCount}
+            </span>
+            <button
+              type="button"
+              onClick={(e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                toggleCollapse(node.slug);
+              }}
+              className="p-0.5 text-[#62666d] hover:text-[#d0d6e0] rounded hover:bg-[#23252a] transition-transform"
+              aria-label={isCollapsed ? "Expand folder" : "Collapse folder"}
+            >
+              <svg
+                className={`w-3 h-3 transition-transform duration-200 ${isCollapsed ? "-rotate-90" : "rotate-0"}`}
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+              </svg>
+            </button>
+          </div>
         )}
-      </Link>
+      </div>
-      {node.children.length > 0 && (
+
-        <ul className="mt-0.5 space-y-0.5">
+      {isFolder && !isCollapsed && (
-          {node.children.map((child) => renderTreeNode(child, depth + 1, pathname))}
+        <ul className="mt-0.5 space-y-0.5 animate-fade-in">
+          {node.children.map((child) => (
+            <TreeNodeItem
+              key={child.slug}
+              node={child}
+              depth={depth + 1}
+              pathname={pathname}
+              collapsedMap={collapsedMap}
+              toggleCollapse={toggleCollapse}
+            />
+          ))}
         </ul>
       )}
     </li>
   );
 }
 
-/** 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 [filterText, setFilterText] = useState("");
+  const [collapsedMap, setCollapsedMap] = useState<Record<string, boolean>>({});
   const pathname = usePathname();
 
   useEffect(() => {
@@ -150,40 +185,112 @@ export default function Sidebar() {
       .catch(() => setDocs([]));
   }, []);
 
+  function toggleCollapse(slug: string) {
+    setCollapsedMap((prev) => ({ ...prev, [slug]: !prev[slug] }));
+  }
+
+  const filteredDocs = useMemo(() => {
+    if (!filterText.trim()) return docs;
+    const lower = filterText.toLowerCase();
+    return docs.filter(
+      (d) =>
+        d.title.toLowerCase().includes(lower) ||
+        d.slug.toLowerCase().includes(lower) ||
+        d.tags.some((t) => t.toLowerCase().includes(lower)),
+    );
+  }, [docs, filterText]);
+
   return (
-    <nav className="h-full overflow-y-auto py-6">
+    <nav className="h-full flex flex-col py-4 px-3">
-      <div className="mb-4 px-3">
+      {/* Sidebar search filter */}
-        <span className="text-xs text-[#62666d] uppercase">
+      <div className="mb-3">
-          {docs.length} documents
+        <div className="relative">
-        </span>
+          <input
+            type="text"
+            value={filterText}
+            onChange={(e) => setFilterText(e.target.value)}
+            placeholder="Filter docs..."
+            className="w-full pl-7 pr-3 py-1.5 bg-[#141517] border border-[#23252a] hover:border-[#383b42] rounded-md text-xs text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] transition-colors"
+          />
+          <svg
+            className="w-3.5 h-3.5 text-[#62666d] absolute left-2 top-2.5"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+          </svg>
+          {filterText && (
+            <button
+              onClick={() => setFilterText("")}
+              className="absolute right-2 top-2 text-xs text-[#62666d] hover:text-[#d0d6e0]"
+            >
+              ✕
+            </button>
+          )}
+        </div>
       </div>
-      <ul className="space-y-3 px-3 text-sm">
+
+      {/* Summary count */}
+      <div className="flex items-center justify-between px-1 mb-3 text-[11px] text-[#62666d]">
+        <span className="uppercase tracking-wider font-mono">Documentation</span>
+        <span>{filteredDocs.length} items</span>
+      </div>
+
+      {/* Section Trees */}
+      <div className="flex-1 overflow-y-auto space-y-4 pr-1">
         {SECTIONS.map(({ id, label, icon }) => {
-          const sectionDocs = docs.filter((d) => d.section === id);
+          const sectionDocs = filteredDocs.filter((d) => d.section === id);
           if (sectionDocs.length === 0) return null;
 
-          const tree = buildFolderTree(docs, id);
+          const tree = buildFolderTree(filteredDocs, id);
-          const isActive = pathname === `/${id}` || pathname.startsWith(`/${id}/`);
+          const isSectionActive = pathname === `/${id}` || pathname.startsWith(`/${id}/`);
 
           return (
-            <li key={id} className="border-b border-[#141516] pb-2 last:border-0">
+            <div key={id} className="border-b border-[#141516] pb-3 last:border-0">
-              <div
+              <Link
-                className={`flex items-center gap-1.5 mb-1.5 ${
+                href={`/${id}`}
-                  isActive ? "text-[#7170ff]" : "text-[#62666d]"
+                className={`flex items-center justify-between gap-1.5 px-1 py-1 mb-1 rounded text-xs font-semibold uppercase tracking-wider transition-colors ${
+                  isSectionActive
+                    ? "text-[#7170ff]"
+                    : "text-[#8a8f98] hover:text-[#d0d6e0]"
                 }`}
               >
-                <span className="text-lg">{icon}</span>
+                <div className="flex items-center gap-1.5">
-                <span className="font-medium text-xs uppercase tracking-wider">
+                  <span>{icon}</span>
-                  {label}
+                  <span>{label}</span>
+                </div>
+                <span className="text-[10px] text-[#62666d] font-normal font-mono">
+                  {sectionDocs.length}
                 </span>
-              </div>
+              </Link>
-              <ul className="space-y-0.5">
+
-                {tree.map((node) => renderTreeNode(node, 0, pathname))}
+              <ul className="space-y-0.5 mt-1">
+                {tree.map((node) => (
+                  <TreeNodeItem
+                    key={node.slug}
+                    node={node}
+                    depth={0}
+                    pathname={pathname}
+                    collapsedMap={collapsedMap}
+                    toggleCollapse={toggleCollapse}
+                  />
+                ))}
               </ul>
-            </li>
+            </div>
           );
         })}
-      </ul>
+      </div>
+
+      {/* Bottom quick links */}
+      <div className="pt-3 border-t border-[#1f2022] mt-auto">
+        <Link
+          href="/create"
+          className="flex items-center justify-center gap-1.5 w-full py-1.5 text-xs bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] text-[#d0d6e0] hover:text-white rounded-md transition-colors font-medium"
+        >
+          <span>+ Create New Document</span>
+        </Link>
+      </div>
     </nav>
   );
 }

apps/web/app/components/TOC.tsx

@@ -10,11 +10,9 @@ interface TOCEntry {
   level: number;
 }
 
-/** Extract h2/h3 headings from markdown and render as a clickable TOC. The
- *  heading `id`s are generated by rehype-slug (via github-slugger) in Markdown.tsx,
- *  so the same slugger is used here to produce matching anchors. */
 export default function TOC({ source }: { source: string }) {
   const [toc, setToc] = useState<TOCEntry[]>([]);
+  const [activeId, setActiveId] = useState<string>("");
 
   useEffect(() => {
     const slugger = new GithubSlugger();
@@ -31,24 +29,79 @@ export default function TOC({ source }: { source: string }) {
     setToc(entries);
   }, [source]);
 
+  // Scroll spy using IntersectionObserver
+  useEffect(() => {
+    if (toc.length === 0) return;
+
+    const headingElements = toc
+      .map((entry) => document.getElementById(entry.id))
+      .filter((el): el is HTMLElement => el !== null);
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+            break;
+          }
+        }
+      },
+      {
+        rootMargin: "-80px 0% -60% 0%",
+        threshold: 0.1,
+      },
+    );
+
+    headingElements.forEach((el) => observer.observe(el));
+    return () => observer.disconnect();
+  }, [toc]);
+
   if (toc.length === 0) return null;
 
   return (
-    <nav className="mb-6 text-sm">
+    <nav className="text-xs">
-      <h3 className="text-xs font-semibold text-zinc-500 uppercase mb-2">
+      <div className="flex items-center gap-2 mb-3 pb-2 border-b border-[#1f2022]">
-        Contents
+        <svg className="w-3.5 h-3.5 text-[#7170ff]" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-      </h3>
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h7" />
-      <ul className="space-y-1">
+        </svg>
-        {toc.map((entry) => (
+        <span className="font-semibold uppercase tracking-wider text-[#8a8f98] text-[11px]">
-          <li key={entry.id} className={entry.level === 3 ? "ml-3" : ""}>
+          On this page
-            <Link
+        </span>
-              href={`#${entry.id}`}
+      </div>
-              className="text-zinc-600 dark:text-zinc-400 hover:text-zinc-900 dark:hover:text-zinc-200 hover:underline"
+
+      <ul className="space-y-1.5 border-l border-[#1f2022] pl-2.5">
+        {toc.map((entry) => {
+          const isActive = activeId === entry.id;
+          return (
+            <li
+              key={entry.id}
+              className={`transition-all ${entry.level === 3 ? "ml-3" : ""}`}
             >
-              {entry.text}
+              <Link
-            </Link>
+                href={`#${entry.id}`}
-          </li>
+                onClick={(e) => {
-        ))}
+                  e.preventDefault();
+                  const target = document.getElementById(entry.id);
+                  if (target) {
+                    const offset = 80;
+                    const top = target.getBoundingClientRect().top + window.scrollY - offset;
+                    window.scrollTo({ top, behavior: "smooth" });
+                    setActiveId(entry.id);
+                    history.pushState(null, "", `#${entry.id}`);
+                  }
+                }}
+                className={`block py-0.5 transition-colors line-clamp-1 ${
+                  isActive
+                    ? "text-[#7170ff] font-medium translate-x-0.5"
+                    : "text-[#8a8f98] hover:text-[#d0d6e0]"
+                }`}
+                title={entry.text}
+              >
+                {entry.text}
+              </Link>
+            </li>
+          );
+        })}
       </ul>
     </nav>
   );

apps/web/app/create/page.tsx

@@ -1,3 +1,4 @@
+import Link from "next/link";
 import { listDocuments, extractFoldersForSection } from "@mcpedia/core";
 import { SECTIONS } from "@mcpedia/config/sections";
 import { WEBHOOK_SECRET } from "@mcpedia/config";
@@ -5,6 +6,8 @@ import { cookies } from "next/headers";
 import { redirect } from "next/navigation";
 import DocForm from "@/components/DocForm";
 
+export const dynamic = "force-dynamic";
+
 export default async function CreatePage() {
   const cookieStore = await cookies();
   const isAdmin = cookieStore.get("mcpedia_admin")?.value != null;
@@ -14,10 +17,29 @@ export default async function CreatePage() {
   const docPaths = all.map((d) => d.path);
 
   return (
-    <div>
+    <div className="space-y-6">
-      <div className="flex items-center gap-2 mb-6">
+      {/* Breadcrumb */}
-        <span className="text-2xl">✏️</span>
+      <nav className="flex items-center gap-2 text-xs text-[#62666d]">
-        <h1 className="text-2xl font-medium text-[#f7f8f8]">Create Document</h1>
+        <Link href="/" className="hover:text-[#d0d6e0] transition-colors">
+          MCPedia
+        </Link>
+        <span>/</span>
+        <span className="text-[#8a8f98] font-medium">Create Document</span>
+      </nav>
+
+      {/* Header */}
+      <div className="flex items-center justify-between pb-4 border-b border-[#1f2022]">
+        <div className="flex items-center gap-3">
+          <div className="w-10 h-10 rounded-lg bg-[#5e6ad2]/15 border border-[#5e6ad2]/30 flex items-center justify-center text-xl text-[#7170ff]">
+            ✏️
+          </div>
+          <div>
+            <h1 className="text-2xl font-bold text-[#f7f8f8] tracking-tight">Create Document</h1>
+            <p className="text-xs text-[#8a8f98] mt-0.5">
+              Writes markdown file to disk, records revision, and computes 2048-dim vector embeddings.
+            </p>
+          </div>
+        </div>
       </div>
 
       <DocForm

apps/web/app/globals.css

@@ -1,7 +1,7 @@
 @import "tailwindcss";
 @plugin "@tailwindcss/typography";
 
-/* Linear design system: dark-mode-first */
+/* Modern Linear / Vercel style dark-mode-first tokens */
 @custom-variant dark (&:where(.dark, .dark *));
 
 @theme inline {
@@ -10,10 +10,11 @@
 
   --color-background: #08090a;
   --color-surface: #0f1011;
-  --color-elevated: #191a1b;
+  --color-elevated: #141517;
+  --color-elevated-hover: #1b1d20;
   --color-border: #1f2022;
-  --color-border-subtle: rgba(255, 255, 255, 0.05);
+  --color-border-subtle: rgba(255, 255, 255, 0.06);
-  --color-border-standard: rgba(255, 255, 255, 0.08);
+  --color-border-standard: rgba(255, 255, 255, 0.1);
 
   --color-text-primary: #f7f8f8;
   --color-text-secondary: #d0d6e0;
@@ -27,6 +28,7 @@
 
 html {
   scroll-behavior: smooth;
+  color-scheme: dark;
 }
 
 body {
@@ -34,55 +36,132 @@ body {
   color: var(--color-text-secondary);
   font-family: var(--font-sans);
   font-feature-settings: "cv01", "ss03";
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
 }
 
-/* Inter font loading */
+/* Custom scrollbar */
-@font-face {
+::-webkit-scrollbar {
-  font-family: "Inter";
+  width: 6px;
-  font-weight: 200 900;
+  height: 6px;
-  font-display: swap;
-  src: url("https://fonts.gstatic.com/s/inter/v19/UcCO3FwrK3iLTeHuS_nVMrNCGw.woff2") format("woff2");
 }
 
-/* Custom prose styles for dark theme — tables */
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #23252a;
+  border-radius: 9999px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #383b42;
+}
+
+/* Glassmorphism helpers */
+.glass-panel {
+  background: rgba(15, 16, 17, 0.75);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.glass-nav {
+  background: rgba(8, 9, 10, 0.85);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+/* Prose markdown typography */
 .prose table {
   width: 100%;
-  border-collapse: collapse;
+  border-collapse: separate;
-  margin: 1.5rem 0;
+  border-spacing: 0;
-  font-size: 0.9rem;
+  margin: 1.75rem 0;
+  font-size: 0.875rem;
+  border-radius: 0.5rem;
+  overflow: hidden;
+  border: 1px solid #1f2022;
 }
 
 .prose th,
 .prose td {
-  border: 1px solid var(--color-border);
+  padding: 0.75rem 1rem;
-  padding: 0.5rem 0.75rem;
   text-align: left;
+  border-bottom: 1px solid #1f2022;
 }
 
 .prose th {
-  background: var(--color-elevated);
+  background: #141517;
-  color: var(--color-text-primary);
+  color: #f7f8f8;
   font-weight: 600;
+  font-size: 0.8125rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
 }
 
 .prose td {
-  color: var(--color-text-secondary);
+  color: #d0d6e0;
 }
 
-.prose tbody tr:nth-child(even) {
+.prose tbody tr:last-child td {
-  background: rgba(15, 16, 17, 0.5);
+  border-bottom: none;
+}
+
+.prose tbody tr:hover {
+  background: rgba(255, 255, 255, 0.02);
+}
+
+.prose pre {
+  background: #0d0e0f !important;
+  border: 1px solid #1f2022;
+  border-radius: 0.625rem;
+  padding: 1rem 1.25rem;
+  overflow-x: auto;
+  position: relative;
 }
 
-/* Inline code in prose */
 .prose code {
   font-family: var(--font-mono);
   font-size: 0.85em;
+  color: #e2e4e7;
 }
 
-/* Blockquote styling */
+.prose :not(pre) > code {
+  background: #141517;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  padding: 0.15rem 0.35rem;
+  border-radius: 0.25rem;
+  font-weight: 400;
+}
+
+.prose :not(pre) > code::before,
+.prose :not(pre) > code::after {
+  content: none !important;
+}
+
 .prose blockquote {
-  border-left: 2px solid var(--color-border);
+  border-left: 3px solid #5e6ad2;
+  background: rgba(94, 106, 210, 0.05);
+  border-radius: 0 0.375rem 0.375rem 0;
   margin: 1.5em 0;
-  padding: 0.25em 1em;
+  padding: 0.75em 1.25em;
-  font-style: italic;
+  font-style: normal;
+  color: #a0a4a8;
+}
+
+.prose hr {
+  border-color: #1f2022;
+  margin: 2.5rem 0;
+}
+
+/* Animations */
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.animate-fade-in {
+  animation: fadeIn 0.2s ease-out forwards;
 }

apps/web/app/layout.tsx

@@ -1,9 +1,7 @@
 import type { Metadata } from "next";
-import Link from "next/link";
 import "./globals.css";
-import ThemeToggle from "@/components/ThemeToggle";
+import Header from "@/components/Header";
 import Sidebar from "@/components/Sidebar";
-import { SECTIONS } from "@mcpedia/config/sections";
 
 export const metadata: Metadata = {
   title: "MCPedia — Knowledge base for humans and AI agents",
@@ -18,51 +16,20 @@ export default function RootLayout({
 }>) {
   return (
     <html lang="en" className="h-full scroll-smooth">
-      <body className="min-h-screen bg-[#08090a] text-[#e2e4e7] font-inter">
+      <body className="min-h-screen bg-[#08090a] text-[#e2e4e7] font-sans antialiased selection:bg-[#5e6ad2]/30 selection:text-white flex flex-col">
         <div hidden>
-          {/* hidden aria-live container for screen readers */}
           <div id="a11y-live-region" aria-live="polite" aria-atomic="true" />
         </div>
 
-        <header className="sticky top-0 z-20 border-b border-[#1f2022]">
+        <Header />
-          <div className="mx-auto max-w-7xl px-4 h-14 flex items-center justify-between">
-            <Link href="/" className="font-medium text-[#f7f8f8] text-lg">
-              MCPedia
-            </Link>
-            <nav className="flex items-center gap-6 text-sm">
-              {SECTIONS.map((s) => (
-                <Link
-                  key={s.id}
-                  href={`/${s.id}`}
-                  className="text-[#d0d6e0] hover:text-[#f7f8f8] transition-colors"
-                >
-                  {s.label}
-                </Link>
-              ))}
-              <Link
-                href="/search"
-                className="text-[#d0d6e0] hover:text-[#f7f8f8] transition-colors"
-              >
-                Search
-              </Link>
-              <Link
-                href="/login"
-                className="text-[#d0d6e0] hover:text-[#f7f8f8] transition-colors"
-              >
-                Login
-              </Link>
-              <ThemeToggle />
-            </nav>
-          </div>
-        </header>
 
-        <div className="mx-auto max-w-7xl">
+        <div className="mx-auto max-w-7xl w-full flex-1 flex flex-col">
-          <div className="flex">
+          <div className="flex flex-1">
-            <aside className="hidden xl:block w-64 shrink-0 border-r border-[#1f2022]">
+            <aside className="hidden lg:block w-72 shrink-0 border-r border-[#1f2022] sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto">
               <Sidebar />
             </aside>
             <main className="flex-1 min-w-0">
-              <div className="px-8 py-10 max-w-4xl mx-auto lg:max-w-5xl xl:max-w-6xl">
+              <div className="px-4 sm:px-8 py-8 sm:py-10 max-w-4xl mx-auto xl:max-w-5xl">
                 {children}
               </div>
             </main>

apps/web/app/login/page.tsx

@@ -4,12 +4,10 @@ import { useState } from "react";
 import { useRouter } from "next/navigation";
 import Link from "next/link";
 
-// Simple admin login form. POSTs password to /api/auth/login.
-// On success, the API sets an HTTP-only cookie. We don't touch the cookie
-// client-side (it's HttpOnly) — just redirect to /create after login.
 export default function LoginPage() {
   const router = useRouter();
   const [password, setPassword] = useState("");
+  const [showPassword, setShowPassword] = useState(false);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -27,7 +25,7 @@ export default function LoginPage() {
 
       if (!res.ok) {
         const data = await res.json().catch(() => ({}));
-        throw new Error(data.error ?? "Login failed");
+        throw new Error(data.error ?? "Invalid password. Check ADMIN_PASSWORD.");
       }
 
       router.push("/create");
@@ -39,49 +37,72 @@ export default function LoginPage() {
   }
 
   return (
-    <div className="flex min-h-[60vh] items-center justify-center">
+    <div className="flex min-h-[65vh] items-center justify-center px-4">
-      <div className="w-full max-w-sm">
+      <div className="w-full max-w-md bg-[#0f1011] border border-[#1f2022] rounded-2xl p-6 sm:p-8 shadow-2xl relative overflow-hidden">
-        <h1 className="text-2xl font-light text-[#f7f8f8] mb-2">Admin Login</h1>
+        {/* Top decorative glow */}
-        <p className="text-[#8a8f98] text-sm mb-6">
+        <div className="absolute -top-12 left-1/2 -translate-x-1/2 w-48 h-24 bg-[#5e6ad2]/20 blur-2xl pointer-events-none rounded-full" />
-          Enter your admin password to manage documents.
+
-        </p>
+        <div className="text-center mb-8">
+          <div className="w-12 h-12 rounded-xl bg-[#5e6ad2] text-white font-bold text-xl flex items-center justify-center mx-auto mb-3 shadow-lg shadow-[#5e6ad2]/25">
+            M
+          </div>
+          <h1 className="text-2xl font-bold text-[#f7f8f8] tracking-tight">Admin Authentication</h1>
+          <p className="text-xs text-[#8a8f98] mt-1.5">
+            Enter your admin password to create, edit, or delete documents.
+          </p>
+        </div>
 
         {error && (
-          <div className="p-3 mb-4 rounded border border-[#274360] text-[#fca5a5] text-sm">
+          <div className="p-3.5 mb-6 rounded-lg border border-rose-500/30 bg-rose-500/10 text-rose-400 text-xs">
             {error}
           </div>
         )}
 
         <form onSubmit={handleSubmit} className="space-y-4">
           <div>
-            <label className="block text-xs font-medium text-[#d0d6e0] mb-1">
+            <label className="block text-xs font-semibold uppercase tracking-wider text-[#8a8f98] mb-1.5">
-              Password
+              Admin Password
             </label>
-            <input
+            <div className="relative">
-              type="password"
+              <input
-              value={password}
+                type={showPassword ? "text" : "password"}
-              onChange={(e) => setPassword(e.target.value)}
+                value={password}
-              className="w-full px-3 py-2 bg-[#0f1011] border border-[#23252a] rounded text-[#f7f8f8] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2]"
+                onChange={(e) => setPassword(e.target.value)}
-              required
+                placeholder="Enter password..."
-              autoFocus
+                className="w-full px-3.5 py-2.5 bg-[#141517] border border-[#23252a] hover:border-[#383b42] rounded-lg text-sm text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2] transition-colors"
-            />
+                required
+                autoFocus
+              />
+              <button
+                type="button"
+                onClick={() => setShowPassword(!showPassword)}
+                className="absolute right-3 top-2.5 text-xs text-[#62666d] hover:text-[#d0d6e0]"
+              >
+                {showPassword ? "Hide" : "Show"}
+              </button>
+            </div>
           </div>
+
           <button
             type="submit"
             disabled={loading}
-            className="w-full px-4 py-2 bg-[#5e6ad2] text-white rounded hover:bg-[#7170ff] transition-colors disabled:opacity-50 font-medium text-sm"
+            className="w-full py-2.5 bg-[#5e6ad2] hover:bg-[#6a75e0] text-white rounded-lg transition-all font-medium text-sm shadow-md shadow-[#5e6ad2]/20 disabled:opacity-50 flex items-center justify-center gap-2"
           >
-            {loading ? "Logging in..." : "Login"}
+            {loading && (
+              <div className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin" />
+            )}
+            <span>{loading ? "Authenticating..." : "Sign In"}</span>
           </button>
         </form>
 
-        <div className="mt-6">
+        <div className="mt-8 pt-6 border-t border-[#1a1b1d] flex items-center justify-between text-xs text-[#8a8f98]">
           <Link
             href="/"
-            className="text-sm text-[#8a8f98] hover:text-[#d0d6e0] transition-colors"
+            className="hover:text-[#d0d6e0] transition-colors"
           >
-            ← Back to home
+            ← Back to Home
           </Link>
+          <span className="text-[11px] text-[#62666d]">HTTP-only Secure Cookie</span>
         </div>
       </div>
     </div>

apps/web/app/page.tsx

@@ -1,13 +1,10 @@
 import Link from "next/link";
 import { listDocuments } from "@mcpedia/core";
 import { SECTIONS } from "@mcpedia/config/sections";
+import McpConfigSnippet from "@/components/McpConfigSnippet";
 
 export const dynamic = "force-dynamic";
 
-/**
- * Build a hierarchical folder tree from document list.
- * Each node is either a folder (has children) or a leaf doc.
- */
 interface TreeNode {
   name: string;
   slug: string;
@@ -16,7 +13,6 @@ interface TreeNode {
   isLeaf: boolean;
 }
 
-// Helper: turn a slug segment into a display title
 function slugToTitle(segment: string): string {
   return segment
     .split(/[-_]/)
@@ -30,7 +26,6 @@ function buildFolderTree(docs: { slug: string; title: string }[], section: strin
 
   for (const doc of docs) {
     const parts = doc.slug.split("/");
-    // parts[0] should be the section
     let current = tree;
     let currentPath = section;
 
@@ -62,7 +57,6 @@ function buildFolderTree(docs: { slug: string; title: string }[], section: strin
     }
   }
 
-  // Sort: folders first, then docs, alphabetically
   function sortNodes(nodes: TreeNode[]): TreeNode[] {
     return nodes.sort((a, b) => {
       const aFolder = a.children.length > 0 ? 0 : 1;
@@ -85,23 +79,23 @@ function buildFolderTree(docs: { slug: string; title: string }[], section: strin
 
 function renderTree(nodes: TreeNode[], pathname: string) {
   return (
-    <ul className="space-y-0.5">
+    <ul className="space-y-1">
       {nodes.map((node) => (
         <li key={node.slug}>
           <Link
             href={`/${node.slug}`}
-            className={`flex items-center gap-1.5 text-xs py-0.5 rounded transition-all ${
+            className={`flex items-center gap-1.5 text-xs py-1 px-1.5 rounded transition-all ${
               pathname === `/${node.slug}`
-                ? "text-[#7170ff] bg-[#191a1b]"
+                ? "text-[#7170ff] bg-[#5e6ad2]/15 font-medium"
-                : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#191a1b]"
+                : "text-[#8a8f98] hover:text-[#d0d6e0] hover:bg-[#141517]"
             }`}
             title={node.title}
           >
-            <span>{node.isLeaf && node.children.length === 0 ? "📄" : "📁"}</span>
+            <span className="opacity-70">{node.isLeaf && node.children.length === 0 ? "📄" : "📁"}</span>
             <span className="truncate">{node.title || node.name}</span>
           </Link>
           {node.children.length > 0 && (
-            <div className="ml-5 border-l border-[#1f2022] pl-2 mt-0.5">
+            <div className="ml-3.5 border-l border-[#1f2022] pl-2 mt-0.5">
               {renderTree(node.children, pathname)}
             </div>
           )}
@@ -127,10 +121,6 @@ function SectionTree({ section, docs, pathname }: SectionTreeProps) {
 
   return (
     <div>
-      <div className="flex items-center gap-1.5 mb-2">
-        <span className="text-xl">{sectionInfo.icon}</span>
-        <h3 className="font-medium text-[#f7f8f8]">{sectionInfo.label}</h3>
-      </div>
       {tree.length > 0 ? (
         renderTree(tree, pathname)
       ) : (
@@ -151,70 +141,114 @@ export default async function HomePage() {
     .slice(0, 6);
 
   return (
-    <>
+    <div className="space-y-16">
-      {/* Hero */}
+      {/* Hero Section */}
-      <section className="mb-16">
+      <section className="relative pt-4 pb-2">
-        <div className="max-w-3xl">
+        <div className="inline-flex items-center gap-2 px-3 py-1 rounded-full bg-[#5e6ad2]/10 border border-[#5e6ad2]/25 text-[#7170ff] text-xs font-medium mb-6">
-          <h1 className="text-5xl font-medium text-[#f7f8f8] mb-4 leading-tight">
+          <span className="w-2 h-2 rounded-full bg-[#5e6ad2] animate-pulse" />
-            MCPedia
+          <span>Model Context Protocol + Unified Knowledge Base</span>
-          </h1>
+        </div>
-          <p className="text-xl text-[#8a8f98] mb-8 leading-relaxed max-w-2xl">
-            A content-first knowledge base for humans and AI agents. Browse the
-            hierarchical folder structure below, search all documents, or connect
-            via the MCP server.
-          </p>
 
-          <div className="flex flex-col sm:flex-row gap-3 mb-8">
+        <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold text-[#f7f8f8] tracking-tight mb-5 leading-tight">
-            <Link
+          Knowledge Base for <br />
-              href="/docs"
+          <span className="bg-gradient-to-r from-[#7170ff] via-[#828fff] to-white bg-clip-text text-transparent">
-              className="inline-flex items-center justify-center gap-2 px-6 py-3 bg-[#5e6ad2] text-white rounded-lg font-medium hover:bg-[#6a75e0] transition-colors"
+            Humans and AI Agents
-            >
+          </span>
-              Browse Documents
+        </h1>
-            </Link>
+
-            <Link
+        <p className="text-base sm:text-lg text-[#8a8f98] max-w-2xl leading-relaxed mb-8">
-              href="/search"
+          A high-performance, content-first documentation system. Browse hierarchical notes and CTF writeups in your browser, or connect AI coding assistants directly via native MCP tools.
-              className="inline-flex items-center justify-center gap-2 px-6 py-3 bg-[#191a1b] border border-[#222] text-[#d0d6e0] rounded-lg font-medium hover:border-[#5e6ad2]/40 hover:text-[#f7f8f8] transition-colors"
+        </p>
-            >
+
-              Search
+        {/* Quick action buttons & stats */}
-            </Link>
+        <div className="flex flex-wrap items-center gap-3 mb-10">
+          <Link
+            href="/docs"
+            className="inline-flex items-center gap-2 px-5 py-2.5 bg-[#5e6ad2] hover:bg-[#6a75e0] text-white rounded-lg font-medium text-sm transition-all shadow-md shadow-[#5e6ad2]/20"
+          >
+            <span>Browse Documentation</span>
+            <span>→</span>
+          </Link>
+          <Link
+            href="/search"
+            className="inline-flex items-center gap-2 px-5 py-2.5 bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] hover:border-[#383b42] text-[#d0d6e0] hover:text-white rounded-lg font-medium text-sm transition-all"
+          >
+            <svg className="w-4 h-4 text-[#8a8f98]" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+            </svg>
+            <span>Hybrid Search</span>
+          </Link>
+          <Link
+            href="/create"
+            className="inline-flex items-center gap-1.5 px-4 py-2.5 bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] text-[#8a8f98] hover:text-[#d0d6e0] rounded-lg text-sm transition-colors"
+          >
+            <span>+ Create Document</span>
+          </Link>
+        </div>
+
+        {/* Stats bar */}
+        <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 p-4 bg-[#0c0d0e] border border-[#1f2022] rounded-xl max-w-3xl">
+          <div>
+            <div className="text-xl font-semibold text-[#f7f8f8]">{all.length}</div>
+            <div className="text-xs text-[#62666d]">Documents indexed</div>
+          </div>
+          <div>
+            <div className="text-xl font-semibold text-[#f7f8f8]">{SECTIONS.length}</div>
+            <div className="text-xs text-[#62666d]">Core sections</div>
+          </div>
+          <div>
+            <div className="text-xl font-semibold text-[#7170ff]">RRF Hybrid</div>
+            <div className="text-xs text-[#62666d]">FTS + 2048-dim vectors</div>
+          </div>
+          <div>
+            <div className="text-xl font-semibold text-emerald-400">10 MCP Tools</div>
+            <div className="text-xs text-[#62666d]">Streamable HTTP :4021</div>
           </div>
         </div>
       </section>
 
-      {/* Hierarchical Folder Tree */}
+      {/* Browse by Section */}
-      <section className="mb-16">
+      <section>
-        <h2 className="text-sm font-medium text-[#d0d6e0] uppercase mb-6">
+        <div className="flex items-center justify-between mb-6">
-          Browse by section
+          <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider">
-        </h2>
+            Browse by Section
+          </h2>
+        </div>
+
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
           {SECTIONS.map((s) => {
             const sectionDocs = all.filter((d) => d.section === s.id);
             return (
               <div
                 key={s.id}
-                className="group block bg-[#0f1011] border border-[#1f2022] rounded-lg p-5 hover:border-[#5e6ad2]/40 hover:bg-[#131415] transition-all duration-200"
+                className="group flex flex-col justify-between bg-[#0f1011] hover:bg-[#131415] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-xl p-5 transition-all shadow-sm"
               >
-                <div className="flex items-start justify-between gap-2 mb-3">
+                <div>
-                  <span className="text-2xl">{s.icon}</span>
+                  <div className="flex items-center justify-between gap-2 mb-3">
-                  <Link
+                    <span className="text-2xl">{s.icon}</span>
-                    href={`/${s.id}`}
+                    <Link
-                    className="text-xs text-[#62666d] hover:text-[#7170ff] transition-colors"
+                      href={`/${s.id}`}
-                  >
+                      className="text-xs font-mono text-[#7170ff] hover:underline"
-                    View all ({sectionDocs.length})
+                    >
-                  </Link>
+                      {sectionDocs.length} docs →
+                    </Link>
+                  </div>
+                  <h3 className="font-semibold text-base text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors mb-1.5">
+                    {s.label}
+                  </h3>
+                  <p className="text-xs text-[#8a8f98] mb-4 line-clamp-2 leading-relaxed">
+                    {s.desc}
+                  </p>
                 </div>
-                <h3 className="font-medium text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors mb-3">
+
-                  {s.label}
-                </h3>
-                <p className="text-xs text-[#8a8f98] mb-3 line-clamp-2">
-                  {s.desc}
-                </p>
                 {/* Inline folder tree */}
-                <SectionTree
+                <div className="pt-3 border-t border-[#1a1b1d]">
-                  section={s.id}
+                  <SectionTree
-                  docs={all.map((d) => ({ slug: d.slug, title: d.title }))}
+                    section={s.id}
-                  pathname="/"
+                    docs={all.map((d) => ({ slug: d.slug, title: d.title }))}
-                />
+                    pathname="/"
+                  />
+                </div>
               </div>
             );
           })}
@@ -223,18 +257,19 @@ export default async function HomePage() {
 
       {/* Recent Documents */}
       {recent.length > 0 && (
-        <section className="mb-16">
+        <section>
-          <div className="flex items-baseline justify-between mb-6">
+          <div className="flex items-center justify-between mb-6">
-            <h2 className="text-sm font-medium text-[#d0d6e0] uppercase">
+            <h2 className="text-xs font-semibold text-[#8a8f98] uppercase tracking-wider">
-              Recently updated
+              Recently Updated Knowledge
             </h2>
             <Link
               href="/docs"
-              className="text-xs text-[#62666d] hover:text-[#7170ff] transition-colors"
+              className="text-xs text-[#7170ff] hover:underline"
             >
-              View all →
+              View all ({all.length}) →
             </Link>
           </div>
+
           <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
             {recent.map((d) => {
               const sInfo = SECTIONS.find((s) => s.id === d.section);
@@ -242,32 +277,34 @@ export default async function HomePage() {
                 <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"
+                  className="group block bg-[#0f1011] hover:bg-[#131415] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-xl p-4 transition-all shadow-sm"
                 >
-                  <div className="flex items-start justify-between gap-2 mb-2">
+                  <div className="flex items-center justify-between gap-2 mb-2">
-                    <span className="text-xl">
+                    <span className="text-xs font-mono text-[#7170ff] uppercase">
-                      {sInfo?.icon || "📄"}
+                      {sInfo?.icon} {d.section}
                     </span>
-                    <time className="text-xs text-[#62666d]">
+                    <time className="text-[11px] text-[#62666d] font-mono">
                       {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">
+                  <h3 className="font-medium text-sm text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors line-clamp-1 mb-2">
                     {d.title}
                   </h3>
-                  <div className="mt-2 flex flex-wrap gap-1">
+                  {d.tags.length > 0 && (
-                    {d.tags.slice(0, 3).map((t) => (
+                    <div className="flex flex-wrap gap-1">
-                      <span
+                      {d.tags.slice(0, 3).map((t) => (
-                        key={t}
+                        <span
-                        className="text-xs px-1.5 py-0.5 bg-[#191a1b] border border-[#23252a] rounded text-[#d0d6e0]"
+                          key={t}
-                      >
+                          className="text-[10px] px-1.5 py-0.25 bg-[#141517] border border-[#23252a] rounded text-[#8a8f98]"
-                        #{t}
+                        >
-                      </span>
+                          #{t}
-                    ))}
+                        </span>
-                  </div>
+                      ))}
+                    </div>
+                  )}
                 </Link>
               );
             })}
@@ -275,29 +312,22 @@ export default async function HomePage() {
         </section>
       )}
 
-      {/* MCP info */}
+      {/* MCP Agent Integration Showcase */}
-      <section className="border-t border-[#1f2022] pt-8">
+      <section className="border-t border-[#1f2022] pt-12 pb-6">
-        <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
+        <div className="mb-6">
-          <div>
+          <div className="inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded bg-[#141517] border border-[#23252a] text-[#8a8f98] text-xs font-mono mb-2">
-            <h3 className="font-medium text-[#f7f8f8] mb-1">AI agents</h3>
+            <span>⚡ Native Model Context Protocol (MCP)</span>
-            <p className="text-sm text-[#8a8f98]">
-              MCP server at{" "}
-              <code className="text-[#d0d6e0] bg-[#191a1b] px-1.5 py-0.5 rounded">
-                mcp.asepharyana.my.id/mcp
-              </code>
-              . All tools available via Streamable HTTP transport.
-            </p>
           </div>
-          <Link
+          <h2 className="text-2xl font-bold text-[#f7f8f8] tracking-tight mb-2">
-            href="https://github.com/modelcontextprotocol"
+            Connect AI Coding Assistants
-            target="_blank"
+          </h2>
-            rel="noopener noreferrer"
+          <p className="text-sm text-[#8a8f98] max-w-xl">
-            className="text-xs text-[#62666d] hover:text-[#7170ff] transition-colors"
+            Give Claude Desktop, Cursor, Antigravity, or Zed direct access to your knowledge base via semantic search, read resources, and document tools.
-          >
+          </p>
-            MCP spec →
-          </Link>
         </div>
+
+        <McpConfigSnippet />
       </section>
-    </>
+    </div>
   );
 }

apps/web/app/search/page.tsx

@@ -3,6 +3,7 @@
 import { useState, useEffect, useCallback, Suspense } from "react";
 import Link from "next/link";
 import { useSearchParams } from "next/navigation";
+import { SECTIONS } from "@mcpedia/config/sections";
 
 interface DocHit {
   slug: string;
@@ -23,6 +24,7 @@ function SearchContent() {
   const [mode, setMode] = useState<SearchMode>(
     ["hybrid", "keyword", "semantic"].includes(initialMode) ? initialMode : "hybrid",
   );
+  const [selectedSection, setSelectedSection] = useState<string>("all");
   const [results, setResults] = useState<DocHit[]>([]);
   const [loading, setLoading] = useState(false);
 
@@ -34,7 +36,7 @@ function SearchContent() {
     setLoading(true);
     try {
       const res = await fetch(
-        `/api/search?q=${encodeURIComponent(q)}&mode=${searchMode}`,
+        `/api/search?q=${encodeURIComponent(q)}&mode=${searchMode}&limit=30`,
       );
       const data = await res.json();
       setResults(data.results || []);
@@ -64,81 +66,195 @@ function SearchContent() {
     }
   }
 
+  const filteredResults = selectedSection === "all"
+    ? results
+    : results.filter((r) => r.section === selectedSection);
+
   return (
-    <div className="max-w-3xl">
+    <div className="max-w-4xl space-y-8">
-      <h1 className="text-2xl font-light text-[#f7f8f8] mb-6">Search</h1>
+      {/* Header */}
+      <div>
+        <h1 className="text-3xl font-bold text-[#f7f8f8] tracking-tight mb-2">
+          Search Knowledge Base
+        </h1>
+        <p className="text-sm text-[#8a8f98]">
+          Find answers across all documentation, CTF writeups, research notes, and semantic vector chunks.
+        </p>
+      </div>
 
-      <div className="space-y-4 mb-8">
+      {/* Search Box & Controls */}
-        <input
+      <div className="bg-[#0f1011] border border-[#1f2022] rounded-xl p-4 sm:p-5 shadow-sm space-y-4">
-          type="search"
+        {/* Search Input */}
-          value={query}
+        <div className="relative">
-          onChange={handleChange}
+          <input
-          placeholder="Search documents by keyword or semantic meaning..."
+            type="search"
-          className="w-full px-4 py-2.5 bg-[#0f1011] border border-[#23252a] rounded-lg text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-1 focus:ring-[#5e6ad2]"
+            value={query}
-          autoFocus
+            onChange={handleChange}
-        />
+            placeholder="Search by keywords, challenge names, tools, concepts..."
+            className="w-full pl-11 pr-10 py-3 bg-[#141517] border border-[#23252a] hover:border-[#383b42] rounded-lg text-[#f7f8f8] placeholder-[#62666d] focus:outline-none focus:border-[#5e6ad2] focus:ring-2 focus:ring-[#5e6ad2]/20 text-base transition-all"
+            autoFocus
+          />
+          <svg
+            className="w-5 h-5 text-[#7170ff] absolute left-3.5 top-3.5"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+          </svg>
+          {query && (
+            <button
+              onClick={() => {
+                setQuery("");
+                setResults([]);
+              }}
+              className="absolute right-3.5 top-3.5 text-xs text-[#62666d] hover:text-[#d0d6e0] p-0.5"
+            >
+              ✕
+            </button>
+          )}
+        </div>
 
-        {/* Mode Selector */}
+        {/* Search Mode & Section Filters */}
-        <div className="flex items-center gap-2 text-xs">
+        <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-3 pt-2 border-t border-[#1a1b1d] text-xs">
-          <span className="text-[#62666d]">Mode:</span>
+          {/* Mode Selector */}
-          {(
+          <div className="flex items-center gap-1.5 flex-wrap">
-            [
+            <span className="text-[#62666d] mr-1">Algorithm:</span>
-              { id: "hybrid", label: "Hybrid (FTS + Semantic)" },
+            {[
-              { id: "keyword", label: "Keyword (FTS)" },
+              { id: "hybrid", label: "⚡ Hybrid (RRF)", desc: "FTS + Vector Fusion" },
-              { id: "semantic", label: "Semantic (Embeddings)" },
+              { id: "keyword", label: "🔍 Keyword", desc: "PostgreSQL FTS" },
-            ] as const
+              { id: "semantic", label: "🧠 Semantic", desc: "Embeddings Cosine" },
-          ).map((m) => (
+            ].map((m) => (
+              <button
+                key={m.id}
+                type="button"
+                onClick={() => handleModeChange(m.id as SearchMode)}
+                title={m.desc}
+                className={`px-3 py-1 rounded-md border font-medium transition-all ${
+                  mode === m.id
+                    ? "bg-[#5e6ad2] border-[#5e6ad2] text-white shadow-sm"
+                    : "bg-[#141517] border-[#23252a] text-[#8a8f98] hover:text-[#d0d6e0]"
+                }`}
+              >
+                {m.label}
+              </button>
+            ))}
+          </div>
+
+          {/* Section Filter Pills */}
+          <div className="flex items-center gap-1 flex-wrap">
             <button
-              key={m.id}
               type="button"
-              onClick={() => handleModeChange(m.id)}
+              onClick={() => setSelectedSection("all")}
-              className={`px-2.5 py-1 rounded border transition-colors ${
+              className={`px-2.5 py-1 rounded-md text-xs transition-colors ${
-                mode === m.id
+                selectedSection === "all"
-                  ? "bg-[#5e6ad2]/15 border-[#5e6ad2] text-[#7170ff]"
+                  ? "bg-[#23252a] text-white"
-                  : "bg-[#0f1011] border-[#1f2022] text-[#8a8f98] hover:text-[#d0d6e0]"
+                  : "text-[#62666d] hover:text-[#8a8f98]"
               }`}
             >
-              {m.label}
+              All Sections
             </button>
-          ))}
+            {SECTIONS.map((s) => (
+              <button
+                key={s.id}
+                type="button"
+                onClick={() => setSelectedSection(s.id)}
+                className={`px-2.5 py-1 rounded-md text-xs transition-colors ${
+                  selectedSection === s.id
+                    ? "bg-[#23252a] text-white"
+                    : "text-[#62666d] hover:text-[#8a8f98]"
+                }`}
+              >
+                {s.label}
+              </button>
+            ))}
+          </div>
         </div>
       </div>
 
-      {loading && <p className="text-[#8a8f98]">Searching...</p>}
+      {/* Loading State */}
-
+      {loading && (
-      {!loading && results.length === 0 && query && (
+        <div className="flex items-center gap-3 py-8 text-[#8a8f98] text-sm">
-        <p className="text-[#8a8f98]">No results found for "{query}".</p>
+          <div className="w-5 h-5 border-2 border-[#5e6ad2] border-t-transparent rounded-full animate-spin" />
+          <span>Searching knowledge base...</span>
+        </div>
       )}
 
-      {!loading && results.length > 0 && (
+      {/* Empty State */}
-        <ul className="space-y-4">
+      {!loading && query && filteredResults.length === 0 && (
-          {results.map((r) => (
+        <div className="text-center py-16 bg-[#0f1011] border border-[#1f2022] rounded-xl">
-            <li
+          <div className="text-3xl mb-3">🔍</div>
-              key={r.slug}
+          <h3 className="text-base font-medium text-[#f7f8f8] mb-1">No matching documents</h3>
-              className="bg-[#0f1011] border border-[#1f2022] rounded-lg p-4 hover:border-[#5e6ad2]/40 transition-colors"
+          <p className="text-xs text-[#8a8f98] max-w-sm mx-auto">
-            >
+            Try switching algorithm mode to <strong>Hybrid</strong> or <strong>Semantic</strong>, or search with different keywords.
-              <Link
+          </p>
-                href={`/${r.slug}`}
+        </div>
-                className="text-[#f7f8f8] hover:text-[#7170ff] font-medium transition-colors block mb-1"
+      )}
+
+      {/* Initial Hint */}
+      {!loading && !query && (
+        <div className="p-8 text-center bg-[#0c0d0e] border border-[#1f2022] rounded-xl space-y-4">
+          <p className="text-xs text-[#8a8f98]">Popular search queries:</p>
+          <div className="flex justify-center flex-wrap gap-2 text-xs">
+            {["stack alignment", "ret2win", "bullmq worker", "streamable http", "full-text search", "caddy reverse proxy"].map((term) => (
+              <button
+                key={term}
+                onClick={() => {
+                  setQuery(term);
+                  handleSearch(term, mode);
+                }}
+                className="px-3 py-1 bg-[#141517] hover:bg-[#1b1d20] border border-[#23252a] hover:border-[#5e6ad2]/40 rounded-md text-[#d0d6e0] transition-colors"
               >
-                {r.title}
+                {term}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Results List */}
+      {!loading && filteredResults.length > 0 && (
+        <div className="space-y-4">
+          <div className="flex items-center justify-between text-xs text-[#62666d]">
+            <span>Found {filteredResults.length} result{filteredResults.length !== 1 ? "s" : ""}</span>
+            <span className="font-mono">Ranked by {mode} score</span>
+          </div>
+
+          <div className="space-y-3">
+            {filteredResults.map((r) => (
+              <Link
+                key={r.slug}
+                href={`/${r.slug}`}
+                className="group block bg-[#0f1011] hover:bg-[#131415] border border-[#1f2022] hover:border-[#5e6ad2]/40 rounded-xl p-4 sm:p-5 transition-all shadow-sm"
+              >
+                <div className="flex items-center justify-between gap-3 mb-2">
+                  <div className="flex items-center gap-2">
+                    <span className="text-xs font-mono px-2 py-0.5 rounded bg-[#5e6ad2]/10 border border-[#5e6ad2]/30 text-[#7170ff] uppercase">
+                      {r.section}
+                    </span>
+                    <span className="text-xs text-[#62666d] font-mono truncate">
+                      /{r.slug}
+                    </span>
+                  </div>
+                  <span className="text-xs font-mono text-[#8a8f98] bg-[#141517] px-2 py-0.5 rounded">
+                    Score: {r.score.toFixed(3)}
+                  </span>
+                </div>
+
+                <h2 className="text-base font-semibold text-[#f7f8f8] group-hover:text-[#7170ff] transition-colors mb-2">
+                  {r.title}
+                </h2>
+
+                {r.snippet && (
+                  <p
+                    className="text-xs text-[#8a8f98] leading-relaxed line-clamp-2 [&>mark]:bg-[#5e6ad2]/30 [&>mark]:text-white [&>mark]:px-1 [&>mark]:rounded [&>mark]:font-medium"
+                    dangerouslySetInnerHTML={{ __html: r.snippet }}
+                  />
+                )}
               </Link>
-              <div className="flex items-center gap-2 text-xs text-[#62666d] mb-2">
+            ))}
-                <span className="uppercase text-[#7170ff]">{r.section}</span>
+          </div>
-                <span>·</span>
+        </div>
-                <span>{r.slug}</span>
-                <span>·</span>
-                <span>Score: {r.score.toFixed(3)}</span>
-              </div>
-              {r.snippet && (
-                <p
-                  className="text-sm text-[#8a8f98] leading-relaxed [&>mark]:bg-[#5e6ad2]/30 [&>mark]:text-[#f7f8f8] [&>mark]:px-1 [&>mark]:rounded"
-                  dangerouslySetInnerHTML={{ __html: r.snippet }}
-                />
-              )}
-            </li>
-          ))}
-        </ul>
       )}
     </div>
   );
@@ -148,9 +264,9 @@ export default function SearchPage() {
   return (
     <Suspense
       fallback={
-        <div className="max-w-3xl">
+        <div className="max-w-4xl py-12">
-          <h1 className="text-2xl font-light text-[#f7f8f8] mb-6">Search</h1>
+          <h1 className="text-2xl font-bold text-[#f7f8f8] mb-4">Search</h1>
-          <p className="text-[#8a8f98]">Loading search...</p>
+          <p className="text-sm text-[#8a8f98]">Loading search module...</p>
         </div>
       }
     >