seed-mcp scaffold: clone docs-mcp-template, customize for crop_seed PRODUCT_NAME

Sibling project to crop-chem-docs, same MCP-template lineage. Corpus is
seed/hybrid varieties across 6 vendors instead of pesticide labels.

What's customized vs. the template:
- CLAUDE.md: vendor matrix, build priority, Pioneer fallback policy,
  canonical sidecar schema (per-crop), Golden Harvest disease-scale
  reversal gotcha, no-IPv6 / HTTPS-clone note
- README.md: vendor coverage table, tool list, phase status
- Dockerfile: PRODUCT_NAME=crop_seed default, sources.json (not
  bundles.json), HYBRID_SEARCH=true, OLLAMA_URL + RERANK_URL Docker
  DNS defaults (same llama-rerank sidecar as crop-chem-docs)
- .gitea/workflows/refresh.yml: monthly cron (seed catalogs move
  slowly), 5 GREEN scraper steps, corpus-YYYY.MM.DD tag for Drawbar
  pinning, continue-on-error on GC step
- .gitea/workflows/image-only.yml: paths filter + cancel-in-progress
  concurrency group
- scripts/registry_gc.py: lifted from crop-chem-docs (correct Gitea
  packages API URL + UA header to bypass CF block on default
  Python-urllib UA)
- sources.json: catalog of 6 sources + scope_filter + per-source
  schema notes + Pioneer-exclusion rationale
- scrape/runner.py: dispatcher with --all = GREEN-only
- scrape/sources/{bayer_seeds,golden_harvest,nk,agripro,becks_pfr,
  becks_products}.py: stub modules with implementation notes
- docs_mcp/server.py: PRODUCT_NAME default → crop_seed,
  PRODUCT_DOCS_URL → repo URL

Pioneer is intentionally NOT a source. ToS bans automation; dealer
locator is login-gated. The MCP returns a curated fallback lesson
directing the user to pioneer.com.

Next phases:
- Phase 1: implement bayer_seeds (lift-and-shift from crop-chem-docs
  Bayer scraper; same __NEXT_DATA__ infra)
- Phase 7: curate eval/queries.jsonl
- Phase 11: lessons.md with Pioneer fallback + disease-scale notes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

eval/queries.jsonl.example

@@ -0,0 +1,4 @@
+{"query": "how to install <product> on Linux", "expected": [{"bundle_id": "Install.Linux.10.0", "page_id": "Installation.htm"}], "tags": ["install", "linux"]}
+{"query": "configure database connection for high availability", "expected": [{"bundle_id": "Admin.10.0", "page_id": "HA_Setup.htm"}], "tags": ["ha", "config"]}
+{"query": "API endpoint to list users", "expected": [{"bundle_id": "API.10.0", "page_id": "Users_API.htm"}], "tags": ["api"]}
+{"query": "what changed between 10.0 and 10.1", "expected": [{"bundle_id": "Release_Notes.10.1", "page_id": "Whats_New.htm"}], "tags": ["release-notes"]}

eval/retrievers.py

@@ -0,0 +1,62 @@
+"""Retriever protocol + concrete implementations.
+
+A single matrix dimension per knob (dense / reranked / bm25 / hybrid)
+so the eval harness can compare them apples-to-apples. Implement these
+once at Phase 7 and reuse them across every retrieval change.
+
+Each retriever returns a ranked list of (bundle_id, page_id) tuples
+deduplicated to the page level (chunks within the same page collapse
+to one entry; the highest-ranked chunk's position wins).
+"""
+from __future__ import annotations
+
+from typing import Protocol, Iterable
+
+
+class Retriever(Protocol):
+    name: str
+
+    def retrieve(self, query: str, k: int = 10) -> list[tuple[str, str]]:
+        """Return up to k (bundle_id, page_id) tuples in rank order."""
+        ...
+
+
+def _collapse_to_pages(chunk_ids: Iterable[tuple[str, str, str]], k: int) -> list[tuple[str, str]]:
+    """Take a stream of (bundle_id, page_id, chunk_ordinal) and return
+    the first k unique pages in their first-seen order."""
+    seen: set[tuple[str, str]] = set()
+    out: list[tuple[str, str]] = []
+    for bid, pid, _ord in chunk_ids:
+        key = (bid, pid)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(key)
+        if len(out) >= k:
+            break
+    return out
+
+
+# TODO Phase 2/3 — implement these once Chroma + the bm25 module are
+# in place. Each one is small (15-30 LOC). The eval harness imports
+# from this module by class name.
+#
+# class DenseRetriever:
+#     name = "dense"
+#     def __init__(self, collection): self.col = collection
+#     def retrieve(self, query, k=10): ...
+#
+# class RerankedRetriever:
+#     name = "dense+rerank"
+#     def __init__(self, collection, rerank_url, pool=200): ...
+#     def retrieve(self, query, k=10): ...
+#
+# class BM25Retriever:
+#     name = "bm25"
+#     def __init__(self, bm25_index): ...
+#     def retrieve(self, query, k=10): ...
+#
+# class HybridRetriever:
+#     name = "bm25+dense+rrf"
+#     def __init__(self, dense, bm25, k_rrf=60): ...
+#     def retrieve(self, query, k=10): ...

