football-docs 0.1.1 → 0.2.0

package/README.md

@@ -1,39 +1,87 @@
-# @nutmeg/docs
+# football-docs
 
 Searchable football data provider documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
 
-An MCP server that gives your AI agent instant access to documentation for Opta, StatsBomb, Wyscout, SportMonks, kloppy, and free sources (FBref, Understat, ClubElo). Search event types, qualifier IDs, coordinate systems, API endpoints, and cross-provider mappings.
+An MCP server that gives your AI agent instant access to documentation for Opta, StatsBomb, Wyscout, SportMonks, socceraction, kloppy, soccerdata, mplsoccer, databallpy, and free sources (FBref, Understat, ClubElo). Search event types, qualifier IDs, coordinate systems, API endpoints, and cross-provider mappings.
+
+MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
 
 ## Quick start
 
-### With Claude Code
+### Claude Code
+
+```bash
+claude mcp add football-docs -- npx -y football-docs
+```
 
-Add to your MCP config:
+### Cursor
+
+Settings → MCP → Add server. Use this config:
 
 ```json
 {
   "mcpServers": {
     "football-docs": {
       "command": "npx",
-      "args": ["-y", "@nutmeg/docs"]
+      "args": ["-y", "football-docs"]
     }
   }
 }
 ```
 
-### With any MCP client
+### VS Code / Copilot
 
-```bash
-npx @nutmeg/docs
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "football-docs": {
+      "command": "npx",
+      "args": ["-y", "football-docs"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "football-docs": {
+      "command": "npx",
+      "args": ["-y", "football-docs"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "football-docs": {
+      "command": "npx",
+      "args": ["-y", "football-docs"]
+    }
+  }
+}
 ```
 
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `search_docs` | Full-text search across all provider docs. Filter by provider. |
+| `search_docs` | Full-text search across all provider docs. Filter by provider. Results include provenance (source URL, version). |
 | `list_providers` | List all indexed providers and their doc coverage. |
 | `compare_providers` | Compare how different providers handle the same concept. |
+| `request_update` | Request a new provider, flag outdated docs, or suggest a better doc source. Queued for maintainer review. |
 
 ## Example queries
 
@@ -42,45 +90,61 @@ npx @nutmeg/docs
 - "Compare Opta and Wyscout coordinate systems"
 - "Does SportMonks have xG data?"
 - "What event types does kloppy map to GenericEvent?"
+- "How does SPADL represent a tackle?"
 
 ## Indexed providers
 
 | Provider | Chunks | Categories |
 |----------|--------|------------|
-| Opta | 29 | event-types, qualifiers, coordinate-system, api-access |
 | StatsBomb | 143 | event-types, data-model, coordinate-system, api-access, xg-model |
-| Wyscout | 61 | event-types, data-model, coordinate-system, api-access |
-| SportMonks | 71 | event-types, data-model, api-access |
 | kloppy | 100 | data-model, usage, provider-mapping |
-| Free sources | 28 | overview, fbref, understat |
+| SportMonks | 71 | event-types, data-model, api-access |
+| databallpy | 63 | data-model, overview, usage |
+| mplsoccer | 62 | overview, pitch-types, visualizations |
+| Wyscout | 61 | event-types, data-model, coordinate-system, api-access |
+| Free sources | 45 | overview, fbref, understat |
+| soccerdata | 40 | overview, data-sources, usage |
+| Opta | 29 | event-types, qualifiers, coordinate-system, api-access |
+| socceraction | 26 | SPADL format, VAEP, Expected Threat |
 
-**432 searchable chunks** across 6 providers.
+**640 searchable chunks** across 10 providers.
 
-## Contributing docs
+## Contributing
 
-Add or improve provider documentation by creating markdown files in `docs/{provider}/`:
+Contributions are welcome from everyone. There are three ways to help:
 
