Refactor comparisons subsystem to use YAML manifests

.github/workflows/validate-manifests.yml

@@ -0,0 +1,46 @@
+name: Validate Tool Manifests
+
+on:
+  pull_request:
+    paths:
+      - 'manifests/**'
+      - 'src/lib/manifests/**'
+      - '.github/workflows/validate-manifests.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'manifests/**'
+      - 'src/lib/manifests/**'
+      - '.github/workflows/validate-manifests.yml'
+
+jobs:
+  validate-manifests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate manifest schemas
+        run: |
+          echo "Validating manifest schemas..."
+          npx tsx scripts/validate-manifests.ts
+
+      - name: Check for missing provenance
+        run: |
+          echo "Checking provenance coverage..."
+          npx tsx scripts/check-provenance.ts
+
+      - name: Run policy checks
+        run: |
+          echo "Running policy checks..."
+          npx tsx scripts/policy-checks.ts

.queue/reviews-queue.yaml

@@ -0,0 +1,33 @@
+# Review Priority Queue
+# Tracks upcoming reviews and comparisons to write
+
+high_priority:
+  - slug: "anthropic-vs-openai-llm-api-2025"
+    title: "Anthropic vs OpenAI: Which LLM API for Your Startup in 2025"
+    status: idea
+    tools: [anthropic-api, openai-api]
+    reviewType: comparison
+    reason: "High search volume, both tools have affiliate programs"
+    estimatedRevenue: "$500/month"
+    affiliateOpportunity: true
+    created: "2025-10-20"
+    notes: "Focus on cost differences, context windows, data retention policies"
+
+medium_priority:
+  - slug: "cursor-vs-github-copilot-2025"
+    title: "Cursor vs GitHub Copilot: AI Code Editors Compared"
+    status: idea
+    tools: [cursor, github-copilot]
+    reviewType: comparison
+    reason: "Popular dev tools, good SEO opportunity"
+    estimatedRevenue: "$300/month"
+    created: "2025-10-20"
+
+backlog:
+  - slug: "voice-dictation-tools-roundup"
+    title: "Best Voice Dictation Tools for Developers 2025"
+    status: idea
+    tools: [wisprflow, talon, dragon]
+    reviewType: roundup
+    reason: "Wispr Flow review performed well, expand coverage"
+    created: "2025-10-20"

README-manifests.md

@@ -0,0 +1,221 @@
+# Tool Manifest System
+
+This document describes the new manifest-based comparison system that replaces the database-driven approach with versioned YAML manifests containing verifiable facts and provenance tracking.
+
+## Overview
+
+The manifest system provides:
+- **Verifiable Facts**: All data comes from official vendor sources with citations
+- **Provenance Tracking**: Every fact includes source URL and verification date
+- **Type Safety**: Strict TypeScript schemas with JSON Schema validation
+- **No Synthetic Scores**: Only publish facts that are verifiable from vendor sources
+- **Hover Citations**: UI shows source information on hover for every displayed fact
+
+## Architecture
+
+### Base Types (`src/lib/manifests/types/base.ts`)
+
+```typescript
+interface ToolManifest<TFacts> {
+  schema_version: "1.0";
+  slug: string;
+  name: string;
+  category: "llm_api" | "vector_db" | "coding_assistant" | "ai_framework";
+  homepage_url: string;
+  docs_url?: string;
+  github_repo?: string;
+  as_of: IsoDate;
+  facts: TFacts;
+  provenance: ProvenanceItem[];
+}
+
+interface ProvenanceItem {
+  path: string;          // JSON Pointer
+  url: string;           // authoritative source
+  quote?: string;        // short exact excerpt
+  captured_at: IsoDate;  // when verified
+}
+```
+
+### LLM API Facts (`src/lib/manifests/types/llm_api.ts`)
+
+Focused on what developers actually compare:
+- Models and modalities
+- Context window sizes
+- Pricing per 1K tokens (normalized)
+- Rate limits
+- SDK support
+- Terms and restrictions
+
+### Manifest Loader (`src/lib/manifests/loader.ts`)
+
+- Validates against JSON schemas
+- Enforces provenance coverage
+- Configurable storage (filesystem, object store, etc.)
+- Type-safe loading with error handling
+
+## Usage
+
+### Creating Manifests
+
+Manifests are YAML files in the `manifests/` directory:
+
+```yaml
+schema_version: "1.0"
+slug: "openai-api"
+name: "OpenAI API"
+category: "llm_api"
+homepage_url: "https://openai.com/api"
+as_of: "2024-01-15T00:00:00Z"
+facts:
+  vendor: "openai"
+  auth:
+    scheme: "bearer"
+    header: "Authorization"
+    base_url: "https://api.openai.com/v1"
+  models:
+    - name: "gpt-4o"
+      modality: ["text", "image"]
+      context_tokens_max: 128000
+      pricing:
+        input_per_1k: 0.005
+        output_per_1k: 0.015
+      # ... more model details
+provenance:
+  - path: "/facts/vendor"
+    url: "https://openai.com/api"
+    quote: "OpenAI API"
+    captured_at: "2024-01-15T00:00:00Z"
+  # ... more provenance entries
+```
+
+### Loading Manifests
+
+```typescript
+import { loadLlmApiManifest, createManifestProvider } from '@/lib/manifests/loader';
+
+const provider = createManifestProvider();
+const manifest = await loadLlmApiManifest('openai-api', provider);
+```
+
+### Displaying Facts with Citations
+
+```tsx
+import { FactWithCitation } from '@/components/FactWithCitation';
+
+<FactWithCitation
+  value="$0.005 / 1K input"
+  jsonPointer="/facts/models/0/pricing/input_per_1k"
+  provenance={manifest.provenance}
+/>
+```
+
+## Validation
+
+### Schema Validation
+
+```bash
+npm run validate-manifests
+```
+
+Validates all manifests against JSON schemas and checks for:
+- Required fields
+- Correct data types
+- Valid URLs and dates
+- Category-specific fact schemas
+
+### Provenance Coverage
+
+```bash
+npm run check-provenance
+```
+
+Ensures every non-null fact has a corresponding provenance entry.
+
+### Policy Checks
+
+```bash
+npm run policy-checks
+```
+
+Runs quality checks for:
+- Unusual pricing values
+- Stale verification dates
+- Placeholder URLs
+- Vendor mismatches
+
+## Migration
+
+### From Database to Manifests
+
+```bash
+npm run migrate-to-manifests
+```
+
+Converts existing database tools to YAML manifests with:
+- Basic fact mapping
+- Placeholder provenance entries
+- Proper categorization
+
+**Note**: This creates starter manifests that need manual verification and fact-checking.
+
+## CI/CD
+
+The GitHub Actions workflow (`.github/workflows/validate-manifests.yml`) runs on:
+- Pull requests touching manifests
+- Pushes to main branch
+
+Validates:
+1. JSON Schema compliance
+2. Provenance coverage
+3. Policy compliance
+
+## Development Workflow
+
+1. **Create/Edit Manifest**: Write YAML with facts and provenance
+2. **Validate Locally**: Run validation scripts
+3. **Test in UI**: Use manifest-based comparison components
+4. **Submit PR**: CI validates automatically
+5. **Deploy**: Manifests are read directly (no cache)
+
+## File Structure
+
+```
+manifests/
+├── openai-api.yaml
+├── anthropic-api.yaml
+└── ...
+
+src/lib/manifests/
+├── types/
+│   ├── base.ts
+│   └── llm_api.ts
+└── loader.ts
+
+src/components/
+├── FactWithCitation.tsx
+└── ManifestBasedComparison.tsx
+
+scripts/
+├── validate-manifests.ts
+├── check-provenance.ts
+├── policy-checks.ts
+└── migrate-to-manifests.ts
+```
+
+## Key Principles
+
+1. **No Invented Data**: Only publish facts verifiable from vendor sources
+2. **Complete Provenance**: Every fact must have a source URL and verification date
+3. **Normalized Units**: All pricing in USD per 1K tokens, context in integer tokens
+4. **Type Safety**: Strict schemas prevent invalid data
+5. **Transparent Citations**: UI shows source information for every fact
+6. **No Synthetic Benchmarks**: Only vendor-published facts, no subjective scores
+
+## Future Extensions
+
+- Additional categories (vector databases, coding assistants)
+- Automated fact extraction from vendor pages
+- LLM-powered PR bot for manifest updates
+- Caching layer for production performance
+- Synthetic benchmarks (separate from facts)