eval/run_eval.py

@@ -0,0 +1,91 @@
+"""Run all retrievers against eval/queries.jsonl, emit a markdown report.
+
+Metrics computed per retriever:
+
+  MRR        — mean reciprocal rank of the FIRST expected page in the
+               ranked result list (0 if not in top-k).
+  Recall@K   — fraction of expected pages that appear in top-K.
+  nDCG@K     — discounted gain weighted by rank position.
+
+The "right" number depends on what you're measuring. MRR tracks "the
+first-line answer is correct"; Recall@K tracks "everything relevant
+is there to draw from"; nDCG@K is a smoother combination of both.
+For docs-RAG, MRR is usually the headline metric.
+
+Usage:
+
+    python -m eval.run_eval \\
+        --queries eval/queries.jsonl \\
+        --k 5 \\
+        --output eval/results/baseline.md
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import time
+from pathlib import Path
+from typing import Iterable
+
+
+def load_queries(path: Path) -> list[dict]:
+    with open(path) as fh:
+        return [json.loads(line) for line in fh if line.strip()]
+
+
+def reciprocal_rank(retrieved: list[tuple[str, str]], expected: list[tuple[str, str]]) -> float:
+    expected_set = set(expected)
+    for i, page in enumerate(retrieved, start=1):
+        if page in expected_set:
+            return 1.0 / i
+    return 0.0
+
+
+def recall_at_k(retrieved: list[tuple[str, str]], expected: list[tuple[str, str]], k: int) -> float:
+    if not expected:
+        return 0.0
+    retrieved_set = set(retrieved[:k])
+    hits = sum(1 for e in expected if e in retrieved_set)
+    return hits / len(expected)
+
+
+def ndcg_at_k(retrieved: list[tuple[str, str]], expected: list[tuple[str, str]], k: int) -> float:
+    expected_set = set(expected)
+    dcg = 0.0
+    for i, page in enumerate(retrieved[:k], start=1):
+        if page in expected_set:
+            dcg += 1.0 / math.log2(i + 1)
+    # Ideal DCG: every expected page in the top positions.
+    idcg = sum(1.0 / math.log2(i + 1) for i in range(1, min(len(expected), k) + 1))
+    return dcg / idcg if idcg else 0.0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--queries", type=Path, default=Path("eval/queries.jsonl"))
+    p.add_argument("--k", type=int, default=5)
+    p.add_argument("--output", type=Path, default=Path("eval/results/baseline.md"))
+    args = p.parse_args()
+
+    if not args.queries.exists():
+        print(f"queries file not found: {args.queries}")
+        print("hint: copy eval/queries.jsonl.example and edit")
+        return 1
+
+    queries = load_queries(args.queries)
+    print(f"loaded {len(queries)} queries")
+
+    # TODO Phase 7: instantiate the retrievers you implemented in
+    # eval/retrievers.py and run each one against each query.
+    # Aggregate MRR / Recall@K / nDCG@K per retriever. Emit a
+    # markdown table to args.output. Commit the file alongside the
+    # PR that changes retrieval.
+    raise NotImplementedError(
+        "Wire up the retrievers in eval/retrievers.py first, then "
+        "fill in this evaluation loop. See PLAN.md Phase 7."
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())