@mcptoolshop/claude-synergy 0.0.0 → 1.0.0

package/dist/cli.js

@@ -0,0 +1,2090 @@
+#!/usr/bin/env node
+import {
+  OllamaEmbeddingProvider,
+  VoyageEmbeddingProvider,
+  entityFrequency,
+  hybridSearch,
+  initSchema,
+  listProducts,
+  lookupEntity,
+  openDb,
+  recentReleases,
+  searchChanges
+} from "./chunk-YFGUTT22.js";
+import {
+  ingestAll,
+  loadProductsConfig
+} from "./chunk-HCIZPSW4.js";
+
+// src/cli.ts
+import { Command, Option } from "commander";
+import { join as join4, resolve as resolve2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { createRequire } from "module";
+
+// src/embed.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+// src/providers/context/none.ts
+var NoneContextProvider = class {
+  name = "none";
+  async contextFor(_chunk, _release) {
+    return "";
+  }
+};
+
+// src/providers/context/structured.ts
+var StructuredContextProvider = class {
+  name = "structured";
+  async contextFor(chunk, release) {
+    const date = release.releasedAt ?? "unknown date";
+    const positional = `change ${chunk.ordinalInRelease} of ${chunk.totalInRelease}`;
+    return `In ${release.product} ${release.version} (${date}), ${chunk.kind} (${positional}):`;
+  }
+};
+
+// src/providers/context/ollama.ts
+function providerTimeoutMs() {
+  const raw = process.env.CLAUDE_SYNERGY_PROVIDER_TIMEOUT_MS;
+  const n = raw === void 0 ? NaN : parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 6e4;
+}
+async function safeErrorBody(res, max = 200) {
+  try {
+    const body = await res.text();
+    const safe = body.split("\n").filter((l) => !/x-api-key|authorization|bearer|api[-_]?key/i.test(l)).join("\n");
+    return safe.slice(0, max);
+  } catch {
+    return "<unreadable>";
+  }
+}
+var OllamaContextProvider = class {
+  name = "ollama";
+  host;
+  model;
+  constructor(opts = {}) {
+    const rawHost = opts.host ?? process.env.OLLAMA_HOST ?? "http://localhost:11434";
+    this.host = /^https?:\/\//.test(rawHost) ? rawHost : `http://${rawHost}`;
+    this.model = opts.model ?? process.env.OLLAMA_GEN_MODEL ?? "llama3.2:3b";
+  }
+  async contextFor(chunk, release) {
+    const releaseSnippet = release.siblings.map((s, i) => `${i + 1}. ${s.text}`).slice(0, 30).join("\n");
+    const prompt = [
+      `<document>`,
+      `${release.product} ${release.version} release notes (${release.releasedAt ?? "unknown date"}):`,
+      releaseSnippet,
+      `</document>`,
+      ``,
+      `Here is the chunk we want to situate within the whole document:`,
+      `<chunk>`,
+      chunk.text,
+      `</chunk>`,
+      ``,
+      `Please give a short succinct context (1 sentence, max 30 words) to situate this chunk within the overall document for improving search retrieval of the chunk. Mention any related product names, env vars, command names, or APIs. Answer only with the succinct context and nothing else.`
+    ].join("\n");
+    const timeoutMs = providerTimeoutMs();
+    let res;
+    try {
+      res = await fetch(`${this.host}/api/generate`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: this.model,
+          prompt,
+          stream: false,
+          options: { temperature: 0, num_predict: 80 }
+        }),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (e) {
+      if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+        throw new Error(`Ollama context request timed out after ${timeoutMs}ms \u2014 is the Ollama server responsive?`);
+      }
+      throw e;
+    }
+    if (!res.ok) throw new Error(`Ollama ${res.status}: ${await safeErrorBody(res)}`);
+    const json = await res.json();
+    return json.response.trim();
+  }
+};
+
+// src/providers/context/claude-haiku.ts
+function providerTimeoutMs2() {
+  const raw = process.env.CLAUDE_SYNERGY_PROVIDER_TIMEOUT_MS;
+  const n = raw === void 0 ? NaN : parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 6e4;
+}
+async function safeErrorBody2(res, max = 200) {
+  try {
+    const body = await res.text();
+    const safe = body.split("\n").filter((l) => !/x-api-key|authorization|bearer|api[-_]?key/i.test(l)).join("\n");
+    return safe.slice(0, max);
+  } catch {
+    return "<unreadable>";
+  }
+}
+var ClaudeHaikuContextProvider = class {
+  name = "claude-haiku";
+  apiKey;
+  model;
+  cachedDocByRelease = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
+    this.model = opts.model ?? "claude-haiku-4-5-20251001";
+    if (!this.apiKey) {
+      throw new Error("claude-haiku context provider requires ANTHROPIC_API_KEY");
+    }
+  }
+  async contextFor(chunk, release) {
+    const releaseKey = `${release.product}@${release.version}`;
+    let doc = this.cachedDocByRelease.get(releaseKey);
+    if (!doc) {
+      doc = release.siblings.map((s, i) => `${i + 1}. ${s.text}`).join("\n");
+      this.cachedDocByRelease.set(releaseKey, doc);
+    }
+    const userPrompt = [
+      `Chunk: ${chunk.text}`,
+      ``,
+      `Give a 1-sentence context (max 30 words) situating this chunk in the release. Mention related products, env vars, commands. Output ONLY the context.`
+    ].join("\n");
+    const timeoutMs = providerTimeoutMs2();
+    let res;
+    try {
+      res = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: 80,
+          system: [
+            {
+              type: "text",
+              text: `${release.product} ${release.version} (${release.releasedAt}) release notes:
+${doc}`,
+              cache_control: { type: "ephemeral" }
+            }
+          ],
+          messages: [{ role: "user", content: userPrompt }]
+        }),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (e) {
+      if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+        throw new Error(`Anthropic API request timed out after ${timeoutMs}ms \u2014 is the API responsive?`);
+      }
+      throw e;
+    }
+    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${await safeErrorBody2(res)}`);
+    const json = await res.json();
+    return (json.content.find((c) => c.type === "text")?.text ?? "").trim();
+  }
+};
+
+// src/embed.ts
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+function initVecSchema(db) {
+  const existing = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'`).get();
+  if (existing) return;
+  const schemaPath = resolveSchemaVecPath();
+  const sql = readFileSync(schemaPath, "utf-8");
+  db.exec(sql);
+}
+function resolveSchemaVecPath() {
+  const candidates = [
+    join(__dirname2, "..", "schema-vec.sql"),
+    join(process.cwd(), "schema-vec.sql")
+  ];
+  for (const p of candidates) {
+    try {
+      readFileSync(p);
+      return p;
+    } catch {
+    }
+  }
+  throw new Error(`schema-vec.sql not found in: ${candidates.join(", ")}`);
+}
+async function embedAll(db, opts) {
+  initVecSchema(db);
+  const ctx = makeContextProvider(opts.contextProviderName);
+  const emb = makeEmbeddingProvider(opts.embeddingProviderName);
+  const productFilter = opts.product ? "AND c.product = @product" : "";
+  const forceFilter = opts.force ? "" : "AND ch.id IS NULL";
+  const limitClause = opts.limit ? "LIMIT @limit" : "";
+  const pendingSql = `
+    SELECT c.id AS change_id, c.product, c.version, r.released_at, c.kind, c.text, c.ordinal
+    FROM changes c
+    JOIN releases r ON c.product = r.product AND c.version = r.version
+    LEFT JOIN chunks ch ON ch.change_id = c.id
+    WHERE 1=1
+      ${productFilter}
+      ${forceFilter}
+    ORDER BY c.product, c.version, c.ordinal
+    ${limitClause}
+  `;
+  const params = {};
+  if (opts.product) params.product = opts.product;
+  if (opts.limit) params.limit = opts.limit;
+  const pending = db.prepare(pendingSql).all(params);
+  if (pending.length === 0) {
+    return {
+      contextProvider: ctx.name,
+      embeddingProvider: emb.name,
+      chunksCreated: 0,
+      chunksSkipped: 0,
+      contextMs: 0,
+      embedMs: 0,
+      totalMs: 0
+    };
+  }
+  const byRelease = /* @__PURE__ */ new Map();
+  for (const row of pending) {
+    const key = `${row.product}@${row.version}`;
+    if (!byRelease.has(key)) byRelease.set(key, []);
+    byRelease.get(key).push({
+      changeId: row.change_id,
+      product: row.product,
+      releaseVersion: row.version,
+      releasedAt: row.released_at,
+      kind: row.kind,
+      text: row.text,
+      ordinalInRelease: row.ordinal,
+      totalInRelease: 0
+      // backfilled below
+    });
+  }
+  for (const [, list] of byRelease) {
+    for (const c of list) c.totalInRelease = list.length;
+  }
+  const startTotal = Date.now();
+  let contextMs = 0;
+  let embedMs = 0;
+  const contextsByChange = /* @__PURE__ */ new Map();
+  const allChunks = [];
+  for (const [, siblings] of byRelease) {
+    const release = {
+      product: siblings[0].product,
+      version: siblings[0].releaseVersion,
+      releasedAt: siblings[0].releasedAt,
+      siblings
+    };
+    for (const chunk of siblings) {
+      if (opts.signal?.aborted) break;
+      const t0 = Date.now();
+      const ctxPrefix = await ctx.contextFor(chunk, release);
+      contextMs += Date.now() - t0;
+      contextsByChange.set(chunk.changeId, ctxPrefix);
+      allChunks.push(chunk);
+    }
+    if (opts.signal?.aborted) break;
+  }
+  const batchSize = opts.batchSize ?? 64;
+  const insertChunk = db.prepare(`
+    INSERT OR REPLACE INTO chunks
+      (change_id, product, release_version, released_at, context_prefix, original_text, contextualized, context_provider, embedding_model, embedded_at)
+    VALUES
+      (@change_id, @product, @release_version, @released_at, @context_prefix, @original_text, @contextualized, @context_provider, @embedding_model, @embedded_at)
+  `);
+  const deleteVec = db.prepare(`DELETE FROM chunks_vec WHERE rowid = ?`);
+  const insertVec = db.prepare(`INSERT INTO chunks_vec(rowid, embedding) VALUES (?, ?)`);
+  let created = 0;
+  let stoppedEarly = false;
+  let stopReason;
+  const usage = { requests: 0, tokens: 0 };
+  const totalBatches = Math.ceil(allChunks.length / batchSize);
+  for (let i = 0; i < allChunks.length; i += batchSize) {
+    if (opts.signal?.aborted) {
+      stoppedEarly = true;
+      stopReason = "cancelled";
+      break;
+    }
+    if (opts.maxRequests !== void 0 && usage.requests >= opts.maxRequests) {
+      stoppedEarly = true;
+      stopReason = "budget_requests";
+      break;
+    }
+    if (opts.maxTokens !== void 0 && usage.tokens >= opts.maxTokens) {
+      stoppedEarly = true;
+      stopReason = "budget_tokens";
+      break;
+    }
+    const batch = allChunks.slice(i, i + batchSize);
+    const texts = batch.map((c) => {
+      const prefix = contextsByChange.get(c.changeId) ?? "";
+      return prefix ? `${prefix}
+
+${c.text}` : c.text;
+    });
+    const t0 = Date.now();
+    const vectors = await emb.embed(texts);
+    embedMs += Date.now() - t0;
+    usage.requests++;
+    if ("usage" in emb) {
+      const provUsage = emb.usage;
+      if (provUsage && typeof provUsage.tokens === "number") {
+        usage.tokens = provUsage.tokens;
+      }
+    }
+    const tx = db.transaction(() => {
+      for (let j = 0; j < batch.length; j++) {
+        const c = batch[j];
+        const prefix = contextsByChange.get(c.changeId) ?? "";
+        const contextualized = prefix ? `${prefix}
+
+${c.text}` : c.text;
+        const result = insertChunk.run({
+          change_id: c.changeId,
+          product: c.product,
+          release_version: c.releaseVersion,
+          released_at: c.releasedAt,
+          context_prefix: prefix,
+          original_text: c.text,
+          contextualized,
+          context_provider: ctx.name,
+          embedding_model: `${emb.name}:${emb.model}`,
+          embedded_at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        const chunkId = Number(result.lastInsertRowid);
+        deleteVec.run(chunkId);
+        insertVec.run(BigInt(chunkId), vectors[j]);
+        created++;
+      }
+    });
+    tx();
+    if (opts.onProgress) {
+      opts.onProgress({
+        batchesCompleted: Math.floor(i / batchSize) + 1,
+        batchesTotal: totalBatches,
+        chunksCompleted: created,
+        chunksTotal: allChunks.length,
+        provider: `${emb.name}:${emb.model}`,
+        tokensUsed: usage.tokens,
+        requestsMade: usage.requests
+      });
+    }
+  }
+  const stats = {
+    contextProvider: ctx.name,
+    embeddingProvider: `${emb.name}:${emb.model}`,
+    chunksCreated: created,
+    chunksSkipped: 0,
+    contextMs,
+    embedMs,
+    totalMs: Date.now() - startTotal
+  };
+  if (usage.requests > 0) {
+    stats.usage = usage;
+  }
+  if (stoppedEarly) {
+    stats.stoppedEarly = true;
+    stats.stopReason = stopReason;
+  }
+  return stats;
+}
+function makeContextProvider(name) {
+  switch (name) {
+    case "none":
+      return new NoneContextProvider();
+    case "structured":
+      return new StructuredContextProvider();
+    case "ollama":
+      return new OllamaContextProvider();
+    case "claude-haiku":
+      return new ClaudeHaikuContextProvider();
+    default:
+      throw new Error(`unknown context provider: ${name}`);
+  }
+}
+function makeEmbeddingProvider(name) {
+  switch (name) {
+    case "ollama":
+      return new OllamaEmbeddingProvider();
+    case "voyage":
+      return new VoyageEmbeddingProvider();
+    default:
+      throw new Error(`unknown embedding provider: ${name}`);
+  }
+}
+
+// src/fetch.ts
+import { execFileSync } from "child_process";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync } from "fs";
+import { join as join3, resolve } from "path";
+
+// src/fetch-rss.ts
+import { XMLParser } from "fast-xml-parser";
+
+// src/fetch-utils.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var GITHUB_TOKEN_HINT = "GitHub API rate limit hit. Set GITHUB_TOKEN env var for 5000 req/hr (vs 60 unauthenticated).";
+async function fetchWithRetry(url, opts = {}) {
+  const {
+    timeoutMs = 3e4,
+    maxRetries = 3,
+    baseDelayMs = 1e3,
+    signal: externalSignal,
+    ...fetchInit
+  } = opts;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (externalSignal?.aborted) {
+      throw new Error(`fetch aborted: ${externalSignal.reason?.message ?? "signal aborted"}`);
+    }
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const combinedSignal = externalSignal ? AbortSignal.any([timeoutSignal, externalSignal]) : timeoutSignal;
+    try {
+      const res = await fetch(url, {
+        ...fetchInit,
+        signal: combinedSignal
+      });
+      if (res.ok) return res;
+      if (!RETRYABLE_STATUSES.has(res.status)) {
+        if (res.status === 403 && isGitHubApiUrl(url)) {
+          throw new Error(`HTTP 403 from ${url} \u2014 ${GITHUB_TOKEN_HINT}`);
+        }
+        return res;
+      }
+      if (attempt < maxRetries) {
+        const delay = computeDelay(res, attempt, baseDelayMs);
+        console.error(
+          `[retry] ${fetchInit.method ?? "GET"} ${String(url)} (attempt ${attempt + 2}/${maxRetries + 1}, status ${res.status}, backoff ${delay}ms)`
+        );
+        await sleep(delay, externalSignal);
+        continue;
+      }
+      const ghHint = res.status === 429 && isGitHubApiUrl(url) ? ` ${GITHUB_TOKEN_HINT}` : "";
+      throw new Error(`HTTP ${res.status} from ${url} after ${maxRetries + 1} attempts.${ghHint}`);
+    } catch (e) {
+      if (externalSignal?.aborted) {
+        throw new Error(`fetch aborted: ${externalSignal.reason?.message ?? "signal aborted"}`);
+      }
+      lastError = e;
+      if (attempt < maxRetries) {
+        const delay = computeDelay(null, attempt, baseDelayMs);
+        console.error(
+          `[retry] ${fetchInit.method ?? "GET"} ${String(url)} (attempt ${attempt + 2}/${maxRetries + 1}, ${e.name ?? "Error"}: ${e.message}, backoff ${delay}ms)`
+        );
+        try {
+          await sleep(delay, externalSignal);
+        } catch {
+          throw e;
+        }
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw lastError ?? new Error(`fetchWithRetry: unexpected exhaustion for ${url}`);
+}
+function computeDelay(res, attempt, baseDelayMs) {
+  if (res) {
+    const retryAfter = res.headers.get("retry-after");
+    if (retryAfter) {
+      const seconds = Number(retryAfter);
+      if (!Number.isNaN(seconds) && seconds > 0) {
+        return Math.min(seconds * 1e3, 6e4);
+      }
+      const date = new Date(retryAfter);
+      if (!Number.isNaN(date.getTime())) {
+        const delayMs = date.getTime() - Date.now();
+        if (delayMs > 0) return Math.min(delayMs, 6e4);
+      }
+    }
+  }
+  const exponential = baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * baseDelayMs * 0.5;
+  return Math.min(exponential + jitter, 3e4);
+}
+function sleep(ms, signal) {
+  if (signal?.aborted) return Promise.reject(new Error("sleep interrupted: signal already aborted"));
+  if (!signal) return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve3, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new Error("sleep interrupted: signal aborted"));
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      resolve3();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function isGitHubApiUrl(url) {
+  try {
+    const hostname = typeof url === "string" ? new URL(url).hostname : url.hostname;
+    return hostname === "api.github.com" || hostname === "raw.githubusercontent.com";
+  } catch {
+    const s = String(url);
+    return s.includes("api.github.com") || s.includes("raw.githubusercontent.com");
+  }
+}
+var DEFAULT_FETCH_ALL_TIMEOUT_MS = 5 * 60 * 1e3;
+function createFetchAllController(timeoutMs = DEFAULT_FETCH_ALL_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort(new Error(`fetchAll global timeout exceeded (${timeoutMs}ms)`));
+  }, timeoutMs);
+  if (typeof timer === "object" && "unref" in timer) {
+    timer.unref();
+  }
+  return { controller, signal: controller.signal };
+}
+
+// src/fetch-rss.ts
+async function fetchRssReleases(url, sinceIso, titleFilter, signal) {
+  const res = await fetchWithRetry(url, {
+    headers: { "user-agent": "claude-synergy/0.1.0" },
+    signal
+  });
+  if (!res.ok) throw new Error(`RSS ${url} returned ${res.status}`);
+  const xml = await res.text();
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    cdataPropName: "__cdata",
+    parseTagValue: false,
+    trimValues: true
+  });
+  const parsed = parser.parse(xml);
+  const rawItems = parsed?.rss?.channel?.item ?? [];
+  const items = Array.isArray(rawItems) ? rawItems : [rawItems];
+  const out = [];
+  for (const it of items) {
+    if (!it) continue;
+    const title = pickString(it.title);
+    if (titleFilter && title && !titleFilter.test(title)) continue;
+    const link = pickString(it.link) ?? pickString(it.guid) ?? "";
+    const pubDateRaw = pickString(it.pubDate) ?? pickString(it["dc:date"]) ?? "";
+    const pubDateIso = parsePubDate(pubDateRaw);
+    if (!pubDateIso) continue;
+    if (pubDateIso <= sinceIso) continue;
+    const guid = pickString(it.guid) ?? link;
+    const slug = makeSlug(guid, pubDateIso, title);
+    const body = pickString(it["content:encoded"]) ?? pickString(it.description) ?? null;
+    out.push({ slug, title, link, pubDate: pubDateIso, body });
+  }
+  return out;
+}
+function pickString(v) {
+  if (v == null) return null;
+  if (typeof v === "string") return v.trim() || null;
+  if (typeof v === "object") {
+    const o = v;
+    if (typeof o.__cdata === "string") return o.__cdata.trim() || null;
+    if (typeof o["#text"] === "string") return o["#text"].trim() || null;
+    if (typeof o.toString === "function") {
+      const s = String(v);
+      if (s !== "[object Object]") return s.trim() || null;
+    }
+  }
+  return null;
+}
+function parsePubDate(raw) {
+  if (!raw) return null;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toISOString();
+}
+function makeSlug(guid, isoDate, title) {
+  try {
+    const u = new URL(guid);
+    const parts = u.pathname.split("/").filter(Boolean);
+    const last = parts[parts.length - 1];
+    if (last && /^[a-z0-9][a-z0-9._-]*$/i.test(last)) {
+      return last.replace(/\.html?$/, "").toLowerCase();
+    }
+  } catch {
+  }
+  const date = isoDate.split("T")[0];
+  if (title) {
+    const titleSlug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+    return `${date}-${titleSlug}`;
+  }
+  return date;
+}
+
+// src/fetch-changelog.ts
+import { execSync } from "child_process";
+async function fetchAiderHistory(url, sinceIso, signal) {
+  const res = await fetchWithRetry(url, {
+    headers: { "user-agent": "claude-synergy/0.1.0" },
+    signal
+  });
+  if (!res.ok) throw new Error(`raw-changelog ${url} returned ${res.status}`);
+  const md = await res.text();
+  const items = parseAiderHistory(md);
+  const releaseDates = aiderReleaseDates();
+  for (const item of items) {
+    const tag = `v${item.version}`;
+    if (releaseDates.has(tag)) {
+      item.releasedAt = releaseDates.get(tag);
+    }
+  }
+  return items.filter((i) => !i.releasedAt || i.releasedAt > sinceIso);
+}
+function parseAiderHistory(md) {
+  const lines = md.split("\n");
+  const out = [];
+  let currentVersion = null;
+  let currentBody = [];
+  const flush = () => {
+    if (currentVersion) {
+      out.push({
+        version: currentVersion,
+        releasedAt: null,
+        body: currentBody.join("\n").trim()
+      });
+    }
+    currentBody = [];
+  };
+  for (const line of lines) {
+    const headerMatch = line.match(/^###\s+(?:Aider\s+)?(?:v(\d+\.\d+\.\d+(?:[-.][\w.]+)?)|main\s+branch)\s*$/i);
+    if (headerMatch) {
+      flush();
+      currentVersion = headerMatch[1] ?? "main";
+      continue;
+    }
+    if (currentVersion) currentBody.push(line);
+  }
+  flush();
+  return out.filter((i) => i.body.length > 0 || i.version !== "main");
+}
+function aiderReleaseDates() {
+  try {
+    const out = execSync(`gh api "repos/Aider-AI/aider/releases?per_page=100"`, {
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const releases = JSON.parse(out);
+    const map = /* @__PURE__ */ new Map();
+    for (const r of releases) if (r.tag_name && r.published_at) map.set(r.tag_name, r.published_at);
+    return map;
+  } catch (e) {
+    const stderr = (e?.stderr ?? "").toString();
+    if (stderr.includes("403") || stderr.includes("429") || stderr.includes("rate limit")) {
+      console.error(
+        "[claude-synergy] GitHub API rate limit hit while fetching aider release dates. Set GITHUB_TOKEN env var for 5000 req/hr (vs 60 unauthenticated)."
+      );
+    }
+    return /* @__PURE__ */ new Map();
+  }
+}
+
+// src/fetch-html.ts
+import * as cheerio from "cheerio";
+var UA = { "user-agent": "claude-synergy/0.1.0" };
+async function fetchGithubCopilotBlog(sinceIso, signal) {
+  const baseUrl = "https://github.blog/changelog/label/copilot/";
+  const entryUrls = /* @__PURE__ */ new Set();
+  for (let page = 1; page <= 3; page++) {
+    const url = page === 1 ? baseUrl : `${baseUrl}page/${page}/`;
+    try {
+      const res = await fetchWithRetry(url, { headers: UA, signal });
+      if (!res.ok) break;
+      const html = await res.text();
+      const $ = cheerio.load(html);
+      $('a[href*="/changelog/"]').each((_, el) => {
+        const href = $(el).attr("href");
+        if (!href) return;
+        const m = href.match(/^(?:https:\/\/github\.blog)?(\/changelog\/20\d{2}-\d{2}-\d{2}-[^/?#]+\/?)$/);
+        if (m) entryUrls.add(`https://github.blog${m[1].startsWith("/") ? m[1] : "/" + m[1]}`);
+      });
+    } catch {
+      break;
+    }
+  }
+  const items = [];
+  for (const url of entryUrls) {
+    const slugMatch = url.match(/\/changelog\/(20\d{2}-\d{2}-\d{2})-([^/]+)\/?$/);
+    if (!slugMatch) continue;
+    const dateStr = slugMatch[1];
+    const pubDate = (/* @__PURE__ */ new Date(`${dateStr}T12:00:00Z`)).toISOString();
+    if (pubDate <= sinceIso) continue;
+    try {
+      const res = await fetchWithRetry(url, { headers: UA, signal });
+      if (!res.ok) continue;
+      const html = await res.text();
+      const $ = cheerio.load(html);
+      const title = ($("h1").first().text() || $('meta[property="og:title"]').attr("content") || "").trim();
+      const bodyEl = $("article").first();
+      const body = (bodyEl.length ? bodyEl.html() : $("main").first().html()) ?? "";
+      items.push({
+        slug: `${dateStr}-${slugMatch[2]}`,
+        title,
+        pubDate,
+        link: url,
+        body: body.trim()
+      });
+    } catch {
+      continue;
+    }
+  }
+  return items;
+}
+async function fetchWindsurfChangelog(sinceIso, signal) {
+  const url = "https://windsurf.com/changelog";
+  const res = await fetchWithRetry(url, { headers: UA, signal });
+  if (!res.ok) throw new Error(`Windsurf ${res.status}`);
+  const html = await res.text();
+  const $ = cheerio.load(html);
+  const nextDataScript = $("script#__NEXT_DATA__").html();
+  if (!nextDataScript) {
+    console.error("[fetch-html] windsurf: __NEXT_DATA__ not found; changelog is client-rendered. Use the playwright strategy (src/fetch-playwright.ts) for full coverage. 0 entries.");
+    return [];
+  }
+  try {
+    const data = JSON.parse(nextDataScript);
+    const entries = findChangelogEntries(data);
+    if (!entries || entries.length === 0) {
+      console.error("[fetch-html] windsurf: __NEXT_DATA__ present but no entry array found. 0 entries.");
+      return [];
+    }
+    const items = [];
+    for (const e of entries) {
+      const title = (e.title ?? e.heading ?? e.name ?? "").toString().trim();
+      const dateRaw = (e.date ?? e.publishedAt ?? e.published_at ?? "").toString();
+      if (!title || !dateRaw) continue;
+      const d = new Date(dateRaw);
+      if (Number.isNaN(d.getTime())) continue;
+      const pubDate = d.toISOString();
+      if (pubDate <= sinceIso) continue;
+      const body = (e.body ?? e.content ?? e.description ?? "").toString();
+      const titleSlug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+      const slug = `${pubDate.split("T")[0]}-${titleSlug || "entry"}`;
+      items.push({ slug, title, pubDate, link: `${url}#${titleSlug}`, body });
+    }
+    return items;
+  } catch (e) {
+    console.error(`[fetch-html] windsurf: __NEXT_DATA__ parse failed: ${e.message}`);
+    return [];
+  }
+}
+function findChangelogEntries(obj, depth = 0) {
+  if (depth > 8 || !obj || typeof obj !== "object") return null;
+  if (Array.isArray(obj)) {
+    if (obj.length > 0 && typeof obj[0] === "object" && obj[0] !== null && (typeof obj[0].title === "string" || typeof obj[0].heading === "string") && (typeof obj[0].date === "string" || typeof obj[0].publishedAt === "string" || typeof obj[0].published_at === "string")) {
+      return obj;
+    }
+    return null;
+  }
+  for (const v of Object.values(obj)) {
+    const found = findChangelogEntries(v, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+var VSCODE_V_TO_MONTH = {
+  // version → [year, month-1 (0-indexed)]
+  100: [2025, 3],
+  // April 2025
+  101: [2025, 4],
+  // May 2025
+  102: [2025, 5],
+  // June 2025
+  103: [2025, 6],
+  // July 2025
+  104: [2025, 7],
+  // August 2025
+  105: [2025, 8],
+  // September 2025
+  106: [2025, 9],
+  // October 2025
+  107: [2025, 10],
+  // November 2025
+  108: [2025, 11],
+  // December 2025
+  109: [2026, 0],
+  // January 2026
+  110: [2026, 1],
+  // February 2026
+  111: [2026, 2],
+  // March 2026
+  112: [2026, 3],
+  // April 2026
+  113: [2026, 4],
+  // May 2026
+  114: [2026, 5],
+  // June 2026 (future / Insiders)
+  115: [2026, 6],
+  // July 2026 (future / Insiders)
+  116: [2026, 7],
+  117: [2026, 8],
+  118: [2026, 9],
+  119: [2026, 10],
+  120: [2026, 11]
+};
+function parseVscodeReleaseDate(html, $) {
+  const releaseDateMatch = html.match(
+    /Release\s+date[:\s]*((?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2},\s*\d{4})/i
+  );
+  if (releaseDateMatch) {
+    const d = new Date(releaseDateMatch[1]);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  const timeEl = $("time[datetime]").first();
+  if (timeEl.length) {
+    const iso = timeEl.attr("datetime");
+    if (iso) {
+      const d = new Date(iso);
+      if (!Number.isNaN(d.getTime())) return d.toISOString();
+    }
+  }
+  const welcomeMatch = html.match(
+    /Welcome to the\s+((?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{4})/i
+  );
+  if (welcomeMatch) {
+    const d = /* @__PURE__ */ new Date(`${welcomeMatch[1]} 15`);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  return null;
+}
+async function fetchVscodeUpdates(sinceIso, signal) {
+  const items = [];
+  for (const [vStr, [year, monthIdx]] of Object.entries(VSCODE_V_TO_MONTH)) {
+    const v = parseInt(vStr, 10);
+    const fallbackIsoDate = new Date(Date.UTC(year, monthIdx, 15, 12)).toISOString();
+    const versionTag = `v1_${v}`;
+    const url = `https://code.visualstudio.com/updates/${versionTag}`;
+    const fallbackPlus31d = new Date(Date.parse(fallbackIsoDate) + 31 * 24 * 3600 * 1e3).toISOString();
+    if (fallbackPlus31d <= sinceIso) continue;
+    try {
+      const res = await fetchWithRetry(url, { headers: UA, signal, maxRetries: 1 });
+      if (res.status === 404) continue;
+      if (!res.ok) continue;
+      const html = await res.text();
+      const $ = cheerio.load(html);
+      let isoDate = parseVscodeReleaseDate(html, $);
+      if (!isoDate) {
+        console.warn(
+          `[fetch-html] vscode ${versionTag}: no Release-date line found; falling back to mid-month (${fallbackIsoDate.split("T")[0]})`
+        );
+        isoDate = fallbackIsoDate;
+      }
+      if (isoDate <= sinceIso) continue;
+      const title = $("h1").first().text().trim() || `Visual Studio Code 1.${v}`;
+      const body = ($("main").first().html() || $("article").first().html() || "").trim();
+      if (body.length < 200) continue;
+      items.push({
+        slug: versionTag,
+        title,
+        pubDate: isoDate,
+        link: url,
+        body
+      });
+    } catch {
+      continue;
+    }
+  }
+  return items;
+}
+async function fetchHtmlReleases(parser, sinceIso, signal) {
+  switch (parser) {
+    case "github-copilot-blog":
+      return fetchGithubCopilotBlog(sinceIso, signal);
+    case "windsurf-changelog":
+      return fetchWindsurfChangelog(sinceIso, signal);
+    case "vscode-updates":
+      return fetchVscodeUpdates(sinceIso, signal);
+  }
+}
+
+// src/fetch-mcp-registry.ts
+import { writeFileSync, mkdirSync } from "fs";
+import { join as join2 } from "path";
+var UA2 = { "user-agent": "claude-synergy/0.1.0", accept: "application/json" };
+async function fetchOfficialMcpRegistry(opts = {}) {
+  const maxPages = opts.maxPages ?? 50;
+  const limit = 100;
+  let cursor;
+  const byName = /* @__PURE__ */ new Map();
+  for (let page = 0; page < maxPages; page++) {
+    const url = `https://registry.modelcontextprotocol.io/v0/servers?limit=${limit}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+    const res = await fetchWithRetry(url, { headers: UA2, signal: opts.signal });
+    if (!res.ok) throw new Error(`Official MCP Registry ${res.status}`);
+    const json = await res.json();
+    if (!Array.isArray(json.servers)) break;
+    for (const item of json.servers) {
+      const s = item.server;
+      if (!s?.name) continue;
+      const meta = item._meta?.["io.modelcontextprotocol.registry/official"];
+      const isLatest = meta?.isLatest === true;
+      const existing = byName.get(s.name);
+      if (existing && !isLatest) continue;
+      byName.set(s.name, {
+        slug: slugify(s.name),
+        name: s.title ?? s.name,
+        description: (s.description ?? "").trim(),
+        homepage: s.remotes?.[0]?.url ?? null,
+        popularity: null,
+        createdAt: meta?.publishedAt ?? null,
+        source: "official-mcp-registry",
+        category: null,
+        verified: null
+      });
+    }
+    const next = json.metadata?.nextCursor;
+    if (!next || next === cursor) break;
+    cursor = next;
+  }
+  return [...byName.values()];
+}
+async function fetchSmitheryRegistry(opts = {}) {
+  const pageSize = opts.pageSize ?? 100;
+  const maxEntries = opts.maxEntries ?? 200;
+  const out = [];
+  let page = 1;
+  while (out.length < maxEntries) {
+    const url = `https://registry.smithery.ai/servers?page=${page}&pageSize=${pageSize}`;
+    const res = await fetchWithRetry(url, { headers: UA2, signal: opts.signal });
+    if (!res.ok) throw new Error(`Smithery Registry ${res.status}`);
+    const json = await res.json();
+    if (!Array.isArray(json.servers) || json.servers.length === 0) break;
+    for (const s of json.servers) {
+      if (out.length >= maxEntries) break;
+      out.push({
+        slug: slugify(s.qualifiedName ?? s.namespace ?? s.id),
+        name: s.displayName ?? s.qualifiedName,
+        description: (s.description ?? "").trim(),
+        homepage: s.homepage ?? null,
+        popularity: typeof s.useCount === "number" ? s.useCount : null,
+        createdAt: s.createdAt ?? null,
+        source: "smithery",
+        category: null,
+        verified: s.verified ?? null
+      });
+    }
+    const total = json.pagination?.totalPages ?? 1;
+    if (page >= total) break;
+    page++;
+  }
+  out.sort((a, b) => (b.popularity ?? 0) - (a.popularity ?? 0));
+  return out;
+}
+function writeCatalog(productDir, productName, entries) {
+  mkdirSync(productDir, { recursive: true });
+  const catalogPath = join2(productDir, "CATALOG.md");
+  const lines = [];
+  lines.push(`# ${productName} \u2014 MCP server catalog`);
+  lines.push("");
+  lines.push(`**Source:** ${entries[0]?.source ?? "unknown"}`);
+  lines.push(`**Entries:** ${entries.length}`);
+  lines.push(`**Fetched:** ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`);
+  lines.push("");
+  lines.push("| Name | Description | Popularity | Created | Homepage |");
+  lines.push("|------|-------------|------------|---------|----------|");
+  for (const e of entries) {
+    const desc = (e.description.split("\n")[0] ?? "").slice(0, 160).replace(/\|/g, "\\|");
+    const pop = e.popularity != null ? String(e.popularity) : "\u2014";
+    const date = e.createdAt ? e.createdAt.split("T")[0] : "\u2014";
+    const home = e.homepage ? `[link](${e.homepage})` : "\u2014";
+    const name = e.name.replace(/\|/g, "\\|");
+    lines.push(`| ${name} | ${desc} | ${pop} | ${date} | ${home} |`);
+  }
+  lines.push("");
+  writeFileSync(catalogPath, lines.join("\n"), "utf-8");
+  return {
+    source: entries[0]?.source ?? "unknown",
+    entriesFetched: entries.length,
+    productDir,
+    catalogPath
+  };
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+}
+async function fetchCatalog(catalogType, opts = {}) {
+  switch (catalogType) {
+    case "official-mcp-registry":
+      return fetchOfficialMcpRegistry({ maxPages: opts.maxPages, signal: opts.signal });
+    case "smithery":
+      return fetchSmitheryRegistry({ maxEntries: opts.maxEntries, signal: opts.signal });
+  }
+}
+
+// src/fetch.ts
+var REPO_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+var PRODUCT_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function assertRepoShape(repo) {
+  if (!REPO_PATTERN.test(repo)) {
+    throw new Error(
+      `invalid repo: ${JSON.stringify(repo)} \u2014 expected "<org>/<repo>" with safe chars [A-Za-z0-9._-]`
+    );
+  }
+}
+function assertProductShape(product) {
+  if (!PRODUCT_PATTERN.test(product)) {
+    throw new Error(
+      `invalid product name: ${JSON.stringify(product)} \u2014 expected [a-z0-9][a-z0-9-]*`
+    );
+  }
+}
+function sanitizeFilename(s) {
+  const cleaned = s.replace(/[\/\\]/g, "-").replace(/^\.+/, "").replace(/\.\./g, "-").replace(/[<>:"|?*\x00-\x1f]/g, "-").slice(0, 100);
+  if (cleaned.includes("..") || cleaned.includes("/") || cleaned.includes("\\")) {
+    throw new Error(`sanitizeFilename produced unsafe output: ${JSON.stringify(cleaned)}`);
+  }
+  return cleaned;
+}
+function assertSafeFilename(name, context) {
+  if (!name || name.includes("..") || name.includes("/") || name.includes("\\")) {
+    throw new Error(`unsafe filename in ${context}: ${JSON.stringify(name)}`);
+  }
+}
+var HARDCODED_FALLBACK_TARGETS = [
+  // ── Existing Anthropic GH-Releases sources ────────────────────────────────
+  { product: "claude-agent-sdk-python", strategy: "gh-releases", repo: "anthropics/claude-agent-sdk-python" },
+  { product: "claude-agent-sdk-typescript", strategy: "gh-releases", repo: "anthropics/claude-agent-sdk-typescript" },
+  { product: "anthropic-cli", strategy: "gh-releases", repo: "anthropics/anthropic-cli" },
+  { product: "anthropic-sdk-python", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-python" },
+  { product: "anthropic-sdk-typescript", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-typescript", multiPackage: true },
+  { product: "anthropic-sdk-go", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-go" },
+  { product: "anthropic-sdk-java", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-java" },
+  { product: "anthropic-sdk-ruby", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-ruby" },
+  { product: "anthropic-sdk-csharp", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-csharp", multiPackage: true },
+  { product: "anthropic-sdk-php", strategy: "gh-releases", repo: "anthropics/anthropic-sdk-php" },
+  { product: "claude-code-action", strategy: "gh-releases", repo: "anthropics/claude-code-action" },
+  { product: "claude-code-security-review", strategy: "gh-releases", repo: "anthropics/claude-code-security-review" },
+  // ── Tier 4a additions ─────────────────────────────────────────────────────
+  // MCP ecosystem SDKs (modelcontextprotocol/*)
+  { product: "mcp-python-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/python-sdk" },
+  { product: "mcp-typescript-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/typescript-sdk", multiPackage: true },
+  { product: "mcp-go-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/go-sdk" },
+  { product: "mcp-java-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/java-sdk" },
+  { product: "mcp-csharp-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/csharp-sdk" },
+  { product: "mcp-kotlin-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/kotlin-sdk" },
+  { product: "mcp-ruby-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/ruby-sdk" },
+  { product: "mcp-swift-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/swift-sdk" },
+  { product: "mcp-rust-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/rust-sdk" },
+  { product: "mcp-php-sdk", strategy: "gh-releases", repo: "modelcontextprotocol/php-sdk" },
+  { product: "mcp-spec", strategy: "gh-releases", repo: "modelcontextprotocol/modelcontextprotocol" },
+  { product: "mcp-inspector", strategy: "gh-releases", repo: "modelcontextprotocol/inspector" },
+  { product: "mcp-registry", strategy: "gh-releases", repo: "modelcontextprotocol/registry" },
+  { product: "mcp-mcpb", strategy: "gh-releases", repo: "modelcontextprotocol/mcpb" },
+  { product: "mcp-conformance", strategy: "gh-releases", repo: "modelcontextprotocol/conformance" },
+  // Continue.dev (multi-platform tagged releases)
+  { product: "continue-dev", strategy: "gh-releases", repo: "continuedev/continue", multiPackage: true },
+  { product: "continue-cli", strategy: "gh-releases", repo: "continuedev/continue-cli" },
+  // RSS-based feeds
+  { product: "cursor", strategy: "rss", rssUrl: "https://cursor.com/changelog/rss.xml" },
+  { product: "cody-enterprise", strategy: "rss", rssUrl: "https://sourcegraph.com/changelog/featured.rss", rssTitleFilter: /cody|sourcegraph/i },
+  // Raw markdown CHANGELOG
+  { product: "aider", strategy: "raw-changelog", rawChangelogUrl: "https://raw.githubusercontent.com/Aider-AI/aider/main/HISTORY.md", rawChangelogParser: "aider-history" },
+  // ── Tier 4b additions — HTML-scraped sources ──────────────────────────────
+  { product: "github-copilot", strategy: "html-scrape", htmlParser: "github-copilot-blog" },
+  { product: "vscode-copilot-chat", strategy: "html-scrape", htmlParser: "vscode-updates" },
+  { product: "windsurf", strategy: "html-scrape", htmlParser: "windsurf-changelog" }
+];
+var TARGETS = loadProductsConfig()?.fetchTargets ?? HARDCODED_FALLBACK_TARGETS;
+async function fetchAll(db, productsRoot, opts = {}) {
+  const targets = opts.product ? TARGETS.filter((t) => t.product === opts.product) : TARGETS;
+  if (targets.length === 0) {
+    throw new Error(`unknown product: ${opts.product} (available: ${TARGETS.map((t) => t.product).join(", ")})`);
+  }
+  const total = targets.length;
+  const onProgress = opts.onProgress;
+  const globalTimeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_ALL_TIMEOUT_MS;
+  const { controller, signal } = createFetchAllController(globalTimeoutMs);
+  const results = [];
+  try {
+    for (let i = 0; i < targets.length; i++) {
+      const target = targets[i];
+      if (signal.aborted) {
+        onProgress?.({ type: "skip", product: target.product, index: i, total, error: "global timeout exceeded" });
+        results.push({
+          product: target.product,
+          fetched: 0,
+          newSince: opts.sinceOverride ?? "",
+          latest: null,
+          errors: ["skipped: global timeout exceeded"]
+        });
+        continue;
+      }
+      onProgress?.({ type: "start", product: target.product, index: i, total });
+      const stats = await fetchOne(db, productsRoot, target, opts.sinceOverride, signal);
+      results.push(stats);
+      if (stats.errors.length > 0) {
+        onProgress?.({ type: "error", product: target.product, index: i, total, error: stats.errors[0] });
+      } else {
+        onProgress?.({ type: "done", product: target.product, index: i, total });
+      }
+    }
+  } finally {
+    controller.abort();
+  }
+  const augmented = results;
+  augmented.summary = buildSummary(results);
+  return augmented;
+}
+function buildSummary(results) {
+  let succeeded = 0;
+  let failed = 0;
+  let skipped = 0;
+  let newChanges = 0;
+  const errors = [];
+  for (const r of results) {
+    const isSkipped = r.errors.some((e) => e.startsWith("skipped:"));
+    const isFailed = r.errors.length > 0 && !isSkipped;
+    if (isSkipped) {
+      skipped++;
+    } else if (isFailed) {
+      failed++;
+      for (const e of r.errors) {
+        errors.push({ product: r.product, error: e });
+      }
+    } else {
+      succeeded++;
+    }
+    newChanges += r.fetched;
+  }
+  return { total: results.length, succeeded, failed, skipped, newChanges, errors };
+}
+async function fetchOne(db, productsRoot, target, sinceOverride, signal) {
+  assertProductShape(target.product);
+  const since = sinceOverride ?? readMarker(db, target.product) ?? "2026-01-01";
+  const outDir = resolve(productsRoot, target.product, "releases");
+  mkdirSync2(outDir, { recursive: true });
+  try {
+    switch (target.strategy) {
+      case "gh-releases":
+        return await fetchGhReleases(db, outDir, target, since);
+      case "rss":
+        return await fetchRss(db, outDir, target, since, signal);
+      case "raw-changelog":
+        return await fetchRawChangelog(db, outDir, target, since, signal);
+      case "html-scrape":
+        return await fetchHtmlScrape(db, outDir, target, since, signal);
+      case "catalog":
+        return await fetchCatalogStrategy(db, productsRoot, target, since, signal);
+      case "playwright":
+        return await fetchPlaywrightStrategy(db, outDir, target, since);
+    }
+  } catch (e) {
+    return {
+      product: target.product,
+      fetched: 0,
+      newSince: since,
+      latest: null,
+      errors: [`fetch failed: ${e.message}`]
+    };
+  }
+}
+async function fetchGhReleases(db, outDir, target, since) {
+  if (!target.repo) throw new Error(`${target.product}: gh-releases strategy requires repo`);
+  const releases = ghReleases(target.repo, since);
+  let latest = null;
+  let fetched = 0;
+  const errors = [];
+  for (const r of releases) {
+    try {
+      const baseName = filenameFor(target, r.tag_name);
+      const filename = sanitizeFilename(baseName);
+      assertSafeFilename(filename, `gh-releases filename for tag ${JSON.stringify(r.tag_name)}`);
+      const vName = sanitizeFilename(`v${baseName}`);
+      assertSafeFilename(vName, `gh-releases vName for tag ${JSON.stringify(r.tag_name)}`);
+      const path = join3(outDir, `${filename}.md`);
+      const vPath = join3(outDir, `${vName}.md`);
+      if (existsSync(path) || existsSync(vPath)) {
+        if (!latest || r.published_at > latest) latest = r.published_at;
+        continue;
+      }
+      writeFileSync2(path, renderGhRelease(target.product, r), "utf-8");
+      fetched++;
+      if (!latest || r.published_at > latest) latest = r.published_at;
+    } catch (e) {
+      errors.push(`${r.tag_name}: ${e.message}`);
+    }
+  }
+  if (latest) writeMarker(db, target.product, latest, target.strategy);
+  return { product: target.product, fetched, newSince: since, latest, errors };
+}
+function ghReleases(repo, sinceIso) {
+  assertRepoShape(repo);
+  const all = [];
+  const MAX_PAGES = 50;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    let out;
+    try {
+      out = execFileSync(
+        "gh",
+        ["api", `repos/${repo}/releases?per_page=100&page=${page}`],
+        { encoding: "utf-8", maxBuffer: 50 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }
+      );
+    } catch (e) {
+      const stderr = (e.stderr ?? "").toString();
+      if (stderr.includes("404")) return page === 1 ? [] : all;
+      if (stderr.includes("403") || stderr.includes("429") || stderr.includes("rate limit")) {
+        throw new Error(
+          `GitHub API rate limit hit for ${repo}. Set GITHUB_TOKEN env var for 5000 req/hr (vs 60 unauthenticated). Original error: ${e.message}`
+        );
+      }
+      throw e;
+    }
+    let batch;
+    try {
+      batch = JSON.parse(out);
+    } catch {
+      return page === 1 ? [] : all;
+    }
+    if (!Array.isArray(batch) || batch.length === 0) break;
+    all.push(...batch);
+    if (batch.length < 100) break;
+  }
+  return all.filter((r) => r.published_at && r.published_at > sinceIso).map((r) => ({
+    tag_name: r.tag_name,
+    published_at: r.published_at,
+    name: r.name,
+    body: r.body,
+    html_url: r.html_url
+  }));
+}
+function filenameFor(target, tag) {
+  if (target.multiPackage) {
+    return tag.replace(/^@/, "").replace(/\//g, "-").replace(/@/g, "-").replace(/-v(\d)/g, "-$1").replace(/^v/, "");
+  }
+  return tag.replace(/^v/, "");
+}
+function yamlQuote(s) {
+  if (s == null) return "";
+  return s.replace(/[\x00-\x1f]/g, " ").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function renderGhRelease(product, r) {
+  const version = (r.tag_name ?? "").replace(/^v/, "");
+  return [
+    "---",
+    `product: ${product}`,
+    `version: "${yamlQuote(version)}"`,
+    `released_at: "${r.published_at.split("T")[0]}"`,
+    `source_url: "${yamlQuote(r.html_url)}"`,
+    `fetched_at: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"`,
+    "---",
+    "",
+    `# ${product} ${r.tag_name}`,
+    "",
+    r.body ?? "(no body)",
+    ""
+  ].join("\n");
+}
+async function fetchRss(db, outDir, target, since, signal) {
+  if (!target.rssUrl) throw new Error(`${target.product}: rss strategy requires rssUrl`);
+  const items = await fetchRssReleases(target.rssUrl, since, target.rssTitleFilter, signal);
+  let latest = null;
+  let fetched = 0;
+  const errors = [];
+  for (const item of items) {
+    try {
+      const safeSlug = sanitizeFilename(item.slug);
+      assertSafeFilename(safeSlug, `rss slug for ${JSON.stringify(item.slug)}`);
+      const path = join3(outDir, `${safeSlug}.md`);
+      if (existsSync(path)) {
+        if (!latest || item.pubDate > latest) latest = item.pubDate;
+        continue;
+      }
+      const body = [
+        "---",
+        `product: ${target.product}`,
+        `version: "${yamlQuote(safeSlug)}"`,
+        `released_at: "${item.pubDate.split("T")[0]}"`,
+        `source_url: "${yamlQuote(item.link)}"`,
+        `fetched_at: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"`,
+        `title: "${yamlQuote(item.title ?? "")}"`,
+        "---",
+        "",
+        `# ${target.product} \u2014 ${item.title ?? safeSlug}`,
+        "",
+        item.body ?? "(no body)",
+        ""
+      ].join("\n");
+      writeFileSync2(path, body, "utf-8");
+      fetched++;
+      if (!latest || item.pubDate > latest) latest = item.pubDate;
+    } catch (e) {
+      errors.push(`${item.slug}: ${e.message}`);
+    }
+  }
+  if (latest) writeMarker(db, target.product, latest, target.strategy);
+  return { product: target.product, fetched, newSince: since, latest, errors };
+}
+async function fetchRawChangelog(db, outDir, target, since, signal) {
+  if (!target.rawChangelogUrl) throw new Error(`${target.product}: raw-changelog requires url`);
+  if (target.rawChangelogParser !== "aider-history") {
+    throw new Error(`${target.product}: unsupported parser ${target.rawChangelogParser}`);
+  }
+  const items = await fetchAiderHistory(target.rawChangelogUrl, since, signal);
+  let latest = null;
+  let fetched = 0;
+  const errors = [];
+  for (const item of items) {
+    try {
+      const safeVersion = sanitizeFilename(item.version);
+      assertSafeFilename(safeVersion, `raw-changelog version for ${JSON.stringify(item.version)}`);
+      const path = join3(outDir, `${safeVersion}.md`);
+      if (existsSync(path)) {
+        if (item.releasedAt && (!latest || item.releasedAt > latest)) latest = item.releasedAt;
+        continue;
+      }
+      const body = [
+        "---",
+        `product: ${target.product}`,
+        `version: "${yamlQuote(safeVersion)}"`,
+        `released_at: ${item.releasedAt ? `"${yamlQuote(item.releasedAt)}"` : "null"}`,
+        `source_url: "${yamlQuote(target.rawChangelogUrl ?? "")}"`,
+        `fetched_at: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"`,
+        "---",
+        "",
+        `# ${target.product} v${item.version}`,
+        "",
+        item.body,
+        ""
+      ].join("\n");
+      writeFileSync2(path, body, "utf-8");
+      fetched++;
+      if (item.releasedAt && (!latest || item.releasedAt > latest)) latest = item.releasedAt;
+    } catch (e) {
+      errors.push(`${item.version}: ${e.message}`);
+    }
+  }
+  if (latest) writeMarker(db, target.product, latest, target.strategy);
+  return { product: target.product, fetched, newSince: since, latest, errors };
+}
+async function fetchHtmlScrape(db, outDir, target, since, signal) {
+  if (!target.htmlParser) throw new Error(`${target.product}: html-scrape requires htmlParser`);
+  const items = await fetchHtmlReleases(target.htmlParser, since, signal);
+  let latest = null;
+  let fetched = 0;
+  const errors = [];
+  for (const item of items) {
+    try {
+      const safeSlug = sanitizeFilename(item.slug);
+      assertSafeFilename(safeSlug, `html-scrape slug for ${JSON.stringify(item.slug)}`);
+      const path = join3(outDir, `${safeSlug}.md`);
+      if (existsSync(path)) {
+        if (!latest || item.pubDate > latest) latest = item.pubDate;
+        continue;
+      }
+      const body = [
+        "---",
+        `product: ${target.product}`,
+        `version: "${yamlQuote(safeSlug)}"`,
+        `released_at: "${item.pubDate.split("T")[0]}"`,
+        `source_url: "${yamlQuote(item.link)}"`,
+        `fetched_at: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"`,
+        `title: "${yamlQuote(item.title ?? "")}"`,
+        "---",
+        "",
+        `# ${target.product} \u2014 ${item.title ?? safeSlug}`,
+        "",
+        item.body ?? "(no body)",
+        ""
+      ].join("\n");
+      writeFileSync2(path, body, "utf-8");
+      fetched++;
+      if (!latest || item.pubDate > latest) latest = item.pubDate;
+    } catch (e) {
+      errors.push(`${item.slug}: ${e.message}`);
+    }
+  }
+  if (latest) writeMarker(db, target.product, latest, target.strategy);
+  return { product: target.product, fetched, newSince: since, latest, errors };
+}
+async function fetchPlaywrightStrategy(db, outDir, target, since) {
+  const { fetchWindsurfWithPlaywright } = await import("./fetch-playwright-HQ6OTMSQ.js");
+  const items = await fetchWindsurfWithPlaywright(since);
+  let latest = null;
+  let fetched = 0;
+  const errors = [];
+  for (const item of items) {
+    try {
+      const safeSlug = sanitizeFilename(item.slug);
+      assertSafeFilename(safeSlug, `playwright slug for ${JSON.stringify(item.slug)}`);
+      const path = join3(outDir, `${safeSlug}.md`);
+      if (existsSync(path)) {
+        if (!latest || item.pubDate > latest) latest = item.pubDate;
+        continue;
+      }
+      const body = [
+        "---",
+        `product: ${target.product}`,
+        `version: "${yamlQuote(safeSlug)}"`,
+        `released_at: "${item.pubDate.split("T")[0]}"`,
+        `source_url: "${yamlQuote(item.link)}"`,
+        `fetched_at: "${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}"`,
+        `title: "${yamlQuote(item.title ?? "")}"`,
+        "---",
+        "",
+        `# ${target.product} \u2014 ${item.title ?? safeSlug}`,
+        "",
+        item.body ?? "(no body)",
+        ""
+      ].join("\n");
+      writeFileSync2(path, body, "utf-8");
+      fetched++;
+      if (!latest || item.pubDate > latest) latest = item.pubDate;
+    } catch (e) {
+      errors.push(`${item.slug}: ${e.message}`);
+    }
+  }
+  if (latest) writeMarker(db, target.product, latest, target.strategy);
+  return { product: target.product, fetched, newSince: since, latest, errors };
+}
+async function fetchCatalogStrategy(db, productsRoot, target, since, signal) {
+  if (!target.catalogType) throw new Error(`${target.product}: catalog requires catalogType`);
+  const entries = await fetchCatalog(target.catalogType, { maxEntries: target.catalogMaxEntries, signal });
+  const productDir = resolve(productsRoot, target.product);
+  writeCatalog(productDir, target.product, entries);
+  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  writeMarker(db, target.product, nowIso, target.strategy);
+  return {
+    product: target.product,
+    fetched: entries.length,
+    newSince: since,
+    latest: nowIso,
+    errors: []
+  };
+}
+function readMarker(db, product) {
+  const row = db.prepare(`SELECT version FROM markers WHERE product = ? AND name = 'last_fetched_release_at'`).get(product);
+  return row?.version ?? null;
+}
+function writeMarker(db, product, isoTimestamp, fetchStrategy = "gh-releases") {
+  assertProductShape(product);
+  db.prepare(`
+    INSERT OR IGNORE INTO products (name, display_name, source_tier, source_url, fetch_strategy, notes)
+    VALUES (?, ?, 1, '', ?, NULL)
+  `).run(product, product, fetchStrategy);
+  db.prepare(`
+    INSERT INTO markers (product, name, version, updated_at)
+    VALUES (?, 'last_fetched_release_at', ?, ?)
+    ON CONFLICT(product, name) DO UPDATE SET version = excluded.version, updated_at = excluded.updated_at
+  `).run(product, isoTimestamp, (/* @__PURE__ */ new Date()).toISOString());
+}
+function seedMarkersFromDb(db) {
+  const rows = db.prepare(
+    `SELECT product, MAX(released_at) AS max_date FROM releases WHERE released_at IS NOT NULL GROUP BY product`
+  ).all();
+  const out = [];
+  for (const t of TARGETS) {
+    const r = rows.find((x) => x.product === t.product);
+    if (r?.max_date) {
+      const iso = r.max_date.includes("T") ? r.max_date : `${r.max_date}T23:59:59Z`;
+      writeMarker(db, t.product, iso, t.strategy);
+      out.push({ product: t.product, seededTo: iso });
+    } else {
+      out.push({ product: t.product, seededTo: null });
+    }
+  }
+  return out;
+}
+
+// src/errors.ts
+var AppError = class extends Error {
+  code;
+  hint;
+  cause;
+  retryable;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "AppError";
+    this.code = opts.code;
+    this.hint = opts.hint;
+    this.cause = opts.cause;
+    this.retryable = opts.retryable ?? false;
+  }
+  /** Return the structured JSON shape (useful for --json output and MCP results). */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+      ...this.cause ? { cause: this.cause } : {},
+      ...this.retryable ? { retryable: this.retryable } : {}
+    };
+  }
+};
+function formatError(err, verbose = false) {
+  if (err instanceof AppError) {
+    const lines = [`\u2717 [${err.code}] ${err.message}`];
+    lines.push(`  hint: ${err.hint}`);
+    if (verbose && err.cause) {
+      lines.push(`  cause: ${err.cause}`);
+    }
+    return lines.join("\n");
+  }
+  if (err instanceof Error) {
+    return `\u2717 ${err.message}`;
+  }
+  return `\u2717 ${String(err)}`;
+}
+
+// src/cli.ts
+var LOG_LEVELS = { silent: 0, normal: 1, verbose: 2, debug: 3 };
+function resolveLogLevel() {
+  const env = (process.env.HK_LOG_LEVEL ?? "").toLowerCase();
+  if (env in LOG_LEVELS) return env;
+  if (process.env.HK_DEBUG) return "debug";
+  return "normal";
+}
+var logLevel = resolveLogLevel();
+function logDebug(msg) {
+  if (LOG_LEVELS[logLevel] >= LOG_LEVELS.debug) process.stderr.write(`[debug] ${msg}
+`);
+}
+var activeDb = null;
+function shutdown(signal) {
+  if (activeDb) {
+    try {
+      activeDb.close();
+    } catch {
+    }
+    activeDb = null;
+  }
+  const code = signal === "SIGINT" ? 130 : 143;
+  process.exit(code);
+}
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+var cwd = process.cwd();
+var DEFAULT_DB = join4(cwd, "data", "claude-synergy.db");
+var DEFAULT_PRODUCTS = join4(cwd, "products");
+var _require = createRequire(import.meta.url);
+var { version: PKG_VERSION } = _require("../package.json");
+function intOpt(name, raw, defaultValue, min = 1, max = 1e4) {
+  if (raw === void 0) return defaultValue;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < min || n > max) {
+    console.error(`error: --${name} must be an integer in [${min}, ${max}] (got: ${raw})`);
+    process.exit(1);
+  }
+  return n;
+}
+function openTrackedDb(path) {
+  const db = openDb(path);
+  activeDb = db;
+  return db;
+}
+var CONTEXT_PROVIDERS = ["none", "structured", "ollama", "claude-haiku"];
+var EMBED_PROVIDERS = ["ollama", "voyage"];
+var RERANK_PROVIDERS = ["none", "ollama-judge", "voyage", "cohere"];
+function isDbEmpty(db) {
+  try {
+    const row = db.prepare("SELECT COUNT(*) AS n FROM changes").get();
+    return !row || row.n === 0;
+  } catch {
+    return true;
+  }
+}
+function warnIfEmpty(db) {
+  if (isDbEmpty(db)) {
+    console.error("No data yet. Run `hk sync` to fetch changelogs, then `hk query <term>` to search.");
+    return true;
+  }
+  return false;
+}
+function fmtNum(n) {
+  return n.toLocaleString("en-US");
+}
+function makeFetchProgressWriter() {
+  return (event) => {
+    const idx = `${event.index + 1}/${event.total}`;
+    switch (event.type) {
+      case "start":
+        process.stderr.write(`Fetching ${event.product} (${idx})...
+`);
+        break;
+      case "error":
+        process.stderr.write(`\u2717 ${event.product}: ${event.error ?? "unknown error"}
+`);
+        break;
+      case "skip":
+        process.stderr.write(`\u2298 ${event.product} (skipped \u2014 ${event.error ?? "unknown"})
+`);
+        break;
+    }
+  };
+}
+function printFetchSummary(summary) {
+  const parts = [
+    `${fmtNum(summary.succeeded)} succeeded`,
+    `${fmtNum(summary.failed)} failed`,
+    `${fmtNum(summary.skipped)} skipped`,
+    `${fmtNum(summary.newChanges)} new changes`
+  ];
+  process.stderr.write(`
+Sync complete: ${parts.join(", ")}
+`);
+  if (summary.failed > 0 && summary.errors.length > 0) {
+    const failedList = summary.errors.map((e) => `${e.product} (${e.error})`).join(", ");
+    process.stderr.write(`Failed: ${failedList}
+`);
+  }
+}
+var program = new Command();
+program.name("hk").description("Claude Synergy \u2014 local Anthropic changelog mirror + cross-product synergies").version(PKG_VERSION).enablePositionalOptions().option("--json", "Output results as JSON (for CI/scripting)").option("--verbose", "Show verbose output (also: HK_LOG_LEVEL=verbose)").option("--debug", "Show debug output including query parameters (also: HK_LOG_LEVEL=debug)").hook("preAction", () => {
+  const opts = program.opts();
+  if (opts.debug) logLevel = "debug";
+  else if (opts.verbose) logLevel = "verbose";
+});
+program.command("init").description("Create the database file with the current schema").option("-d, --db <path>", "database path", DEFAULT_DB).action((opts) => {
+  const db = openTrackedDb(opts.db);
+  initSchema(db);
+  console.log(`\u2713 initialized ${resolve2(opts.db)}`);
+  db.close();
+});
+program.command("ingest").description("Parse products/*/releases/*.md and load into DB (idempotent)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --products <path>", "products dir", DEFAULT_PRODUCTS).action((opts) => {
+  if (!existsSync2(opts.products)) {
+    console.error(`\u2717 products dir not found: ${opts.products}`);
+    process.exit(1);
+  }
+  const db = openTrackedDb(opts.db);
+  initSchema(db);
+  const start = Date.now();
+  const stats = ingestAll(db, opts.products);
+  const ms = Date.now() - start;
+  console.log(`\u2713 ingested ${stats.productsCount} products in ${ms}ms`);
+  console.log(`  releases:  ${stats.releasesAdded}`);
+  console.log(`  changes:   ${stats.changesAdded}`);
+  console.log(`  entities:  ${stats.entitiesAdded}`);
+  if (stats.errors.length > 0) {
+    console.log(`
+\u2717 errors: ${stats.errors.length}`);
+    stats.errors.slice(0, 5).forEach((e) => console.log(`  ${e.file}: ${e.error}`));
+    if (stats.errors.length > 5) {
+      console.log(`  ... and ${stats.errors.length - 5} more`);
+    }
+  }
+  db.close();
+});
+program.command("query <text>").description('Full-text search across all change bullets (FTS5). Quote multi-word: hk query "managed agents"').option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "YYYY-MM-DD lower bound").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").option("-l, --limit <n>", "max results", "20").action((text, opts) => {
+  logDebug(`text=${JSON.stringify(text)} opts=${JSON.stringify(opts)}`);
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const q = text;
+  let results;
+  try {
+    results = searchChanges(db, q, {
+      product: opts.product,
+      since: opts.since,
+      kind: opts.kind,
+      limit: intOpt("limit", opts.limit, 20)
+    });
+  } catch (e) {
+    const appErr = new AppError({
+      code: "QUERY_FAILED",
+      message: `query failed: ${e.message}`,
+      hint: `FTS5 syntax \u2014 use double quotes for phrase: hk query '"AskUserQuestion"' or use plain words: hk query AskUserQuestion`,
+      cause: e.message
+    });
+    if (program.opts().json) {
+      console.log(JSON.stringify(appErr.toJSON()));
+    } else {
+      console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+    }
+    db.close();
+    process.exit(1);
+  }
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text,
+      snippet: r.snippet
+    }))));
+  } else if (results.length === 0) {
+    console.log("(no results)");
+  } else {
+    for (const r of results) {
+      console.log(`${r.released_at ?? "????-??-??"}  ${r.product}@${r.version}  [${r.kind}]`);
+      console.log(`  ${r.snippet}`);
+    }
+    console.log(`
+${results.length} result${results.length === 1 ? "" : "s"}`);
+  }
+  db.close();
+});
+program.command("env-var <name>").description("Find when an env var was introduced or last changed").option("-d, --db <path>", "database path", DEFAULT_DB).action((name, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const results = lookupEntity(db, "env_var", name);
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text
+    }))));
+  } else {
+    printEntityResults(name, "env var", results);
+  }
+  db.close();
+});
+program.command("command <slash>").description("Find a slash command's history").option("-d, --db <path>", "database path", DEFAULT_DB).action((slash, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const normalized = slash.startsWith("/") ? slash : "/" + slash;
+  const results = lookupEntity(db, "slash_command", normalized);
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text
+    }))));
+  } else {
+    printEntityResults(normalized, "slash command", results);
+  }
+  db.close();
+});
+program.command("model <id>").description("Find a Claude model ID's history (deprecations, launches)").option("-d, --db <path>", "database path", DEFAULT_DB).action((id, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const results = lookupEntity(db, "model_id", id);
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text
+    }))));
+  } else {
+    printEntityResults(id, "model id", results);
+  }
+  db.close();
+});
+program.command("cve <id>").description("Find releases mentioning a specific CVE").option("-d, --db <path>", "database path", DEFAULT_DB).action((id, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const results = lookupEntity(db, "cve", id);
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text
+    }))));
+  } else {
+    printEntityResults(id, "CVE", results);
+  }
+  db.close();
+});
+program.command("seed-markers").description("Seed fetch markers from the current DB state (run once after study-swarm to enable incremental fetch)").option("-d, --db <path>", "database path", DEFAULT_DB).action((opts) => {
+  const db = openTrackedDb(opts.db);
+  initSchema(db);
+  const results = seedMarkersFromDb(db);
+  for (const r of results) {
+    console.log(`${r.product.padEnd(35)} ${r.seededTo ? "\u2192 " + r.seededTo.split("T")[0] : "(no releases on disk)"}`);
+  }
+  console.log(`
+\u2713 seeded ${results.filter((r) => r.seededTo).length} marker${results.filter((r) => r.seededTo).length === 1 ? "" : "s"}`);
+  db.close();
+});
+program.command("fetch").description("Pull new GitHub releases since last sync (Tier 1 sources only \u2014 10 SDK/CLI products)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-r, --products-root <path>", "products dir root", DEFAULT_PRODUCTS).option("-p, --product <name>", "limit to one product").option("--since <iso>", "override the stored marker (YYYY-MM-DD or full ISO)").action(async (opts) => {
+  const db = openTrackedDb(opts.db);
+  initSchema(db);
+  try {
+    const stats = await fetchAll(db, opts.productsRoot, {
+      product: opts.product,
+      sinceOverride: opts.since,
+      onProgress: makeFetchProgressWriter()
+    });
+    for (const s of stats) {
+      const status = s.fetched > 0 ? `+${s.fetched} new` : `current (since ${s.newSince})`;
+      console.log(`${s.product.padEnd(35)} ${status}${s.latest ? `  latest: ${s.latest.split("T")[0]}` : ""}`);
+    }
+    if (program.opts().json) {
+      console.log(JSON.stringify({ stats, summary: stats.summary }));
+    } else {
+      printFetchSummary(stats.summary);
+    }
+    if (stats.summary.failed > 0 && stats.summary.succeeded > 0) {
+      process.exitCode = 3;
+    } else if (stats.summary.failed > 0 && stats.summary.succeeded === 0) {
+      process.exitCode = 2;
+    }
+  } finally {
+    db.close();
+  }
+});
+program.command("sync").description("Run fetch \u2192 ingest \u2192 embed in sequence (for daily cron / GH Action)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-r, --products-root <path>", "products dir", DEFAULT_PRODUCTS).option("--skip-fetch", "skip the fetch step (just ingest+embed existing files)").option("--skip-embed", "skip the embed step (fetch+ingest only)").addOption(
+  new Option("-c, --context <provider>", "context provider for embed").default("structured").choices([...CONTEXT_PROVIDERS])
+).addOption(
+  new Option("-e, --embed-provider <provider>", "embedding provider").default("ollama").choices([...EMBED_PROVIDERS])
+).action(
+  async (opts) => {
+    const db = openTrackedDb(opts.db);
+    initSchema(db);
+    const t0 = Date.now();
+    try {
+      if (!opts.skipFetch) {
+        process.stderr.write("=== fetch ===\n");
+        const stats = await fetchAll(db, opts.productsRoot, {
+          onProgress: makeFetchProgressWriter()
+        });
+        if (program.opts().json) {
+        } else {
+          printFetchSummary(stats.summary);
+        }
+      }
+      process.stderr.write("\n=== ingest ===\n");
+      const { ingestAll: ingestAll2 } = await import("./ingest-3LJNQWS7.js");
+      const ingestStats = ingestAll2(db, opts.productsRoot);
+      console.log(`ingested ${ingestStats.releasesAdded} releases, ${ingestStats.changesAdded} changes, ${ingestStats.entitiesAdded} entities`);
+      if (!opts.skipEmbed) {
+        process.stderr.write("\n=== embed ===\n");
+        const embedStats = await embedAll(db, {
+          contextProviderName: opts.context,
+          embeddingProviderName: opts.embedProvider,
+          onProgress: (p) => {
+            const prov = p.provider ? ` [${p.provider}]` : "";
+            const tokens = p.tokensUsed != null ? ` ${fmtNum(p.tokensUsed)} tokens` : "";
+            const reqs = p.requestsMade != null ? ` ${p.requestsMade} reqs` : "";
+            process.stderr.write(`  Embedding batch ${p.batchesCompleted}/${p.batchesTotal} (${p.chunksCompleted}/${p.chunksTotal} chunks)${prov}${tokens}${reqs}
+`);
+          }
+        });
+        console.log(`embedded ${embedStats.chunksCreated} new chunks via ${embedStats.contextProvider} + ${embedStats.embeddingProvider}`);
+      }
+      console.log(`
+\u2713 sync complete in ${Date.now() - t0}ms`);
+    } catch (e) {
+      const appErr = new AppError({
+        code: "SYNC_FAILED",
+        message: `sync failed: ${e.message}`,
+        hint: "Check network connectivity and API credentials. Re-run with --verbose for details.",
+        cause: e.message,
+        retryable: true
+      });
+      if (program.opts().json) {
+        console.log(JSON.stringify(appErr.toJSON()));
+      } else {
+        console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+      }
+      process.exit(2);
+    } finally {
+      db.close();
+    }
+  }
+);
+program.command("embed").description("Generate contextual chunks + embeddings (Tier 2b \u2014 opt-in semantic layer)").option("-d, --db <path>", "database path", DEFAULT_DB).addOption(
+  new Option("-c, --context <provider>", "context provider").default("structured").choices([...CONTEXT_PROVIDERS])
+).addOption(
+  new Option("-e, --embed <provider>", "embedding provider").default("ollama").choices([...EMBED_PROVIDERS])
+).option("-p, --product <name>", "limit to one product").option("-l, --limit <n>", "embed at most N pending chunks (testing)").option("--batch-size <n>", "embedding batch size", "64").option("--force", "recompute even if chunk already exists").action(
+  async (opts) => {
+    const db = openTrackedDb(opts.db);
+    try {
+      const stats = await embedAll(db, {
+        contextProviderName: opts.context,
+        embeddingProviderName: opts.embed,
+        product: opts.product,
+        limit: opts.limit !== void 0 ? intOpt("limit", opts.limit, 1) : void 0,
+        batchSize: intOpt("batch-size", opts.batchSize, 64),
+        force: opts.force,
+        onProgress: (p) => {
+          const prov = p.provider ? ` [${p.provider}]` : "";
+          const tokens = p.tokensUsed != null ? ` ${fmtNum(p.tokensUsed)} tokens` : "";
+          const reqs = p.requestsMade != null ? ` ${p.requestsMade} reqs` : "";
+          process.stderr.write(`Embedding batch ${p.batchesCompleted}/${p.batchesTotal} (${p.chunksCompleted}/${p.chunksTotal} chunks)${prov}${tokens}${reqs}
+`);
+        }
+      });
+      console.log(`\u2713 embedded ${stats.chunksCreated} chunks in ${stats.totalMs}ms`);
+      console.log(`  context provider: ${stats.contextProvider} (${stats.contextMs}ms total)`);
+      console.log(`  embedding model:  ${stats.embeddingProvider} (${stats.embedMs}ms total)`);
+      if (stats.chunksCreated === 0) {
+        console.log(`  (nothing to do \u2014 all changes already embedded; use --force to re-embed)`);
+      }
+    } catch (e) {
+      const hint = e.message.includes("Ollama") || e.message.includes("11434") ? "start Ollama with 'ollama serve' and pull the model: 'ollama pull nomic-embed-text'" : "Check provider connectivity. Re-run with --verbose for details.";
+      const appErr = new AppError({
+        code: "EMBED_FAILED",
+        message: `embed failed: ${e.message}`,
+        hint,
+        cause: e.message,
+        retryable: true
+      });
+      if (program.opts().json) {
+        console.log(JSON.stringify(appErr.toJSON()));
+      } else {
+        console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+      }
+      process.exit(2);
+    } finally {
+      db.close();
+    }
+  }
+);
+program.command("hybrid <text>").description("Hybrid FTS5 + sqlite-vec search via RRF, optional rerank (requires `hk embed` first)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "YYYY-MM-DD lower bound").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").addOption(
+  new Option("-e, --embed <provider>", "embedding provider for query").default("ollama").choices([...EMBED_PROVIDERS])
+).addOption(
+  new Option("-r, --rerank <provider>", "rerank provider").default("none").choices([...RERANK_PROVIDERS])
+).option("-l, --limit <n>", "max results", "10").option("--top-k <n>", "per-channel pull before fusion", "60").option("--rerank-candidates <n>", "how many RRF candidates to rerank", "20").action(
+  async (text, opts) => {
+    const db = openTrackedDb(opts.db);
+    try {
+      const t0 = Date.now();
+      const results = await hybridSearch(db, text, {
+        product: opts.product,
+        since: opts.since,
+        kind: opts.kind,
+        embedProviderName: opts.embed,
+        rerankProviderName: opts.rerank,
+        limit: intOpt("limit", opts.limit, 10),
+        topK: intOpt("top-k", opts.topK, 60),
+        rerankCandidates: intOpt("rerank-candidates", opts.rerankCandidates, 20)
+      });
+      const ms = Date.now() - t0;
+      if (program.opts().json) {
+        console.log(JSON.stringify(results.map((r) => ({
+          released_at: r.released_at,
+          product: r.product,
+          version: r.version,
+          kind: r.kind,
+          text: r.text,
+          rrf_score: r.rrf_score,
+          rerank_score: r.rerank_score
+        }))));
+      } else if (results.length === 0) {
+        console.log("(no results)");
+      } else {
+        for (const r of results) {
+          const bm = r.bm25_rank ? `bm25#${r.bm25_rank}` : "       ";
+          const vec = r.vec_rank ? `vec#${r.vec_rank}` : "      ";
+          const rerank = r.rerank_score !== null ? ` rerank=${r.rerank_score.toFixed(2)}` : "";
+          console.log(`${r.released_at ?? "????-??-??"}  ${r.product}@${r.version}  [${r.kind}]  ${bm} ${vec} rrf=${r.rrf_score.toFixed(4)}${rerank}`);
+          console.log(`  ${r.text.slice(0, 200)}${r.text.length > 200 ? "\u2026" : ""}`);
+        }
+        console.log(`
+${results.length} result${results.length === 1 ? "" : "s"} in ${ms}ms (rerank: ${opts.rerank})`);
+      }
+    } catch (e) {
+      const hint = e.message.includes("Ollama") || e.message.includes("11434") ? "start Ollama and pull the embedding model (and rerank model if using ollama-judge)" : "Check provider connectivity. Re-run with --verbose for details.";
+      const appErr = new AppError({
+        code: "HYBRID_QUERY_FAILED",
+        message: `hybrid query failed: ${e.message}`,
+        hint,
+        cause: e.message,
+        retryable: true
+      });
+      if (program.opts().json) {
+        console.log(JSON.stringify(appErr.toJSON()));
+      } else {
+        console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+      }
+      process.exit(2);
+    } finally {
+      db.close();
+    }
+  }
+);
+program.command("latest").description("Recent releases across all products (or one)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-l, --limit <n>", "max results", "20").action((opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const releases = recentReleases(db, opts.product, intOpt("limit", opts.limit, 20));
+  if (program.opts().json) {
+    console.log(JSON.stringify(releases));
+  } else if (releases.length === 0) {
+    console.log("(no releases)");
+  } else {
+    for (const r of releases) {
+      console.log(`${r.released_at}  ${r.product}@${r.version}  (${r.change_count} change${r.change_count === 1 ? "" : "s"})`);
+    }
+  }
+  db.close();
+});
+program.command("products").description("List all products in the DB with release counts").option("-d, --db <path>", "database path", DEFAULT_DB).action((opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const products = listProducts(db);
+  if (program.opts().json) {
+    console.log(JSON.stringify(products));
+  } else if (products.length === 0) {
+    console.log("(no products)");
+  } else {
+    console.log("Product                              Releases  Latest");
+    console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    for (const p of products) {
+      const latest = p.latest_version ? `${p.latest_version} (${p.latest_date})` : "\u2014";
+      console.log(`${p.name.padEnd(36)} ${String(p.release_count).padStart(8)}  ${latest}`);
+    }
+  }
+  db.close();
+});
+program.command("top <entity-type>").description("Most-mentioned entities of a type (env_var, slash_command, cli_option, model_id, beta_header, cve, ghsa, hook_event, setting_key)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-l, --limit <n>", "max results", "30").action((entityType, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const results = entityFrequency(db, entityType, intOpt("limit", opts.limit, 30));
+  if (program.opts().json) {
+    console.log(JSON.stringify(results));
+  } else if (results.length === 0) {
+    console.log(`(no entities of type "${entityType}")`);
+  } else {
+    for (const r of results) {
+      console.log(`${String(r.count).padStart(4)}  ${r.first_seen ?? "????-??-??"}  ${r.value}`);
+    }
+  }
+  db.close();
+});
+function printEntityResults(name, label, results) {
+  if (results.length === 0) {
+    console.log(`(${label} not found: ${name})`);
+    return;
+  }
+  console.log(`${label} ${name} \u2014 ${results.length} mention${results.length === 1 ? "" : "s"}:
+`);
+  for (const r of results) {
+    console.log(`${r.released_at ?? "????-??-??"}  ${r.product}@${r.version}  [${r.kind}]`);
+    console.log(`  ${r.text}`);
+  }
+}
+program.parseAsync(process.argv).catch((e) => {
+  console.error(formatError(e, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+  if (activeDb) {
+    try {
+      activeDb.close();
+    } catch {
+    }
+    activeDb = null;
+  }
+  process.exitCode = 2;
+});