feat: add social proof features and comprehensive documentation

Priority 2 - Social Proof:
- Add ToolRating and ToolReview models to Prisma schema
- Add rating aggregates (averageRating, ratingCount, reviewCount) to Tool model
- Create /api/tools/[id]/rate endpoint for tool ratings
- Create /api/tools/[id]/reviews endpoint for tool reviews
- Create /api/tools/trending endpoint for trending tools
- Add Rating component with interactive star rating
- Add ReviewCard component with user avatars and review display
- Add star and starFilled icons to UI package
- Update ToolDetailClient to show ratings

Priority 3 - Documentation:
- Create /docs/api/tools API documentation page
- Create /docs/api/agents API documentation page
- Create /docs/api/collections API documentation page
- Create /docs/api/authentication documentation page
- Create /docs/quickstart getting started tutorial
- Create /docs/sdk SDK reference documentation

packages/db/prisma/schema.prisma

@@ -95,16 +95,26 @@ model Tool {
   createdAt DateTime @default(now()) @map("created_at")
   updatedAt DateTime @updatedAt @map("updated_at")
 
+  // Rating aggregates
+  averageRating Decimal? @map("average_rating") @db.Decimal(2, 1) // 1.0 to 5.0
+  ratingCount   Int      @default(0) @map("rating_count")
+  reviewCount   Int      @default(0) @map("review_count")
+
   // Relations
   simulations  Simulation[]
   healthChecks HealthCheck[]
   collections  CollectionTool[]
   agents       AgentTool[]
   likes        ToolLike[]
+  ratings      ToolRating[]
+  reviews      ToolReview[]
 
   @@unique([packageId, name])
   @@index([qualityScore])
   @@index([likeCount])
+  @@index([averageRating])
+  @@index([ratingCount])
+  @@index([reviewCount])
   @@index([importHealth])
   @@index([executionHealth])
   @@index([lastHealthCheck])
@@ -346,6 +356,8 @@ model User {
   agents           Agent[]
   apiKeys          UserApiKey[]
   toolLikes        ToolLike[]
+  toolRatings      ToolRating[]
+  toolReviews      ToolReview[]
   collectionLikes  CollectionLike[]
   agentLikes       AgentLike[]
   activities       UserActivity[]
@@ -761,6 +773,65 @@ model AgentLike {
   @@map("agent_likes")
 }
 
+/// ToolRating - user ratings for tools (1-5 stars)
+model ToolRating {
+  id        String   @id @default(cuid())
+
+  // Relationships
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  toolId    String   @map("tool_id")
+  tool      Tool     @relation(fields: [toolId], references: [id], onDelete: Cascade)
+
+  // Rating value (1-5)
+  rating    Int      @db.SmallInt
+
+  // Timestamps
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([userId, toolId])
+  @@index([toolId])
+  @@index([userId])
+  @@index([rating])
+  @@map("tool_ratings")
+}
+
+/// ToolReview - user reviews for tools
+model ToolReview {
+  id        String   @id @default(cuid())
+
+  // Relationships
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  toolId    String   @map("tool_id")
+  tool      Tool     @relation(fields: [toolId], references: [id], onDelete: Cascade)
+
+  // Review content
+  title     String?  @db.VarChar(200)
+  content   String   @db.Text
+  rating    Int      @db.SmallInt // 1-5, denormalized for convenience
+
+  // Moderation
+  isApproved Boolean @default(true) @map("is_approved")
+  isHidden   Boolean @default(false) @map("is_hidden")
+
+  // Helpful votes
+  helpfulCount Int   @default(0) @map("helpful_count")
+
+  // Timestamps
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([userId, toolId])
+  @@index([toolId])
+  @@index([userId])
+  @@index([rating])
+  @@index([isApproved, isHidden])
+  @@index([createdAt])
+  @@map("tool_reviews")
+}
+
 // ============================================================================
 // Activity Stream Models
 // ============================================================================

packages/ui/src/Icon/icons.ts

@@ -148,6 +148,14 @@ export const icons = {
     viewBox: '0 0 24 24',
     path: 'M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z',
   },
+  star: {
+    viewBox: '0 0 24 24',
+    path: 'M22 9.24l-7.19-.62L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21 12 17.27 18.18 21l-1.63-7.03L22 9.24zM12 15.4l-3.76 2.27 1-4.28-3.32-2.88 4.38-.38L12 6.1l1.71 4.04 4.38.38-3.32 2.88 1 4.28L12 15.4z',
+  },
+  starFilled: {
+    viewBox: '0 0 24 24',
+    path: 'M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z',
+  },
 } as const;
 
 export type IconName = keyof typeof icons;