-```
-docs/
-  opta/
-    event-types.md
-    qualifiers.md
-    coordinate-system.md
-    api-access.md
-  statsbomb/
-    ...
-  your-new-provider/
-    events.md
-    api.md
-```
+1. **Open an issue** — [request a new provider](https://github.com/withqwerty/football-docs/issues/new/choose), [flag outdated docs](https://github.com/withqwerty/football-docs/issues/new/choose), or [suggest a better doc source](https://github.com/withqwerty/football-docs/issues/new/choose)
+2. **Use the `request_update` tool** — AI agents can flag outdated or missing docs directly via the MCP server, which queues requests for maintainer review
+3. **Open a PR** — fix errors, add new providers, or improve existing docs
+
+**You don't need to be an expert.** See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
+
+### What we especially need
+
+| Provider | Priority | Source material to start from |
+|----------|----------|-------------------------------|
+| FPL (Fantasy Premier League) | High | [FPL APIs Explained](https://www.oliverlooney.com/blogs/FPL-APIs-Explained) |
+| API-Football (RapidAPI) | High | [API-Football docs](https://www.api-football.com/documentation-v3) |
+| Football-data.org | Medium | [Football-data.org docs](https://www.football-data.org/documentation/api) |
+| TheSportsDB | Medium | [TheSportsDB API](https://www.thesportsdb.com/api.php) |
+| WhoScored | Medium | Based on Opta F24, community-documented |
+| Sofascore | Medium | Unofficial API, community-documented |
+
+## For maintainers
+
+### Crawl pipeline
 
-Then rebuild the index:
+Provider doc sources are tracked in `providers.json`. The crawl pipeline discovers the best doc source (llms.txt > ReadTheDocs > GitHub README) and writes markdown with provenance frontmatter.
 
 ```bash
-npm run ingest
+npm run discover                        # probe sources without crawling
+npm run crawl                           # crawl all providers with sources
+npm run crawl -- --provider kloppy      # crawl one provider
+npm run ingest                          # rebuild search index from docs/
+npm run ingest -- --provider kloppy     # re-ingest one provider (incremental)
 ```
 
-Each markdown file is chunked by heading (## or ###) and indexed with FTS5. PRs welcome.
+Each crawled doc carries provenance metadata (source URL, source type, upstream version, crawl timestamp) that is surfaced in search results, so agents can distinguish between curated content and upstream documentation.
 
 ## License
 

package/dist/crawl.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Crawl upstream documentation for football data providers.
+ *
+ * Fetches documentation from the best available source (llms.txt, ReadTheDocs,
+ * GitHub, OpenAPI specs) and writes markdown files with provenance frontmatter.
+ *
+ * IMPORTANT: This crawler stores upstream content faithfully. It does NOT
+ * paraphrase, summarise, or interpret. The content in the output files should
+ * be directly traceable to the source URL.
+ *
+ * Usage:
+ *   npm run crawl                         # crawl all providers with sources
+ *   npm run crawl -- --provider kloppy    # crawl one provider
+ *   npm run crawl -- --discover           # probe sources without crawling
+ */
+interface CrawledDoc {
+    category: string;
+    content: string;
+    source_url: string;
+    source_type: string;
+}
+/**
+ * Extract main content from an HTML page and convert to markdown.
+ * Uses Mozilla's Readability (same algorithm as Firefox Reader View)
+ * to isolate the main content, then Turndown to convert to markdown.
+ */
+export declare function htmlToMarkdown(html: string, url: string): string | null;
+/**
+ * Crawl an llms.txt or llms-full.txt file.
+ * Already structured for LLM consumption — chunk by top-level heading.
+ */
+export declare function crawlLlmsTxt(content: string, sourceUrl: string): CrawledDoc[];
+export declare function slugify(text: string): string;
+export {};

package/dist/crawl.js

@@ -0,0 +1,419 @@
+/**
+ * Crawl upstream documentation for football data providers.
+ *
+ * Fetches documentation from the best available source (llms.txt, ReadTheDocs,
+ * GitHub, OpenAPI specs) and writes markdown files with provenance frontmatter.
+ *
+ * IMPORTANT: This crawler stores upstream content faithfully. It does NOT
+ * paraphrase, summarise, or interpret. The content in the output files should
+ * be directly traceable to the source URL.
+ *
+ * Usage:
+ *   npm run crawl                         # crawl all providers with sources
+ *   npm run crawl -- --provider kloppy    # crawl one provider
+ *   npm run crawl -- --discover           # probe sources without crawling
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { Readability } from "@mozilla/readability";
+import { parseHTML } from "linkedom";
+import TurndownService from "turndown";
+import { discoverBestSource } from "./discover.js";
+import { fetchText } from "./http.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = resolve(__dirname, "..", "docs");
+const PROVIDERS_PATH = resolve(__dirname, "..", "providers.json");
+const turndown = new TurndownService({
+    headingStyle: "atx",
+    codeBlockStyle: "fenced",
+    bulletListMarker: "-",
+});
+// ── HTML → Markdown ──────────────────────────────────────────────────
+/**
+ * Extract main content from an HTML page and convert to markdown.
+ * Uses Mozilla's Readability (same algorithm as Firefox Reader View)
+ * to isolate the main content, then Turndown to convert to markdown.
+ */
+export function htmlToMarkdown(html, url) {
+    // linkedom's parseHTML doesn't support a url option, so we inject a <base> tag
+    // for Readability to resolve relative links against the source URL
+    const htmlWithBase = html.includes("<base ")
+        ? html
+        : html.replace(/(<head[^>]*>)/i, `$1<base href="${url}">`);
+    const { document } = parseHTML(htmlWithBase);
+    const reader = new Readability(document, { charThreshold: 100 });
+    const article = reader.parse();
+    if (!article?.content)
+        return null;
+    return turndown.turndown(article.content);
+}
+// ── Crawl strategies ─────────────────────────────────────────────────
+/**
+ * Crawl an llms.txt or llms-full.txt file.
+ * Already structured for LLM consumption — chunk by top-level heading.
+ */
+export function crawlLlmsTxt(content, sourceUrl) {
+    const sections = [];
+    const lines = content.split("\n");
+    let currentTitle = "overview";
+    let currentLines = [];
+    for (const line of lines) {
+        const headingMatch = line.match(/^(#{1,2})\s+(.+)/);
+        if (headingMatch && currentLines.length > 0) {
+            const body = currentLines.join("\n").trim();
+            if (body.length > 50) {
+                sections.push({
+                    category: slugify(currentTitle),
+                    content: body,
+                    source_url: sourceUrl,
+                    source_type: "llms_txt",
+                });
+            }
+            currentTitle = headingMatch[2].trim();
+            currentLines = [line];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    const body = currentLines.join("\n").trim();
+    if (body.length > 50) {
+        sections.push({
+            category: slugify(currentTitle),
+            content: body,
+            source_url: sourceUrl,
+            source_type: "llms_txt",
+        });
+    }
+    if (sections.length <= 1) {
+        return [{
+                category: "reference",
+                content,
+                source_url: sourceUrl,
+                source_type: "llms_txt",
+            }];
+    }
+    return sections;
+}
+/**
+ * Crawl a documentation website by fetching linked pages from the index.
+ * Works with Sphinx/RTD, MkDocs, GitBook HTML, Docusaurus, and most
+ * static doc sites — Readability handles content extraction regardless
+ * of the specific platform.
+ */
+async function crawlDocsSite(baseUrl) {
+    const docs = [];
+    const root = baseUrl.replace(/\/$/, "");
+    const rootHost = new URL(root).hostname;
+    const usedCategories = new Set();
+    const indexHtml = await fetchText(root);
+    if (!indexHtml)
+        return docs;
+    // Extract the root/index page itself
+    const indexContent = htmlToMarkdown(indexHtml, root);
+    if (indexContent && indexContent.length >= 100) {
+        usedCategories.add("index");
+        docs.push({
+            category: "index",
+            content: indexContent,
+            source_url: root,
+            source_type: "crawled",
+        });
+    }
+    // Extract links from the index page
+    const linkPattern = /href="([^"]*\.html?)"/g;
+    const links = new Set();
+    for (const match of indexHtml.matchAll(linkPattern)) {
+        const href = match[1];
+        if (href.startsWith("#") ||
+            href.includes("genindex") ||
+            href.includes("search.html") ||
+            href.includes("_static") ||
+            href.includes("_sources"))
+            continue;
+        let fullUrl;
+        try {
+            fullUrl = new URL(href, `${root}/`).href;
+        }
+        catch {
+            continue;
+        }
+        if (new URL(fullUrl).hostname !== rootHost)
+            continue;
+        links.add(fullUrl);
+    }
+    // Cap at 50 pages to avoid hammering upstream
+    const pageUrls = [...links].slice(0, 50);
+    for (const pageUrl of pageUrls) {
+        const html = await fetchText(pageUrl);
+        if (!html)
+            continue;
+        const content = htmlToMarkdown(html, pageUrl);
+        if (!content || content.length < 100)
+            continue;
+        // Use last 2 path segments to avoid duplicate category names
+        const pathSegments = new URL(pageUrl).pathname
+            .replace(/\.(html?|htm)$/, "")
+            .split("/")
+            .filter(Boolean);
+        let category = slugify(pathSegments.slice(-2).join("-") || "page");
+        // Deduplicate: append a suffix if the category is already used
+        if (usedCategories.has(category)) {
+            let suffix = 2;
+            while (usedCategories.has(`${category}-${suffix}`))
+                suffix++;
+            category = `${category}-${suffix}`;
+        }
+        usedCategories.add(category);
+        docs.push({
+            category,
+            content,
+            source_url: pageUrl,
+            source_type: "crawled",
+        });
+    }
+    return docs;
+}
+/**
+ * Crawl a GitHub repository's README.
+ */
+async function crawlGitHubReadme(repoUrl) {
+    const docs = [];
+    const repoMatch = repoUrl.match(/github\.com\/([^/]+)\/([^/]+)/);
+    if (!repoMatch)
+        return docs;
+    const [, owner, repo] = repoMatch;
+    for (const branch of ["main", "master", "develop"]) {
+        const readmeUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/README.md`;
+        const content = await fetchText(readmeUrl);
+        if (content) {
+            docs.push({
+                category: "readme",
+                content,
+                source_url: readmeUrl,
+                source_type: "crawled",
+            });
+            break;
+        }
+    }
+    return docs;
+}
+/**
+ * Crawl an OpenAPI/Swagger spec and convert endpoints to searchable markdown.
+ * Handles both YAML and JSON specs, with $ref resolution.
+ */
+async function crawlOpenApiSpec(specUrl) {
+    const docs = [];
+    // Fetch the spec ourselves first, then dereference the parsed object
+    // with external $ref resolution disabled to prevent SSRF via malicious specs
+    const specContent = await fetchText(specUrl);
+    if (!specContent)
+        return docs;
+    let api;
+    try {
+        const parsed = JSON.parse(specContent);
+        api = await SwaggerParser.dereference(parsed, {
+            resolve: { external: false },
+        });
+    }
+    catch {
+        // If JSON parse fails, try as YAML via URL (for YAML specs)
+        try {
+            api = await SwaggerParser.dereference(specUrl, {
+                resolve: { external: false },
+            });
+        }
+        catch (err) {
+            console.error(`  Failed to parse OpenAPI spec: ${err}`);
+            return docs;
+        }
+    }
+    const info = api.info;
+    const paths = api.paths;
+    // Overview doc
+    const overviewLines = [
+        `# ${info?.title ?? "API"}`,
+        "",
+    ];
+    if (info?.description)
+        overviewLines.push(info.description, "");
+    if (info?.version)
+        overviewLines.push(`**Version:** ${info.version}`, "");
+    // Collect servers/base URLs if present
+    const servers = api.servers;
+    if (servers?.length) {
+        overviewLines.push("## Base URLs", "");
+        for (const s of servers) {
+            overviewLines.push(`- \`${s.url}\`${s.description ? ` — ${s.description}` : ""}`);
+        }
+        overviewLines.push("");
+    }
+    docs.push({
+        category: "api-overview",
+        content: overviewLines.join("\n").trim(),
+        source_url: specUrl,
+        source_type: "openapi",
+    });
+    if (!paths)
+        return docs;
+    // Group endpoints by tag (or by first path segment if untagged)
+    const byGroup = new Map();
+    for (const [path, methods] of Object.entries(paths)) {
+        if (!methods || typeof methods !== "object")
+            continue;
+        for (const [method, details] of Object.entries(methods)) {
+            if (method.startsWith("x-") || typeof details !== "object" || !details)
+                continue;
+            const op = details;
+            const tags = op.tags ?? [path.split("/").filter(Boolean)[0] ?? "general"];
+            const group = tags[0] ?? "general";
+            const lines = [];
+            lines.push(`### ${method.toUpperCase()} ${path}`);
+            if (op.summary)
+                lines.push("", String(op.summary));
+            if (op.description)
+                lines.push("", String(op.description));
+            // Parameters
+            const params = op.parameters;
+            if (params?.length) {
+                lines.push("", "**Parameters:**", "");
+                lines.push("| Name | In | Type | Required | Description |");
+                lines.push("|---|---|---|---|---|");
+                for (const p of params) {
+                    const schema = p.schema;
+                    lines.push(`| ${p.name} | ${p.in} | ${schema?.type ?? "—"} | ${p.required ? "yes" : "no"} | ${p.description ?? "—"} |`);
+                }
+            }
+            // Response codes
+            const responses = op.responses;
+            if (responses) {
+                lines.push("", "**Responses:**", "");
+                for (const [code, resp] of Object.entries(responses)) {
+                    lines.push(`- **${code}**: ${resp.description ?? "—"}`);
+                }
+            }
+            lines.push("");
+            const groupLines = byGroup.get(group) ?? [];
+            groupLines.push(lines.join("\n"));
+            byGroup.set(group, groupLines);
+        }
+    }
+    // Write one doc per tag/group
+    for (const [group, endpoints] of byGroup) {
+        docs.push({
+            category: slugify(group),
+            content: `## ${group}\n\n${endpoints.join("\n---\n\n")}`,
+            source_url: specUrl,
+            source_type: "openapi",
+        });
+    }
+    return docs;
+}
+// ── Utilities ────────────────────────────────────────────────────────
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 50);
+}
+/** Write a crawled doc to disk with provenance frontmatter. */
+function writeCrawledDoc(provider, doc, upstreamVersion) {
+    const dir = resolve(DOCS_DIR, provider);
+    mkdirSync(dir, { recursive: true });
+    const frontmatter = [
+        "---",
+        `source_url: ${doc.source_url}`,
+        `source_type: ${doc.source_type}`,
+        upstreamVersion ? `upstream_version: ${upstreamVersion}` : `upstream_version:`,
+        `crawled_at: ${new Date().toISOString()}`,
+        "---",
+        "",
+    ].join("\n");
+    const filePath = resolve(dir, `${doc.category}.md`);
+    const rel = relative(dir, filePath);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path traversal detected: ${doc.category}`);
+    }
+    writeFileSync(filePath, frontmatter + doc.content, "utf-8");
+}
+// ── Main ─────────────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    const providerArg = args.indexOf("--provider");
+    const singleProvider = providerArg >= 0 ? args[providerArg + 1] : undefined;
+    const discoverOnly = args.includes("--discover");
+    if (!existsSync(PROVIDERS_PATH)) {
+        console.error("providers.json not found. Create it first.");
+        process.exit(1);
+    }
+    const providersFile = JSON.parse(readFileSync(PROVIDERS_PATH, "utf-8"));
+    const providers = providersFile.providers;
+    const targets = singleProvider
+        ? { [singleProvider]: providers[singleProvider] }
+        : providers;
+    if (singleProvider && !providers[singleProvider]) {
+        console.error(`Provider "${singleProvider}" not found in providers.json`);
+        process.exit(1);
+    }
+    for (const [name, config] of Object.entries(targets)) {
+        if (!config)
+            continue;
+        const sources = config.sources
+            .filter((s) => !!s.url)
+            .map((s) => ({
+            url: s.url,
+            type: s.type,
+            note: s.note,
+        }));
+        if (sources.length === 0) {
+            console.log(`${name}: curated-only (no URLs to crawl)`);
+            continue;
+        }
+        console.log(`\n${name}: discovering sources...`);
+        const discovery = await discoverBestSource(name, sources);
+        for (const check of discovery.checked) {
+            const status = check.found ?? check.error ?? "not found";
+            console.log(`  ${check.url} → ${status}`);
+        }
+        if (!discovery.source) {
+            console.log(`  → no crawlable source found (chooseBestSource returned null)`);
+            continue;
+        }
+        console.log(`  → best source: ${discovery.source.type} (${discovery.source.url})`);
+        if (discoverOnly)
+            continue;
+        // Crawl based on source type
+        let docs = [];
+        if (discovery.source.type === "llms_txt") {
+            const content = await fetchText(discovery.source.url);
+            if (content) {
+                docs = crawlLlmsTxt(content, discovery.source.url);
+            }
+        }
+        else if (discovery.source.type === "readthedocs" || discovery.source.type === "api_docs") {
+            docs = await crawlDocsSite(discovery.source.url);
+        }
+        else if (discovery.source.type === "github_docs") {
+            docs = await crawlGitHubReadme(discovery.source.url);
+        }
+        else if (discovery.source.type === "openapi") {
+            docs = await crawlOpenApiSpec(discovery.source.url);
+        }
+        if (docs.length === 0) {
+            console.log(`  → no content extracted`);
+            continue;
+        }
+        for (const doc of docs) {
+            writeCrawledDoc(name, doc, config.version);
+            console.log(`  wrote ${name}/${doc.category}.md (${doc.content.length} chars) [${doc.source_type}]`);
+        }
+        console.log(`  → ${docs.length} doc(s) written`);
+    }
+}
+main().catch((err) => {
+    console.error("Crawl failed:", err);
+    process.exit(1);
+});

package/dist/discover.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Source discovery for football data providers.
+ *
+ * Given a provider's known URLs, discovers the best documentation source
+ * to crawl. Checks for llms.txt, ReadTheDocs structure, GitHub docs, etc.
+ *
+ * Usage:
+ *   import { discoverBestSource } from "./discover.js";
+ *   const result = await discoverBestSource(provider);
+ */
+export interface ProviderSource {
+    url: string;
+    type: "llms_txt" | "readthedocs" | "github_docs" | "api_docs" | "openapi" | "curated";
+    note?: string;
+}
+export interface DiscoveryResult {
+    provider: string;
+    /** The best source found, or null if only curated content is available */
+    source: ProviderSource | null;
+    /** All sources that were checked and what was found */
+    checked: Array<{
+        url: string;
+        found: string | null;
+        error?: string;
+    }>;
+}
+export interface ProbeResult {
+    url: string;
+    sourceType: ProviderSource["type"];
+    llmsTxt: {
+        url: string;
+        content: string;
+    } | null;
+    isReadTheDocs: boolean;
+    isReachable: boolean;
+}
+/**
+ * Choose the best source to crawl from probe results.
+ *
+ * Scoring: llms-full.txt (>1000 chars) = 100, llms.txt (>1000 chars) = 90,
+ * ReadTheDocs/Sphinx = 70, short llms.txt = 50, reachable = 40, unreachable = 0.
+ *
+ * @param probeResults - What was actually found at each URL
+ * @returns The best source to crawl, or null if only curated content is available
+ */
+export declare function chooseBestSource(probeResults: ProbeResult[]): ProviderSource | null;
+/**
+ * Discover the best documentation source for a provider.
+ *
+ * Probes all configured URLs for llms.txt, ReadTheDocs markers, and
+ * basic reachability, then uses chooseBestSource() to pick the winner.
+ */
+export declare function discoverBestSource(provider: string, sources: ProviderSource[]): Promise<DiscoveryResult>;