@@ -53,7 +53,7 @@ apps/web/app/
 └── app.css              # Tailwind + theme tokens
 
 packages/cli/src/        # `skillx` npm package
-├── commands/            # search, use, report, config
+├── commands/            # search, use, publish, report, config
 ├── lib/                 # api-client, config-store
 └── index.ts             # Commander.js entry
 ```
@@ -65,6 +65,8 @@ pnpm install              # Install all dependencies
 pnpm dev                  # Start dev server (apps/web) → http://localhost:5173
 pnpm build                # Build for production
 pnpm typecheck            # TypeScript check
+pnpm test                 # Run unit tests (vitest) once
+pnpm test:watch           # Run unit tests in watch mode
 pnpm seed                 # Seed DB (requires ADMIN_SECRET env var)
 
 # Inside apps/web:
@@ -88,14 +90,16 @@ pnpm db:migrate:remote    # Apply migrations to remote D1
 | `/api/skills/:slug/review` | api.skill-review.ts | Session/Key |
 | `/api/skills/:slug/favorite` | api.skill-favorite.ts | Session/Key |
 | `/api/skills/:slug/install` | api.skill-install.ts | Optional (API key or X-Device-Id) |
+| `/api/skills/:slug/vote` | api.skill-vote.ts | Session |
 | `/api/report` | api.usage-report.ts | Session/Key |
 | `/api/user/api-keys` | api.user-api-keys.ts | Session |
+| `/api/user/interactions` | api.user-interactions.ts | Session (graceful fallback) |
 | `/api/skills/register` | api.skill-register.ts | Session/Key |
 | `/api/admin/seed` | api.admin.seed.ts | Admin secret |
 
 ## Database Tables (Drizzle schema)
 
-`skills`, `ratings`, `reviews`, `favorites`, `usageStats`, `apiKeys`, `installs`
+`skills`, `ratings`, `reviews`, `favorites`, `votes`, `usageStats`, `apiKeys`, `installs`
 Plus Better Auth tables: `user`, `session`, `account`, `verification`
 
 ## Key Patterns
@@ -109,7 +113,11 @@ Search algorithm: `./docs/search-algorithm.md`
 
 **Auth**: `getSession(request, env)` for session, `requireAuth(request, env)` for redirect
 
-**Search**: Query → Embed (Workers AI) → Vectorize + FTS5 parallel → RRF fusion → Boost scoring → Filter → Cache (KV)
+**Search**: Query → Embed (Workers AI) → Vectorize + FTS5 parallel → RRF fusion → 8-signal Boost scoring (RRF 43%, rating 15%, stars 10%, usage 8%, success 7%, votes 7%, recency 5%, favorites 5%) → Filter → Cache (KV)
+
+**Leaderboard**: 7-signal composite scoring (rating 30%, installs 20%, stars 15%, votes 10%, success 10%, recency 10%, favorites 5%). Sort tabs (best/rating/installs/trending/newest), category filter, preview modal. Client-side interaction overlay (votes + favorites) on KV-cached data.
+
+**Vote API**: POST `/api/skills/:slug/vote` with `{ type: 'up'|'down'|'none' }`. Rate limited 10 votes/min per user. Atomic count update via SQL subquery.
 
 **CLI `skillx use` resolution**: `author/skill` (two-part → DB slug `author-skill`) | `org/repo/skill` (three-part → DB slug `org-skill`, fallback register from GitHub) | `slug` (direct lookup, fallback search) | `"keywords"` (search mode)
 
 
@@ -1,63 +1,215 @@
 import { useState, useEffect, useRef, useCallback } from "react";
-import { LeaderboardTable } from "./leaderboard-table";
+import { LeaderboardTable, type LeaderboardEntry } from "./leaderboard-table";
+import { LeaderboardControls } from "./leaderboard-controls";
+import { SkillPreviewModal } from "./skill-preview-modal";
 
 const PAGE_SIZE = 20;
 
-interface LeaderboardEntry {
-  rank: number;
-  slug: string;
-  name: string;
-  author: string;
-  installs: number;
-  rating: number;
-}
-
 interface HomeLeaderboardProps {
   initialEntries: LeaderboardEntry[];
   initialHasMore: boolean;
+  categories: string[];
+  isAuthenticated?: boolean;
 }
 
 export function HomeLeaderboard({
   initialEntries,
   initialHasMore,
+  categories,
+  isAuthenticated = false,
 }: HomeLeaderboardProps) {
   const [entries, setEntries] = useState(initialEntries);
   const [hasMore, setHasMore] = useState(initialHasMore);
   const [isLoading, setIsLoading] = useState(false);
-  const sentinelRef = useRef<HTMLDivElement>(null);
+  const [sort, setSort] = useState("best");
+  const [category, setCategory] = useState("");
+  const [previewEntry, setPreviewEntry] = useState<LeaderboardEntry | null>(null);
 
+  // User interaction state (client-side overlay on KV-cached data)
+  const [userFavorites, setUserFavorites] = useState<Set<string>>(new Set());
+  const [userVotes, setUserVotes] = useState<Map<string, "up" | "down">>(new Map());
+  const [interactionsLoaded, setInteractionsLoaded] = useState(false);
+
+  const sentinelRef = useRef<HTMLDivElement>(null);
   const loadingRef = useRef(false);
   const hasMoreRef = useRef(initialHasMore);
   const entriesLengthRef = useRef(initialEntries.length);
+  const sortRef = useRef("best");
+  const categoryRef = useRef("");
+
+  // Fetch user interactions for displayed entries
+  const fetchInteractions = useCallback(async (slugs: string[]) => {
+    if (!isAuthenticated || slugs.length === 0) return;
+    try {
+      const res = await fetch(`/api/user/interactions?slugs=${slugs.join(",")}`);
+      if (!res.ok) return;
+      const data = await res.json() as { favorites: string[]; votes: Record<string, "up" | "down"> };
+      setUserFavorites((prev) => {
+        const next = new Set(prev);
+        for (const slug of data.favorites) next.add(slug);
+        return next;
+      });
+      setUserVotes((prev) => {
+        const next = new Map(prev);
+        for (const [slug, type] of Object.entries(data.votes)) next.set(slug, type);
+        return next;
+      });
+      setInteractionsLoaded(true);
+    } catch {
+      // Non-blocking — graceful degradation
+    }
+  }, [isAuthenticated]);
 
-  const loadMore = useCallback(async () => {
-    if (loadingRef.current || !hasMoreRef.current) return;
+  // Fetch interactions on mount for initial entries
+  useEffect(() => {
+    if (isAuthenticated && !interactionsLoaded) {
+      fetchInteractions(entries.map((e) => e.slug));
+    }
+  }, [isAuthenticated, interactionsLoaded, entries, fetchInteractions]);
+
+  const fetchEntries = useCallback(async (
+    sortMode: string,
+    cat: string,
+    offset: number,
+    append: boolean,
+  ) => {
+    if (loadingRef.current) return;
     loadingRef.current = true;
     setIsLoading(true);
 
     try {
-      const res = await fetch(
-        `/api/leaderboard?sort=best&offset=${entriesLengthRef.current}&limit=${PAGE_SIZE}`
-      );
-      const data = (await res.json()) as {
-        entries: LeaderboardEntry[];
-        hasMore: boolean;
-      };
-      setEntries((prev) => {
-        const updated = [...prev, ...data.entries];
-        entriesLengthRef.current = updated.length;
-        return updated;
+      const params = new URLSearchParams({
+        sort: sortMode,
+        offset: String(offset),
+        limit: String(PAGE_SIZE),
       });
+      if (cat) params.set("category", cat);
+
+      const res = await fetch(`/api/leaderboard?${params}`);
+      const data = await res.json() as { entries: LeaderboardEntry[]; hasMore: boolean };
+
+      if (append) {
+        setEntries((prev) => {
+          const updated = [...prev, ...data.entries];
+          entriesLengthRef.current = updated.length;
+          return updated;
+        });
+      } else {
+        setEntries(data.entries);
+        entriesLengthRef.current = data.entries.length;
+      }
       hasMoreRef.current = data.hasMore;
       setHasMore(data.hasMore);
+
+      // Fetch interactions for new entries
+      if (isAuthenticated && data.entries.length > 0) {
+        fetchInteractions(data.entries.map((e) => e.slug));
+      }
     } catch {
       // Silent fail — observer retries on next intersection
     } finally {
       loadingRef.current = false;
       setIsLoading(false);
     }
+  }, [isAuthenticated, fetchInteractions]);
+
+  const loadMore = useCallback(() => {
+    if (!hasMoreRef.current || loadingRef.current) return;
+    fetchEntries(sortRef.current, categoryRef.current, entriesLengthRef.current, true);
+  }, [fetchEntries]);
+
+  const handleSortChange = useCallback((newSort: string) => {
+    setSort(newSort);
+    sortRef.current = newSort;
+    entriesLengthRef.current = 0;
+    fetchEntries(newSort, categoryRef.current, 0, false);
+  }, [fetchEntries]);
+
+  const handleCategoryChange = useCallback((newCategory: string) => {
+    setCategory(newCategory);
+    categoryRef.current = newCategory;
+    entriesLengthRef.current = 0;
+    fetchEntries(sortRef.current, newCategory, 0, false);
+  }, [fetchEntries]);
+
+  // Optimistic vote handler
+  const handleVote = useCallback(async (slug: string, type: "up" | "down" | "none") => {
+    const prevVote = userVotes.get(slug) ?? null;
+    const prevNetVotes = entries.find((e) => e.slug === slug)?.netVotes ?? 0;
+
+    // Calculate delta
+    let delta = 0;
+    if (type === "none") {
+      delta = prevVote === "up" ? -1 : prevVote === "down" ? 1 : 0;
+    } else if (type === "up") {
+      delta = prevVote === "down" ? 2 : prevVote === "up" ? 0 : 1;
+    } else {
+      delta = prevVote === "up" ? -2 : prevVote === "down" ? 0 : -1;
+    }
+
+    // Optimistic update
+    setUserVotes((prev) => {
+      const next = new Map(prev);
+      if (type === "none") next.delete(slug);
+      else next.set(slug, type);
+      return next;
+    });
+    setEntries((prev) =>
+      prev.map((e) => (e.slug === slug ? { ...e, netVotes: e.netVotes + delta } : e))
+    );
+
+    try {
+      const res = await fetch(`/api/skills/${slug}/vote`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type }),
+      });
+      if (!res.ok) throw new Error("Vote failed");
+    } catch {
+      // Revert
+      setUserVotes((prev) => {
+        const next = new Map(prev);
+        if (prevVote) next.set(slug, prevVote);
+        else next.delete(slug);
+        return next;
+      });
+      setEntries((prev) =>
+        prev.map((e) => (e.slug === slug ? { ...e, netVotes: prevNetVotes } : e))
+      );
+    }
+  }, [userVotes, entries]);
+
+  // Optimistic favorite handler
+  const handleFavoriteToggle = useCallback(async (slug: string) => {
+    const wasFavorited = userFavorites.has(slug);
+
+    // Optimistic update
+    setUserFavorites((prev) => {
+      const next = new Set(prev);
+      if (wasFavorited) next.delete(slug);
+      else next.add(slug);
+      return next;
+    });
+
+    try {
+      const res = await fetch(`/api/skills/${slug}/favorite`, { method: "POST" });
+      if (!res.ok) throw new Error("Favorite failed");
+    } catch {
+      // Revert
+      setUserFavorites((prev) => {
+        const next = new Set(prev);
+        if (wasFavorited) next.add(slug);
+        else next.delete(slug);
+        return next;
+      });
+    }
+  }, [userFavorites]);
+
+  const handleAuthRequired = useCallback(() => {
+    window.location.href = `/api/auth/signin/github?callbackURL=${encodeURIComponent(window.location.pathname + window.location.search)}`;
   }, []);
 
+  // Infinite scroll observer
   useEffect(() => {
     const sentinel = sentinelRef.current;
     if (!sentinel) return;
@@ -75,7 +227,31 @@ export function HomeLeaderboard({
 
   return (
     <>
-      <LeaderboardTable entries={entries} />
+      <LeaderboardControls
+        sort={sort}
+        onSortChange={handleSortChange}
+        category={category}
+        onCategoryChange={handleCategoryChange}
+        categories={categories}
+      />
+
+      <LeaderboardTable
+        entries={entries}
+        onPreview={setPreviewEntry}
+        userFavorites={userFavorites}
+        userVotes={userVotes}
+        isAuthenticated={isAuthenticated}
+        onVote={handleVote}
+        onFavoriteToggle={handleFavoriteToggle}
+        onAuthRequired={handleAuthRequired}
+      />
+
+      {previewEntry && (
+        <SkillPreviewModal
+          entry={previewEntry}
+          onClose={() => setPreviewEntry(null)}
+        />
+      )}
 
       {/* Infinite scroll sentinel */}
       <div ref={sentinelRef} className="flex justify-center py-8">
 
@@ -0,0 +1,58 @@
+const SORT_OPTIONS = [
+  { value: "best", label: "Best" },
+  { value: "rating", label: "Rating" },
+  { value: "installs", label: "Installs" },
+  { value: "trending", label: "Trending" },
+  { value: "newest", label: "Newest" },
+];
+
+interface LeaderboardControlsProps {
+  sort: string;
+  onSortChange: (sort: string) => void;
+  category: string;
+  onCategoryChange: (category: string) => void;
+  categories: string[];
+}
+
+export function LeaderboardControls({
+  sort,
+  onSortChange,
+  category,
+  onCategoryChange,
+  categories,
+}: LeaderboardControlsProps) {
+  return (
+    <div className="mb-4 flex flex-wrap items-center gap-3">
+      {/* Sort tabs */}
+      <div className="flex gap-1 rounded-lg border border-sx-border bg-sx-bg-elevated p-1">
+        {SORT_OPTIONS.map((opt) => (
+          <button
+            key={opt.value}
+            onClick={() => onSortChange(opt.value)}
+            className={`rounded-md px-3 py-1.5 font-mono text-xs transition-colors ${
+              sort === opt.value
+                ? "bg-sx-accent text-sx-bg font-bold"
+                : "text-sx-fg-muted hover:text-sx-fg"
+            }`}
+          >
+            {opt.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Category filter */}
+      <select
+        value={category}
+        onChange={(e) => onCategoryChange(e.target.value)}
+        className="rounded-lg border border-sx-border bg-sx-bg-elevated px-3 py-1.5 font-mono text-xs text-sx-fg"
+      >
+        <option value="">All Categories</option>
+        {categories.map((c) => (
+          <option key={c} value={c}>
+            {c}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}