lurqrun 0.0.2 → 0.0.4

package/dist/index.js

@@ -77,7 +77,7 @@ var init_constants = __esm({
     init_esm_shims();
     SERVER_NAME = "lurq";
     PACKAGE_NAME = "lurqrun";
-    VERSION = "0.0.2";
+    VERSION = "0.0.4";
     DEFAULT_ENDPOINT = "https://api.lurq.run/mcp";
     API_KEY_PREFIX = "lurq_live_";
     EMBEDDING_DIM = 1536;
@@ -145,12 +145,18 @@ var init_config = __esm({
     EnvSchema = z.object({
       DATABASE_URL: z.string().min(1).optional(),
       GITHUB_TOKEN: z.string().min(1).optional(),
+      // 'openai' here means "OpenAI-compatible" — any provider exposing /v1/embeddings
+      // + Bearer auth (OpenAI, Together, Fireworks, HF TEI, …). Point *_BASE_URL at it.
       EMBEDDING_PROVIDER: z.enum(["openai", "local"]).default("openai"),
       EMBEDDING_API_KEY: z.string().min(1).optional(),
       EMBEDDING_MODEL: z.string().min(1).default("text-embedding-3-small"),
+      EMBEDDING_BASE_URL: z.string().url().default("https://api.openai.com/v1"),
+      // 'openai' means "OpenAI-compatible /v1/chat/completions": OpenAI, Groq, Together,
+      // Fireworks, xAI (Grok), etc. Swap provider by setting SUMMARY_BASE_URL + key + model.
       SUMMARY_PROVIDER: z.enum(["openai", "none"]).default("openai"),
       SUMMARY_API_KEY: z.string().min(1).optional(),
       SUMMARY_MODEL: z.string().min(1).default("gpt-4o-mini"),
+      SUMMARY_BASE_URL: z.string().url().default("https://api.openai.com/v1"),
       LURQ_SYNC_CONCURRENCY: z.coerce.number().int().positive().max(50).default(5),
       LOG_LEVEL: z.enum(["error", "warn", "info", "debug"]).default("info"),
       // Hosted HTTP service (`serve-http`). Server-side only.
@@ -161,9 +167,22 @@ var init_config = __esm({
       LURQ_IP_RATE_LIMIT_MAX: z.coerce.number().int().positive().default(240),
       /** Rate-limit window, milliseconds (applies to both limiters). */
       LURQ_RATE_LIMIT_WINDOW_MS: z.coerce.number().int().positive().default(6e4),
+      /** Bearer token guarding `/metrics`. Unset → the endpoint is disabled (404). */
+      LURQ_METRICS_TOKEN: z.string().min(1).optional(),
+      /** Shared secret for self-serve key issuance (`POST /keys`). The Clerk-
+       *  authenticated web app presents it to mint a key for a signed-in user. Unset
+       *  → the endpoint is disabled (404). Keep it server-side, never in the client. */
+      LURQ_ISSUER_SECRET: z.string().min(1).optional(),
       // Client-side (install wizard / CLI talking to a remote endpoint).
       LURQ_ENDPOINT: z.string().url().optional(),
-      LURQ_API_KEY: z.string().min(1).optional()
+      LURQ_API_KEY: z.string().min(1).optional(),
+      // Sandbox verification. With E2B_API_KEY set, package install + smoke-load
+      // runs in an isolated E2B cloud sandbox (safe for UNTRUSTED packages);
+      // without it, the local child-process driver is used (trusted packages only).
+      E2B_API_KEY: z.string().min(1).optional(),
+      // E2B template to launch. Must provide node + npm on PATH; omit for E2B's
+      // default. Provision a Node-versioned template here for reproducible runs.
+      E2B_TEMPLATE: z.string().min(1).optional()
     });
     ConfigError = class extends Error {
       constructor(message) {
@@ -213,10 +232,15 @@ var init_logger = __esm({
 var schema_exports = {};
 __export(schema_exports, {
   apiKeys: () => apiKeys,
+  compatEdges: () => compatEdges,
   discoveryQueue: () => discoveryQueue,
+  packageVersions: () => packageVersions,
   packages: () => packages,
+  recommendationOutcomes: () => recommendationOutcomes,
   seedPackages: () => seedPackages,
-  syncRuns: () => syncRuns
+  syncRuns: () => syncRuns,
+  verificationRuns: () => verificationRuns,
+  watchState: () => watchState
 });
 import { sql } from "drizzle-orm";
 import {
@@ -227,13 +251,15 @@ import {
   integer,
   jsonb,
   pgTable,
+  primaryKey,
   real,
   serial,
   text,
   timestamp,
+  uniqueIndex,
   vector
 } from "drizzle-orm/pg-core";
-var tsvector, ts, packages, syncRuns, seedPackages, discoveryQueue, apiKeys;
+var tsvector, ts, packages, syncRuns, seedPackages, discoveryQueue, apiKeys, packageVersions, watchState, verificationRuns, compatEdges, recommendationOutcomes;
 var init_schema = __esm({
   "src/db/schema.ts"() {
     "use strict";
@@ -270,7 +296,6 @@ var init_schema = __esm({
         // Adoption signals
         weeklyDownloads: bigint("weekly_downloads", { mode: "number" }),
         downloadGrowth90d: real("download_growth_90d"),
-        dependentsCount: integer("dependents_count"),
         stars: integer("stars"),
         openIssues: integer("open_issues"),
         closedIssues: integer("closed_issues"),
@@ -278,6 +303,11 @@ var init_schema = __esm({
         scorecard: real("scorecard"),
         bundleMinGzipKb: real("bundle_min_gzip_kb"),
         advisories: jsonb("advisories").$type(),
+        // Compatibility metadata (Tier-1): declared peer-deps + engines of the
+        // latest version, so a whole-stack peer-range check is one indexed query.
+        peerDependencies: jsonb("peer_dependencies").$type(),
+        peerDependenciesMeta: jsonb("peer_dependencies_meta").$type(),
+        engines: jsonb("engines").$type(),
         // Computed outputs
         healthScore: integer("health_score"),
         /** Intrinsic-quality axis (§1), adoption-independent. Blends with health at
@@ -287,6 +317,10 @@ var init_schema = __esm({
         scoreBreakdown: jsonb("score_breakdown").$type(),
         usageGuide: jsonb("usage_guide").$type(),
         embedding: vector("embedding", { dimensions: EMBEDDING_DIM }),
+        // Identity of the vector space `embedding` was produced in (e.g.
+        // `openai:text-embedding-3-small`, `local`). Vector search filters on the
+        // active provider so switching models can't compare incompatible spaces.
+        embeddingProvider: text("embedding_provider"),
         // Lexical search vector (§3): name weighted highest (A), then category (B),
         // then summary/description (C). Generated + STORED so it stays in sync with
         // the row automatically; indexed with GIN for fast `@@` matching.
@@ -353,6 +387,83 @@ var init_schema = __esm({
       },
       (table2) => [index("api_keys_owner_idx").on(table2.ownerId)]
     );
+    packageVersions = pgTable(
+      "package_versions",
+      {
+        packageName: text("package_name").notNull(),
+        version: text("version").notNull(),
+        publishedAt: ts("published_at")
+      },
+      (table2) => [
+        primaryKey({ columns: [table2.packageName, table2.version] }),
+        index("package_versions_name_published_idx").on(table2.packageName, table2.publishedAt)
+      ]
+    );
+    watchState = pgTable("watch_state", {
+      id: text("id").primaryKey(),
+      seq: text("seq").notNull(),
+      updatedAt: ts("updated_at")
+    });
+    verificationRuns = pgTable(
+      "verification_runs",
+      {
+        id: serial("id").primaryKey(),
+        packageName: text("package_name").notNull(),
+        version: text("version").notNull(),
+        driver: text("driver").notNull(),
+        moduleSystem: text("module_system").notNull(),
+        installed: boolean("installed").notNull(),
+        imported: boolean("imported"),
+        ranScripts: boolean("ran_scripts").notNull().default(false),
+        durationMs: integer("duration_ms"),
+        error: text("error"),
+        ranAt: ts("ran_at")
+      },
+      (table2) => [index("verification_runs_pkg_idx").on(table2.packageName, table2.version)]
+    );
+    compatEdges = pgTable(
+      "compat_edges",
+      {
+        id: serial("id").primaryKey(),
+        packageA: text("package_a").notNull(),
+        versionA: text("version_a").notNull(),
+        packageB: text("package_b").notNull(),
+        versionB: text("version_b").notNull(),
+        status: text("status").$type().notNull(),
+        driver: text("driver").notNull(),
+        ranAt: ts("ran_at")
+      },
+      (table2) => [
+        uniqueIndex("compat_edges_pair_idx").on(
+          table2.packageA,
+          table2.versionA,
+          table2.packageB,
+          table2.versionB
+        )
+      ]
+    );
+    recommendationOutcomes = pgTable(
+      "recommendation_outcomes",
+      {
+        id: serial("id").primaryKey(),
+        /** The org this outcome belongs to (api_keys.owner_id). Null for anonymous /
+         *  operator-issued keys. This is what turns the flywheel from a global blob
+         *  into a per-org asset — "what did *this* org succeed with." Server-injected
+         *  from the authenticated key, never caller-supplied. */
+        ownerId: text("owner_id"),
+        packageName: text("package_name").notNull(),
+        accepted: boolean("accepted").notNull(),
+        buildSignal: text("build_signal").$type(),
+        /** The original need text the recommendation was for — ties outcome back to
+         *  the ask. Optional, length-capped at the trust boundary; never source code. */
+        need: text("need"),
+        createdAt: ts("created_at").notNull().defaultNow()
+      },
+      (table2) => [
+        index("recommendation_outcomes_pkg_idx").on(table2.packageName),
+        index("recommendation_outcomes_owner_idx").on(table2.ownerId)
+      ]
+    );
   }
 });
 
@@ -361,10 +472,10 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 function createDb(opts = {}) {
   const { DATABASE_URL } = requireConfig(["DATABASE_URL"]);
-  const sql8 = postgres(DATABASE_URL, { max: opts.max ?? 10, onnotice: () => {
+  const sql6 = postgres(DATABASE_URL, { max: opts.max ?? 10, onnotice: () => {
   } });
-  const db = drizzle(sql8, { schema: schema_exports });
-  return { db, sql: sql8, close: () => sql8.end() };
+  const db = drizzle(sql6, { schema: schema_exports });
+  return { db, sql: sql6, close: () => sql6.end() };
 }
 var init_client = __esm({
   "src/db/client.ts"() {
@@ -375,6 +486,131 @@ var init_client = __esm({
   }
 });
 
+// src/core/cache.ts
+var cache_exports = {};
+__export(cache_exports, {
+  cached: () => cached2,
+  invalidateCache: () => invalidateCache
+});
+function ttlSeconds() {
+  const n = Number(process.env.LURQ_CACHE_TTL_SEC);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_TTL_SEC;
+}
+async function getClient() {
+  if (!process.env.REDIS_URL) return null;
+  if (!clientPromise) {
+    clientPromise = (async () => {
+      try {
+        const { default: Redis } = await import("ioredis");
+        const client = new Redis(process.env.REDIS_URL, {
+          maxRetriesPerRequest: 1,
+          enableOfflineQueue: false,
+          lazyConnect: false,
+          // Railway's private network (redis.railway.internal) is IPv6-only and
+          // ioredis defaults to IPv4 — family:0 lets it resolve either stack, so
+          // both the private URL and a public/Upstash URL work unchanged.
+          family: 0
+        });
+        client.on("error", (err) => logger.warn(`redis: ${err.message}`));
+        logger.info("Response cache enabled (REDIS_URL set).");
+        return client;
+      } catch (err) {
+        logger.warn(`redis disabled (init failed): ${err.message}`);
+        return null;
+      }
+    })();
+  }
+  return clientPromise;
+}
+async function namespaceVersion(client) {
+  if (versionMemo && Date.now() - versionMemo.at < VERSION_MEMO_MS) return versionMemo.value;
+  const value = await client.get(VERSION_KEY).catch(() => null) ?? "0";
+  versionMemo = { value, at: Date.now() };
+  return value;
+}
+async function cached2(namespace, key, compute, opts = {}) {
+  const client = await getClient();
+  if (!client) return compute();
+  let fullKey;
+  try {
+    const version = await namespaceVersion(client);
+    fullKey = `lurq:${namespace}:${version}:${key}`;
+    const hit = await client.get(fullKey);
+    if (hit != null) return JSON.parse(hit);
+  } catch (err) {
+    logger.warn(`redis read failed, bypassing cache: ${err.message}`);
+    return compute();
+  }
+  const value = await compute();
+  if (!opts.skipCache?.(value)) {
+    client.set(fullKey, JSON.stringify(value), "EX", ttlSeconds()).catch(() => {
+    });
+  }
+  return value;
+}
+async function invalidateCache() {
+  const client = await getClient();
+  if (!client) return;
+  try {
+    await client.incr(VERSION_KEY);
+    versionMemo = null;
+  } catch (err) {
+    logger.warn(`redis invalidate failed: ${err.message}`);
+  }
+}
+var VERSION_KEY, DEFAULT_TTL_SEC, VERSION_MEMO_MS, clientPromise, versionMemo;
+var init_cache = __esm({
+  "src/core/cache.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_logger();
+    VERSION_KEY = "lurq:cachever";
+    DEFAULT_TTL_SEC = 3600;
+    VERSION_MEMO_MS = 1e4;
+    clientPromise = null;
+    versionMemo = null;
+  }
+});
+
+// src/db/compat.ts
+import { and, inArray } from "drizzle-orm";
+async function getCompatMetadata(db, names) {
+  if (names.length === 0) return [];
+  return db.select({
+    name: packages.name,
+    latestVersion: packages.latestVersion,
+    peerDependencies: packages.peerDependencies,
+    peerDependenciesMeta: packages.peerDependenciesMeta,
+    engines: packages.engines
+  }).from(packages).where(inArray(packages.name, names));
+}
+function canonicalPair(a, b) {
+  const [low, high] = a.name <= b.name ? [a, b] : [b, a];
+  return { packageA: low.name, versionA: low.version, packageB: high.name, versionB: high.version };
+}
+async function upsertCompatEdge(db, edge) {
+  await db.insert(compatEdges).values(edge).onConflictDoUpdate({
+    target: [
+      compatEdges.packageA,
+      compatEdges.versionA,
+      compatEdges.packageB,
+      compatEdges.versionB
+    ],
+    set: { status: edge.status, driver: edge.driver, ranAt: edge.ranAt }
+  });
+}
+async function getCompatEdges(db, names) {
+  if (names.length === 0) return [];
+  return db.select().from(compatEdges).where(and(inArray(compatEdges.packageA, names), inArray(compatEdges.packageB, names)));
+}
+var init_compat = __esm({
+  "src/db/compat.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
 // src/core/http.ts
 import { createHash } from "crypto";
 import { mkdir, readFile, writeFile } from "fs/promises";
@@ -439,9 +675,9 @@ async function httpRequest(url, opts) {
   } = opts;
   const key = opts.cacheKey ?? `${method} ${url} ${body ?? ""}`;
   if (ttlMs > 0 && !bypassCacheRead) {
-    const cached2 = await readCache(key, ttlMs);
-    if (cached2) {
-      return { status: cached2.status, data: decode(cached2.body, accept), fromCache: true };
+    const cached3 = await readCache(key, ttlMs);
+    if (cached3) {
+      return { status: cached3.status, data: decode(cached3.body, accept), fromCache: true };
     }
   }
   const limiter = limiterFor(host);
@@ -626,9 +862,45 @@ function parseNpmRegistry(json2) {
     hasTypes: detectTypes(name, latestManifest),
     hasTestScript: detectTestScript(latestManifest),
     directDependenciesCount: countDeps(latestManifest?.dependencies),
-    hasProvenance: detectProvenance(latestManifest)
+    hasProvenance: detectProvenance(latestManifest),
+    hasInstallScripts: detectInstallScripts(latestManifest),
+    peerDependencies: parseDepMap(latestManifest?.peerDependencies),
+    peerDependenciesMeta: parsePeerMeta(latestManifest?.peerDependenciesMeta),
+    engines: parseDepMap(latestManifest?.engines),
+    versionTimeline: parseVersionTimeline(json2)
   };
 }
+function parseDepMap(value) {
+  if (!value || typeof value !== "object") return null;
+  const out = {};
+  for (const [name, range] of Object.entries(value)) {
+    if (typeof range === "string" && range.trim() !== "") out[name] = range;
+  }
+  return Object.keys(out).length ? out : null;
+}
+function parsePeerMeta(value) {
+  if (!value || typeof value !== "object") return null;
+  const out = {};
+  for (const [name, meta] of Object.entries(value)) {
+    if (meta && typeof meta === "object" && "optional" in meta) {
+      out[name] = { optional: Boolean(meta.optional) };
+    }
+  }
+  return Object.keys(out).length ? out : null;
+}
+function detectInstallScripts(manifest) {
+  const scripts = manifest?.scripts;
+  if (!scripts || typeof scripts !== "object") return false;
+  return ["preinstall", "install", "postinstall"].some(
+    (hook) => typeof scripts[hook] === "string" && scripts[hook].trim() !== ""
+  );
+}
+function parseVersionTimeline(json2) {
+  const versions = json2?.versions;
+  if (!versions || typeof versions !== "object") return [];
+  const time = json2?.time ?? {};
+  return Object.keys(versions).map((version) => ({ version, publishedAt: toDate(time?.[version]) })).sort((a, b) => (b.publishedAt?.getTime() ?? 0) - (a.publishedAt?.getTime() ?? 0));
+}
 function parseKeywords(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((k) => typeof k === "string");
@@ -733,7 +1005,7 @@ function parseDownloadGrowth(json2) {
   const priorAvg = sum(prior) / prior.length;
   const recentAvg = sum(recent) / recent.length;
   if (priorAvg <= 0) return recentAvg > 0 ? 1 : 0;
-  return (recentAvg - priorAvg) / priorAvg;
+  return Math.round((recentAvg - priorAvg) / priorAvg * 1e3) / 1e3;
 }
 function ymd(date) {
   return date.toISOString().slice(0, 10);
@@ -1025,6 +1297,336 @@ var init_sources = __esm({
   }
 });
 
+// src/compat/members.ts
+async function assembleMembers(db, names) {
+  const tracked = new Map((await getCompatMetadata(db, names)).map((r) => [r.name, r]));
+  const members = [];
+  const unverified = [];
+  await Promise.all(
+    names.map(async (name) => {
+      const row = tracked.get(name);
+      if (row) {
+        members.push({
+          name,
+          version: row.latestVersion,
+          peerDependencies: row.peerDependencies,
+          peerDependenciesMeta: row.peerDependenciesMeta,
+          engines: row.engines
+        });
+        return;
+      }
+      const reg = await fetchNpmRegistry(name).catch(() => null);
+      if (reg) {
+        members.push({
+          name,
+          version: reg.latestVersion,
+          peerDependencies: reg.peerDependencies,
+          peerDependenciesMeta: reg.peerDependenciesMeta,
+          engines: reg.engines
+        });
+      } else {
+        unverified.push(name);
+      }
+    })
+  );
+  return { members, unverified };
+}
+var init_members = __esm({
+  "src/compat/members.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_compat();
+    init_sources();
+  }
+});
+
+// src/compat/peerCompat.ts
+import semver from "semver";
+function satisfiesRange(version, range) {
+  if (!semver.validRange(range)) return null;
+  const v = semver.valid(version) ? version : semver.coerce(version)?.version;
+  if (!v) return null;
+  return semver.satisfies(v, range, { includePrerelease: true });
+}
+function rangesIntersect(a, b) {
+  if (!semver.validRange(a) || !semver.validRange(b)) return null;
+  try {
+    return semver.intersects(a, b, { includePrerelease: true });
+  } catch {
+    return null;
+  }
+}
+function resolveArchitectureCompat(members) {
+  const conflicts = [];
+  const pinned = /* @__PURE__ */ new Map();
+  for (const m of members) if (m.version) pinned.set(m.name, m.version);
+  const constraints = [];
+  for (const m of members) {
+    if (!m.peerDependencies) continue;
+    for (const [peer, range] of Object.entries(m.peerDependencies)) {
+      constraints.push({
+        requirer: m.name,
+        peer,
+        range,
+        optional: Boolean(m.peerDependenciesMeta?.[peer]?.optional)
+      });
+    }
+  }
+  for (const c of constraints) {
+    const pv = pinned.get(c.peer);
+    if (pv && satisfiesRange(pv, c.range) === false) {
+      conflicts.push({
+        source: "peer-deps",
+        packages: [c.requirer, c.peer],
+        detail: `${c.requirer} needs peer ${c.peer}@${c.range}, but the stack uses ${c.peer}@${pv}`
+      });
+    }
+  }
+  const byPeer = /* @__PURE__ */ new Map();
+  for (const c of constraints) {
+    if (pinned.has(c.peer) || c.optional) continue;
+    const arr = byPeer.get(c.peer);
+    if (arr) arr.push(c);
+    else byPeer.set(c.peer, [c]);
+  }
+  for (const [peer, cs] of byPeer) {
+    for (let i = 0; i < cs.length; i++) {
+      for (let j = i + 1; j < cs.length; j++) {
+        if (cs[i].range !== cs[j].range && rangesIntersect(cs[i].range, cs[j].range) === false) {
+          conflicts.push({
+            source: "peer-deps",
+            packages: [cs[i].requirer, cs[j].requirer],
+            detail: `${cs[i].requirer} needs ${peer}@${cs[i].range} but ${cs[j].requirer} needs ${peer}@${cs[j].range} \u2014 no overlapping version`
+          });
+        }
+      }
+    }
+  }
+  const nodeReqs = members.map((m) => ({ name: m.name, range: m.engines?.node })).filter((r) => typeof r.range === "string");
+  for (let i = 0; i < nodeReqs.length; i++) {
+    for (let j = i + 1; j < nodeReqs.length; j++) {
+      if (rangesIntersect(nodeReqs[i].range, nodeReqs[j].range) === false) {
+        conflicts.push({
+          source: "engines",
+          packages: [nodeReqs[i].name, nodeReqs[j].name],
+          detail: `${nodeReqs[i].name} needs node ${nodeReqs[i].range} but ${nodeReqs[j].name} needs node ${nodeReqs[j].range} \u2014 no overlap`
+        });
+      }
+    }
+  }
+  return conflicts;
+}
+var init_peerCompat = __esm({
+  "src/compat/peerCompat.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
+// src/compat/check.ts
+async function checkCompat(db, packages2) {
+  const names = [...new Set(packages2)];
+  const { members, unverified } = await assembleMembers(db, names);
+  const conflicts = resolveArchitectureCompat(members);
+  for (const edge of await getCompatEdges(db, names)) {
+    if (edge.status === "conflict") {
+      conflicts.push({
+        source: "sandbox",
+        packages: [edge.packageA, edge.packageB],
+        detail: `${edge.packageA}@${edge.versionA} and ${edge.packageB}@${edge.versionB} failed to co-install in the sandbox`
+      });
+    }
+  }
+  const overall = conflicts.length ? "conflict" : unverified.length ? "unknown" : "compatible";
+  return {
+    packages: names,
+    overall,
+    conflicts,
+    unverified,
+    checked: members.map((m) => ({ name: m.name, version: m.version }))
+  };
+}
+var init_check = __esm({
+  "src/compat/check.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_compat();
+    init_members();
+    init_peerCompat();
+  }
+});
+
+// src/db/packages.ts
+import { desc, eq, isNotNull } from "drizzle-orm";
+async function getSeedTargets(db) {
+  const rows = await db.select({ name: seedPackages.name, category: seedPackages.category }).from(seedPackages);
+  return rows.map((r) => ({ name: r.name, category: r.category ?? null }));
+}
+async function getPackageByName(db, name) {
+  const rows = await db.select().from(packages).where(eq(packages.name, name)).limit(1);
+  return rows[0] ?? null;
+}
+async function getAllPackageNames(db) {
+  const rows = await db.select({ name: packages.name }).from(packages);
+  return rows.map((r) => r.name);
+}
+async function upsertPackageVersions(db, name, versions) {
+  if (versions.length === 0) return;
+  for (let i = 0; i < versions.length; i += VERSION_CHUNK) {
+    const rows = versions.slice(i, i + VERSION_CHUNK).map((v) => ({
+      packageName: name,
+      version: v.version,
+      publishedAt: v.publishedAt
+    }));
+    await db.insert(packageVersions).values(rows).onConflictDoNothing();
+  }
+}
+async function getPackageVersions(db, name, limit = 50) {
+  const rows = await db.select({ version: packageVersions.version, publishedAt: packageVersions.publishedAt }).from(packageVersions).where(eq(packageVersions.packageName, name)).orderBy(desc(packageVersions.publishedAt)).limit(limit);
+  return rows.map((r) => ({ version: r.version, publishedAt: r.publishedAt }));
+}
+async function getTopPackageNames(db, limit = 1e3) {
+  const rows = await db.select({ name: packages.name }).from(packages).where(isNotNull(packages.weeklyDownloads)).orderBy(desc(packages.weeklyDownloads)).limit(limit);
+  return rows.map((r) => r.name);
+}
+async function ensureSeedEntry(db, name, category) {
+  await db.insert(seedPackages).values({ name, category }).onConflictDoNothing({ target: seedPackages.name });
+}
+async function upsertPackage(db, row) {
+  const { name: _name, createdAt: _createdAt, ...mutable } = row;
+  await db.insert(packages).values(row).onConflictDoUpdate({
+    target: packages.name,
+    set: { ...mutable, updatedAt: /* @__PURE__ */ new Date() }
+  });
+}
+async function startSyncRun(db) {
+  const [row] = await db.insert(syncRuns).values({ status: "running" }).returning({ id: syncRuns.id });
+  return row.id;
+}
+async function finishSyncRun(db, id, data) {
+  await db.update(syncRuns).set({
+    finishedAt: /* @__PURE__ */ new Date(),
+    packagesSeen: data.packagesSeen,
+    packagesUpdated: data.packagesUpdated,
+    errors: data.errors,
+    status: data.status
+  }).where(eq(syncRuns.id, id));
+}
+var VERSION_CHUNK;
+var init_packages = __esm({
+  "src/db/packages.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+    VERSION_CHUNK = 500;
+  }
+});
+
+// src/db/verification.ts
+import { and as and2, desc as desc2, eq as eq2 } from "drizzle-orm";
+async function storeVerificationRun(db, run) {
+  await db.insert(verificationRuns).values(run);
+}
+async function getLatestVerificationByName(db, packageName) {
+  const rows = await db.select().from(verificationRuns).where(eq2(verificationRuns.packageName, packageName)).orderBy(desc2(verificationRuns.ranAt)).limit(1);
+  return rows[0] ?? null;
+}
+var init_verification = __esm({
+  "src/db/verification.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
+// src/db/outcomes.ts
+async function recordOutcome(db, outcome) {
+  await db.insert(recommendationOutcomes).values(outcome);
+}
+var init_outcomes = __esm({
+  "src/db/outcomes.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
+// src/data/successors.json
+var successors_default;
+var init_successors = __esm({
+  "src/data/successors.json"() {
+    successors_default = {
+      moment: {
+        replacedBy: "dayjs",
+        reason: "In maintenance mode since 2020 (the maintainers recommend alternatives). dayjs is a ~2KB immutable library with a near-identical API."
+      },
+      request: {
+        replacedBy: "got",
+        reason: "Deprecated in 2020 and no longer maintained. Use the built-in fetch, or got for a full-featured HTTP client."
+      },
+      "request-promise": {
+        replacedBy: "got",
+        reason: "Deprecated alongside request. got returns promises natively."
+      },
+      "node-sass": {
+        replacedBy: "sass",
+        reason: "Deprecated; bindings break on new Node versions. sass is the Dart implementation (sass-embedded for speed)."
+      },
+      tslint: {
+        replacedBy: "typescript-eslint",
+        reason: "Deprecated in 2019 in favor of ESLint. Use typescript-eslint to lint TypeScript."
+      },
+      enzyme: {
+        replacedBy: "@testing-library/react",
+        reason: "Unmaintained with no official React 17+/18 adapter. React Testing Library is the current standard."
+      },
+      protractor: {
+        replacedBy: "@playwright/test",
+        reason: "Reached end-of-life in 2023. Use Playwright (or Cypress) for browser E2E."
+      },
+      faker: {
+        replacedBy: "@faker-js/faker",
+        reason: "The original package was sabotaged and deprecated. @faker-js/faker is the community-maintained fork."
+      },
+      bower: {
+        replacedBy: "npm",
+        reason: "Deprecated; front-end packages ship on npm now. Use npm (or your package manager) directly."
+      },
+      "popper.js": {
+        replacedBy: "@popperjs/core",
+        reason: "v1 is deprecated. @popperjs/core is the maintained v2 line."
+      },
+      "create-react-app": {
+        replacedBy: "vite",
+        reason: "No longer recommended by the React team and effectively unmaintained. Vite is the current scaffolding standard."
+      },
+      "babel-eslint": {
+        replacedBy: "@babel/eslint-parser",
+        reason: "Deprecated and renamed. Use @babel/eslint-parser."
+      },
+      istanbul: {
+        replacedBy: "nyc",
+        reason: "The istanbul package is legacy; nyc is its maintained CLI (or c8 for native V8 coverage)."
+      }
+    };
+  }
+});
+
+// src/core/successors.ts
+function lookupSuccessor(name) {
+  const hit = MAP[name.toLowerCase()];
+  return hit ? { name: hit.replacedBy, reason: hit.reason } : null;
+}
+var MAP;
+var init_successors2 = __esm({
+  "src/core/successors.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_successors();
+    MAP = successors_default;
+  }
+});
+
 // src/ingestion/sources/githubReadme.ts
 async function fetchGithubReadme(owner, repo, fetchImpl) {
   for (const file of CANDIDATES) {
@@ -1091,7 +1693,12 @@ function str(value) {
 function createSummaryProvider(fetchImpl) {
   const config = getConfig();
   if (config.SUMMARY_PROVIDER === "openai" && config.SUMMARY_API_KEY) {
-    return new OpenAISummaryProvider(config.SUMMARY_API_KEY, config.SUMMARY_MODEL, fetchImpl);
+    return new OpenAISummaryProvider(
+      config.SUMMARY_API_KEY,
+      config.SUMMARY_MODEL,
+      config.SUMMARY_BASE_URL,
+      fetchImpl
+    );
   }
   return new FallbackSummaryProvider();
 }
@@ -1163,15 +1770,19 @@ var init_summarize = __esm({
     };
     SYSTEM_PROMPT = "You summarize npm packages factually for an AI coding agent choosing dependencies. Use ONLY the provided README/description. Never invent capabilities or APIs. Be concise and concrete. Respond with a JSON object.";
     OpenAISummaryProvider = class {
-      constructor(apiKey, model, fetchImpl) {
+      constructor(apiKey, model, baseUrl, fetchImpl) {
         this.apiKey = apiKey;
         this.model = model;
         this.fetchImpl = fetchImpl;
+        this.endpoint = `${baseUrl.replace(/\/$/, "")}/chat/completions`;
+        this.host = new URL(baseUrl).host;
       }
       apiKey;
       model;
       fetchImpl;
       kind = "openai";
+      endpoint;
+      host;
       async generate(input) {
         try {
           const body = JSON.stringify({
@@ -1183,8 +1794,8 @@ var init_summarize = __esm({
             response_format: { type: "json_object" },
             temperature: 0.2
           });
-          const { data } = await httpRequest("https://api.openai.com/v1/chat/completions", {
-            host: "api.openai.com",
+          const { data } = await httpRequest(this.endpoint, {
+            host: this.host,
             method: "POST",
             ttlMs: 30 * 24 * 60 * 60 * 1e3,
             // cache summaries 30d to control cost
@@ -1371,10 +1982,10 @@ function activeWeightsPath() {
 function loadWeights() {
   if (cachedWeights) return cachedWeights;
   let merged = structuredClone(DEFAULT_WEIGHTS);
-  const active = activeWeightsPath();
-  if (active) {
+  const active2 = activeWeightsPath();
+  if (active2) {
     try {
-      const fromFile = JSON.parse(readFileSync(active.path, "utf8"));
+      const fromFile = JSON.parse(readFileSync(active2.path, "utf8"));
       merged = mergeWeights(merged, fromFile);
     } catch {
     }
@@ -1422,10 +2033,10 @@ function settableKeys() {
 function applyOverrides(base, sets) {
   const next = structuredClone(base);
   for (const entry of sets) {
-    const eq7 = entry.indexOf("=");
-    if (eq7 < 0) throw new Error(`Invalid --set "${entry}" (expected key=value).`);
-    const key = entry.slice(0, eq7).trim();
-    const value = Number(entry.slice(eq7 + 1).trim());
+    const eq9 = entry.indexOf("=");
+    if (eq9 < 0) throw new Error(`Invalid --set "${entry}" (expected key=value).`);
+    const key = entry.slice(0, eq9).trim();
+    const value = Number(entry.slice(eq9 + 1).trim());
     const apply = SETTABLE[key];
     if (!apply) {
       throw new Error(`Unknown weight key "${key}". Settable: ${settableKeys().join(", ")}.`);
@@ -1589,8 +2200,6 @@ function toScoringInput(signals, category) {
     weeklyDownloads: downloads?.weeklyDownloads ?? null,
     downloadGrowth90d: downloads?.downloadGrowth90d ?? null,
     stars: github?.stars ?? null,
-    dependentsCount: null,
-    // not collected in v1 (see spec R1 note)
     firstPublishedAt: registry?.firstPublishedAt ?? null,
     lastReleaseAt: github?.lastReleaseAt ?? registry?.lastReleaseAt ?? null,
     releasesLast12mo: github?.releasesLast12mo ?? null,
@@ -1746,7 +2355,8 @@ function computeConfidence(input, now, qualityScore = null) {
   if (emergingAdoptionOk && emergingReleaseOk && !input.deprecated && !input.archived) {
     return "emerging";
   }
-  const promisingReleaseOk = lastReleaseMonths !== null && lastReleaseMonths <= CONFIDENCE.promising.maxLastReleaseMonths;
+  const promisingRecencyMonths = lastReleaseMonths ?? ageMonths;
+  const promisingReleaseOk = promisingRecencyMonths !== null && promisingRecencyMonths <= CONFIDENCE.promising.maxLastReleaseMonths;
   if (qualityScore !== null && qualityScore >= CONFIDENCE.promising.minQuality && promisingReleaseOk && !hasCriticalOrHighAdvisory(input.advisories) && !input.deprecated && !input.archived) {
     return "promising";
   }
@@ -1840,7 +2450,12 @@ function localEmbed(text2, dim2 = EMBEDDING_DIM) {
 function createEmbeddingProvider(fetchImpl) {
   const config = getConfig();
   if (config.EMBEDDING_PROVIDER === "openai" && config.EMBEDDING_API_KEY) {
-    return new OpenAIEmbeddingProvider(config.EMBEDDING_API_KEY, config.EMBEDDING_MODEL, fetchImpl);
+    return new OpenAIEmbeddingProvider(
+      config.EMBEDDING_API_KEY,
+      config.EMBEDDING_MODEL,
+      config.EMBEDDING_BASE_URL,
+      fetchImpl
+    );
   }
   if (config.EMBEDDING_PROVIDER === "openai" && !config.EMBEDDING_API_KEY) {
     logger.warn("EMBEDDING_API_KEY not set \u2014 falling back to the local embedder.");
@@ -1859,29 +2474,36 @@ var init_embeddings = __esm({
     LocalEmbeddingProvider = class {
       kind = "local";
       dimensions = EMBEDDING_DIM;
+      id = "local";
       async embed(texts) {
         return texts.map((t) => localEmbed(t));
       }
     };
     OPENAI_BATCH = 96;
     OpenAIEmbeddingProvider = class {
-      constructor(apiKey, model, fetchImpl) {
+      constructor(apiKey, model, baseUrl, fetchImpl) {
         this.apiKey = apiKey;
         this.model = model;
         this.fetchImpl = fetchImpl;
+        this.id = `openai:${model}`;
+        this.endpoint = `${baseUrl.replace(/\/$/, "")}/embeddings`;
+        this.host = new URL(baseUrl).host;
       }
       apiKey;
       model;
       fetchImpl;
       kind = "openai";
       dimensions = EMBEDDING_DIM;
+      id;
+      endpoint;
+      host;
       async embed(texts) {
         const out = [];
         for (let i = 0; i < texts.length; i += OPENAI_BATCH) {
           const batch = texts.slice(i, i + OPENAI_BATCH);
-          const body = JSON.stringify({ model: this.model, input: batch });
-          const { data } = await httpRequest("https://api.openai.com/v1/embeddings", {
-            host: "api.openai.com",
+          const body = JSON.stringify({ model: this.model, input: batch, dimensions: EMBEDDING_DIM });
+          const { data } = await httpRequest(this.endpoint, {
+            host: this.host,
             method: "POST",
             ttlMs: 30 * 24 * 60 * 60 * 1e3,
             // cache embeddings 30d to control cost
@@ -1892,7 +2514,14 @@ var init_embeddings = __esm({
           });
           const vectors = data?.data ?? [];
           vectors.sort((a, b) => a.index - b.index);
-          for (const v of vectors) out.push(v.embedding);
+          for (const v of vectors) {
+            if (v.embedding.length !== EMBEDDING_DIM) {
+              throw new Error(
+                `OpenAI model ${this.model} returned ${v.embedding.length}-dim vectors; expected ${EMBEDDING_DIM}. Set EMBEDDING_MODEL to a text-embedding-3 model or update EMBEDDING_DIM.`
+              );
+            }
+            out.push(v.embedding);
+          }
         }
         return out;
       }
@@ -1900,47 +2529,6 @@ var init_embeddings = __esm({
   }
 });
 
-// src/db/packages.ts
-import { eq, sql as sql2 } from "drizzle-orm";
-async function getSeedTargets(db) {
-  const rows = await db.select({ name: seedPackages.name, category: seedPackages.category }).from(seedPackages);
-  return rows.map((r) => ({ name: r.name, category: r.category ?? null }));
-}
-async function getPackageByName(db, name) {
-  const rows = await db.select().from(packages).where(eq(packages.name, name)).limit(1);
-  return rows[0] ?? null;
-}
-async function ensureSeedEntry(db, name, category) {
-  await db.insert(seedPackages).values({ name, category }).onConflictDoNothing({ target: seedPackages.name });
-}
-async function upsertPackage(db, row) {
-  const { name: _name, createdAt: _createdAt, ...mutable } = row;
-  await db.insert(packages).values(row).onConflictDoUpdate({
-    target: packages.name,
-    set: { ...mutable, updatedAt: /* @__PURE__ */ new Date() }
-  });
-}
-async function startSyncRun(db) {
-  const [row] = await db.insert(syncRuns).values({ status: "running" }).returning({ id: syncRuns.id });
-  return row.id;
-}
-async function finishSyncRun(db, id, data) {
-  await db.update(syncRuns).set({
-    finishedAt: /* @__PURE__ */ new Date(),
-    packagesSeen: data.packagesSeen,
-    packagesUpdated: data.packagesUpdated,
-    errors: data.errors,
-    status: data.status
-  }).where(eq(syncRuns.id, id));
-}
-var init_packages = __esm({
-  "src/db/packages.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_schema();
-  }
-});
-
 // src/core/concurrency.ts
 async function pMap(items, mapper, concurrency) {
   const results = new Array(items.length);
@@ -1970,6 +2558,11 @@ async function runSync(opts = {}) {
   const handle = createDb({ max: Math.max(4, config.LURQ_SYNC_CONCURRENCY) });
   const provider = createSummaryProvider();
   logger.info(`Summary provider: ${provider.kind}`);
+  if (!config.GITHUB_TOKEN) {
+    logger.warn(
+      "GITHUB_TOKEN not set \u2014 GitHub signals (stars, issues, release cadence) will be skipped, degrading maintenance/adoption scores. Set it for accurate scoring."
+    );
+  }
   const runId = await startSyncRun(handle.db);
   const allErrors = [];
   try {
@@ -2068,6 +2661,7 @@ async function runSync(opts = {}) {
           healthScore,
           qualityScore: c.quality,
           embedding: embeddings[i] ?? null,
+          embeddingProvider: embProvider.id,
           now
         })
       );
@@ -2081,6 +2675,7 @@ async function runSync(opts = {}) {
       status
     });
     logger.info(`Sync ${status}: ${updated}/${targets.length} updated, ${allErrors.length} source errors.`);
+    if (updated > 0) await invalidateCache();
     return { seen: targets.length, updated, errors: allErrors.length, status };
   } catch (err) {
     await finishSyncRun(handle.db, runId, {
@@ -2140,19 +2735,22 @@ function assemblePackageRow(p) {
     lastReleaseAt: p.input.lastReleaseAt,
     weeklyDownloads: p.input.weeklyDownloads,
     downloadGrowth90d: p.input.downloadGrowth90d,
-    dependentsCount: p.input.dependentsCount,
     stars: p.input.stars,
     openIssues: p.input.openIssues,
     closedIssues: p.input.closedIssues,
     scorecard: p.input.scorecard,
     bundleMinGzipKb: p.input.bundleMinGzipKb,
     advisories: p.input.advisories,
+    peerDependencies: r?.peerDependencies ?? null,
+    peerDependenciesMeta: r?.peerDependenciesMeta ?? null,
+    engines: r?.engines ?? null,
     healthScore: p.healthScore,
     qualityScore: p.qualityScore,
     confidence: p.confidence,
     scoreBreakdown: p.breakdown,
     usageGuide: p.usageGuide,
     embedding: p.embedding,
+    embeddingProvider: p.embedding ? p.embeddingProvider : null,
     dataAsOf: p.now
   };
 }
@@ -2160,6 +2758,7 @@ var init_sync = __esm({
   "src/pipeline/sync.ts"() {
     "use strict";
     init_esm_shims();
+    init_cache();
     init_config();
     init_concurrency();
     init_http();
@@ -2176,17 +2775,68 @@ var init_sync = __esm({
   }
 });
 
-// src/pipeline/single.ts
-import { and, eq as eq2, isNotNull, sql as sql3 } from "drizzle-orm";
-async function getSeedCategory(db, name) {
-  const [row] = await db.select({ category: seedPackages.category }).from(seedPackages).where(eq2(seedPackages.name, name)).limit(1);
-  return row?.category ?? null;
+// src/pipeline/ingestQueue.ts
+function enqueueIngest(db, name) {
+  if (queuedNames.has(name) || inFlight.has(name)) return;
+  if (pending.length >= MAX_PENDING) {
+    logger.warn(`ingest queue full (${MAX_PENDING}); dropping on-demand request for ${name}`);
+    return;
+  }
+  queuedNames.add(name);
+  pending.push(name);
+  pump(db);
+}
+function pump(db) {
+  while (active < MAX_CONCURRENT && pending.length > 0) {
+    const name = pending.shift();
+    queuedNames.delete(name);
+    inFlight.add(name);
+    active += 1;
+    void ingestOne(db, name).finally(() => {
+      inFlight.delete(name);
+      active -= 1;
+      pump(db);
+    });
+  }
 }
-async function getCategoryMedianBundle(db, category) {
-  const [row] = await db.select({
-    m: sql3`percentile_cont(0.5) within group (order by ${packages.bundleMinGzipKb})`
-  }).from(packages).where(and(eq2(packages.category, category), isNotNull(packages.bundleMinGzipKb)));
-  return row?.m ?? null;
+async function ingestOne(db, name) {
+  try {
+    const row = await syncOnePackage(db, name);
+    if (row.confidence && row.confidence !== "unproven") {
+      await ensureSeedEntry(db, name, row.category);
+    }
+  } catch (err) {
+    logger.warn(`on-demand ingest failed for ${name}: ${String(err)}`);
+  }
+}
+var MAX_CONCURRENT, MAX_PENDING, pending, inFlight, queuedNames, active;
+var init_ingestQueue = __esm({
+  "src/pipeline/ingestQueue.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_logger();
+    init_packages();
+    init_single();
+    MAX_CONCURRENT = 3;
+    MAX_PENDING = 500;
+    pending = [];
+    inFlight = /* @__PURE__ */ new Set();
+    queuedNames = /* @__PURE__ */ new Set();
+    active = 0;
+  }
+});
+
+// src/pipeline/single.ts
+import { and as and3, eq as eq3, isNotNull as isNotNull2, sql as sql2 } from "drizzle-orm";
+async function getSeedCategory(db, name) {
+  const [row] = await db.select({ category: seedPackages.category }).from(seedPackages).where(eq3(seedPackages.name, name)).limit(1);
+  return row?.category ?? null;
+}
+async function getCategoryMedianBundle(db, category) {
+  const [row] = await db.select({
+    m: sql2`percentile_cont(0.5) within group (order by ${packages.bundleMinGzipKb})`
+  }).from(packages).where(and3(eq3(packages.category, category), isNotNull2(packages.bundleMinGzipKb)));
+  return row?.m ?? null;
 }
 async function syncOnePackage(db, name, opts = {}) {
   const config = getConfig();
@@ -2225,7 +2875,8 @@ async function syncOnePackage(db, name, opts = {}) {
   };
   const healthScore = computeHealthScore(breakdown);
   const confidence = computeConfidence(input, now, quality);
-  const [embedding] = await createEmbeddingProvider().embed([
+  const embProvider = createEmbeddingProvider();
+  const [embedding] = await embProvider.embed([
     buildEmbeddingText({ name, category, summary, description: signals.registry?.description ?? null })
   ]);
   await upsertPackage(
@@ -2243,9 +2894,14 @@ async function syncOnePackage(db, name, opts = {}) {
       healthScore,
       qualityScore: quality,
       embedding: embedding ?? null,
+      embeddingProvider: embProvider.id,
       now
     })
   );
+  await upsertPackageVersions(db, name, signals.registry?.versionTimeline ?? []).catch(
+    () => {
+    }
+  );
   return await getPackageByName(db, name);
 }
 async function getOrFetchPackage(db, name) {
@@ -2253,9 +2909,8 @@ async function getOrFetchPackage(db, name) {
   if (existing) return { row: existing, wasTracked: true, existsOnNpm: true };
   const exists = await npmPackageExists(name);
   if (!exists) return { row: null, wasTracked: false, existsOnNpm: false };
-  const row = await syncOnePackage(db, name);
-  await ensureSeedEntry(db, name, row.category);
-  return { row, wasTracked: false, existsOnNpm: true };
+  enqueueIngest(db, name);
+  return { row: null, wasTracked: false, existsOnNpm: true, queued: true };
 }
 var init_single = __esm({
   "src/pipeline/single.ts"() {
@@ -2271,20 +2926,21 @@ var init_single = __esm({
     init_packages();
     init_schema();
     init_sync();
+    init_ingestQueue();
   }
 });
 
 // src/search/recommend.ts
-import { and as and2, cosineDistance, eq as eq3, isNotNull as isNotNull2, lte, sql as sql4 } from "drizzle-orm";
+import { and as and4, cosineDistance, eq as eq4, isNotNull as isNotNull3, lte, sql as sql3 } from "drizzle-orm";
 async function recommend(db, opts, provider = createEmbeddingProvider()) {
   const limit = Math.min(Math.max(opts.limit ?? 3, 1), 5);
   const [queryVec] = await provider.embed([opts.need]);
   if (!queryVec) return [];
   const category = opts.category ?? inferCategory(opts.need);
   const pool = Math.max(limit * 5, 25);
-  let fused = await hybridSearch(db, queryVec, opts.need, opts.constraints, category, pool);
+  let fused = await hybridSearch(db, queryVec, provider.id, opts.need, opts.constraints, category, pool);
   if (category && fused.length < limit) {
-    const broad = await hybridSearch(db, queryVec, opts.need, opts.constraints, null, pool);
+    const broad = await hybridSearch(db, queryVec, provider.id, opts.need, opts.constraints, null, pool);
     const seen = new Set(fused.map((f) => f.row.name));
     fused = fused.concat(broad.filter((f) => !seen.has(f.row.name)));
   }
@@ -2298,9 +2954,9 @@ async function recommend(db, opts, provider = createEmbeddingProvider()) {
   }).sort((a, b) => b.score - a.score).slice(0, limit);
   return ranked.map(({ row }) => toCandidate(row));
 }
-async function hybridSearch(db, queryVec, need, constraints, category, pool) {
+async function hybridSearch(db, queryVec, providerId, need, constraints, category, pool) {
   const [vectorRows, lexicalRows] = await Promise.all([
-    runVectorQuery(db, queryVec, constraints, category, pool),
+    runVectorQuery(db, queryVec, providerId, constraints, category, pool),
     runLexicalQuery(db, need, constraints, category, pool)
   ]);
   return rrfFuse([vectorRows, lexicalRows]);
@@ -2319,8 +2975,8 @@ function rrfFuse(lists, k = RRF_K) {
 }
 function buildConditions(constraints, category) {
   const conditions = [];
-  if (category) conditions.push(eq3(packages.category, category));
-  if (constraints?.license) conditions.push(eq3(packages.license, constraints.license));
+  if (category) conditions.push(eq4(packages.category, category));
+  if (constraints?.license) conditions.push(eq4(packages.license, constraints.license));
   if (constraints?.maxBundleKb !== void 0) {
     conditions.push(lte(packages.bundleMinGzipKb, constraints.maxBundleKb));
   }
@@ -2329,21 +2985,25 @@ function buildConditions(constraints, category) {
       (c) => CONFIDENCE_RANK[c] >= CONFIDENCE_RANK[constraints.minConfidence]
     );
     conditions.push(
-      sql4`${packages.confidence} in ${sql4.raw(`(${allowed.map((c) => `'${c}'`).join(",")})`)}`
+      sql3`${packages.confidence} in ${sql3.raw(`(${allowed.map((c) => `'${c}'`).join(",")})`)}`
     );
   }
   return conditions;
 }
-async function runVectorQuery(db, queryVec, constraints, category, pool) {
+async function runVectorQuery(db, queryVec, providerId, constraints, category, pool) {
   const distance = cosineDistance(packages.embedding, queryVec);
-  const conditions = [isNotNull2(packages.embedding), ...buildConditions(constraints, category)];
-  return db.select(ROW_COLUMNS).from(packages).where(and2(...conditions)).orderBy(distance).limit(pool);
+  const conditions = [
+    isNotNull3(packages.embedding),
+    eq4(packages.embeddingProvider, providerId),
+    ...buildConditions(constraints, category)
+  ];
+  return db.select(ROW_COLUMNS).from(packages).where(and4(...conditions)).orderBy(distance).limit(pool);
 }
 async function runLexicalQuery(db, need, constraints, category, pool) {
-  const tsquery = sql4`websearch_to_tsquery('english', ${need})`;
-  const rank = sql4`ts_rank(${packages.searchVector}, ${tsquery})`;
-  const conditions = [sql4`${packages.searchVector} @@ ${tsquery}`, ...buildConditions(constraints, category)];
-  return db.select(ROW_COLUMNS).from(packages).where(and2(...conditions)).orderBy(sql4`${rank} desc`).limit(pool);
+  const tsquery = sql3`websearch_to_tsquery('english', ${need})`;
+  const rank = sql3`ts_rank(${packages.searchVector}, ${tsquery})`;
+  const conditions = [sql3`${packages.searchVector} @@ ${tsquery}`, ...buildConditions(constraints, category)];
+  return db.select(ROW_COLUMNS).from(packages).where(and4(...conditions)).orderBy(sql3`${rank} desc`).limit(pool);
 }
 function toCandidate(row) {
   return {
@@ -2404,12 +3064,316 @@ var init_recommend = __esm({
   }
 });
 
+// src/security/risk.ts
+function assessRisk(i) {
+  const malwarePattern = i.installScripts && i.brandNew && i.lowTrust;
+  if (i.typosquat || i.hasCriticalOrHighAdvisory || malwarePattern) return "high";
+  if (i.deprecatedOrArchived || i.installScripts && (i.lowTrust || i.brandNew) || i.lowTrust && i.flags.includes("single-maintainer")) {
+    return "medium";
+  }
+  return "low";
+}
+var init_risk = __esm({
+  "src/security/risk.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
+// src/data/popular-packages.json
+var popular_packages_default;
+var init_popular_packages = __esm({
+  "src/data/popular-packages.json"() {
+    popular_packages_default = [
+      "react",
+      "react-dom",
+      "react-router",
+      "react-router-dom",
+      "next",
+      "vue",
+      "vue-router",
+      "pinia",
+      "vuex",
+      "svelte",
+      "solid-js",
+      "preact",
+      "angular",
+      "@angular/core",
+      "jquery",
+      "lodash",
+      "underscore",
+      "ramda",
+      "immer",
+      "rxjs",
+      "express",
+      "koa",
+      "fastify",
+      "@nestjs/core",
+      "hapi",
+      "connect",
+      "body-parser",
+      "cookie-parser",
+      "cors",
+      "helmet",
+      "morgan",
+      "compression",
+      "express-session",
+      "express-rate-limit",
+      "multer",
+      "passport",
+      "jsonwebtoken",
+      "bcrypt",
+      "bcryptjs",
+      "axios",
+      "node-fetch",
+      "got",
+      "undici",
+      "superagent",
+      "request",
+      "cheerio",
+      "puppeteer",
+      "playwright",
+      "cypress",
+      "jsdom",
+      "ws",
+      "socket.io",
+      "socket.io-client",
+      "graphql",
+      "@apollo/client",
+      "apollo-server",
+      "dataloader",
+      "mongoose",
+      "mongodb",
+      "pg",
+      "mysql2",
+      "sequelize",
+      "prisma",
+      "knex",
+      "drizzle-orm",
+      "typeorm",
+      "redis",
+      "ioredis",
+      "sqlite3",
+      "better-sqlite3",
+      "typescript",
+      "eslint",
+      "prettier",
+      "tslint",
+      "webpack",
+      "vite",
+      "rollup",
+      "esbuild",
+      "parcel",
+      "@babel/core",
+      "babel-core",
+      "babel-loader",
+      "ts-node",
+      "tsx",
+      "tsup",
+      "nodemon",
+      "concurrently",
+      "npm-run-all",
+      "jest",
+      "vitest",
+      "mocha",
+      "chai",
+      "sinon",
+      "ava",
+      "tape",
+      "supertest",
+      "@testing-library/react",
+      "enzyme",
+      "chalk",
+      "colors",
+      "kleur",
+      "picocolors",
+      "ansi-colors",
+      "commander",
+      "yargs",
+      "meow",
+      "minimist",
+      "inquirer",
+      "prompts",
+      "ora",
+      "boxen",
+      "figlet",
+      "cli-progress",
+      "debug",
+      "dotenv",
+      "cross-env",
+      "rimraf",
+      "glob",
+      "fast-glob",
+      "chokidar",
+      "fs-extra",
+      "execa",
+      "cross-spawn",
+      "shelljs",
+      "which",
+      "semver",
+      "uuid",
+      "nanoid",
+      "ulid",
+      "moment",
+      "dayjs",
+      "date-fns",
+      "luxon",
+      "zod",
+      "yup",
+      "joi",
+      "ajv",
+      "validator",
+      "class-validator",
+      "winston",
+      "pino",
+      "bunyan",
+      "nodemailer",
+      "node-cron",
+      "bull",
+      "bullmq",
+      "kafkajs",
+      "amqplib",
+      "sharp",
+      "jimp",
+      "archiver",
+      "tar",
+      "adm-zip",
+      "qs",
+      "query-string",
+      "form-data",
+      "mime-types",
+      "http-errors",
+      "classnames",
+      "clsx",
+      "styled-components",
+      "@emotion/react",
+      "tailwindcss",
+      "postcss",
+      "autoprefixer",
+      "sass",
+      "less",
+      "framer-motion",
+      "three",
+      "d3",
+      "chart.js",
+      "recharts",
+      "gsap",
+      "swiper",
+      "leaflet",
+      "mapbox-gl",
+      "formik",
+      "react-hook-form",
+      "redux",
+      "@reduxjs/toolkit",
+      "zustand",
+      "jotai",
+      "mobx",
+      "bootstrap",
+      "@popperjs/core",
+      "aws-sdk",
+      "@aws-sdk/client-s3",
+      "firebase",
+      "firebase-admin",
+      "stripe",
+      "twilio",
+      "openai",
+      "@anthropic-ai/sdk",
+      "googleapis",
+      "bignumber.js",
+      "decimal.js",
+      "mathjs",
+      "slugify",
+      "faker",
+      "@faker-js/faker",
+      "puppeteer-core"
+    ];
+  }
+});
+
+// src/security/typosquat.ts
+function typosquatCorpus(trackedTopNames) {
+  return [.../* @__PURE__ */ new Set([...POPULAR_BASELINE, ...trackedTopNames])];
+}
+function bareName(name) {
+  const slash = name.indexOf("/");
+  return (slash >= 0 ? name.slice(slash + 1) : name).toLowerCase();
+}
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prevPrev = new Array(n + 1).fill(0);
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const cur = new Array(n + 1).fill(0);
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let val = Math.min(
+        (prev[j] ?? 0) + 1,
+        (cur[j - 1] ?? 0) + 1,
+        (prev[j - 1] ?? 0) + cost
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        val = Math.min(val, (prevPrev[j - 2] ?? 0) + 1);
+      }
+      cur[j] = val;
+    }
+    prevPrev = prev;
+    prev = cur;
+  }
+  return prev[n] ?? 0;
+}
+function detectTyposquat(name, popular, maxDistance = 2) {
+  const target = bareName(name);
+  if (target.length < 4) return null;
+  if (popular.some((p) => p.toLowerCase() === name.toLowerCase())) return null;
+  let best = null;
+  for (const p of popular) {
+    const cand = bareName(p);
+    if (cand === target) continue;
+    if (Math.abs(cand.length - target.length) > maxDistance) continue;
+    const dist = editDistance(target, cand);
+    if (dist >= 1 && dist <= maxDistance && (!best || dist < best.distance)) {
+      best = { target: p, distance: dist };
+      if (dist === 1) break;
+    }
+  }
+  return best;
+}
+var POPULAR_BASELINE;
+var init_typosquat = __esm({
+  "src/security/typosquat.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_popular_packages();
+    POPULAR_BASELINE = popular_packages_default;
+  }
+});
+
 // src/mcp/handlers.ts
-import { sql as sql5 } from "drizzle-orm";
+var handlers_exports = {};
+__export(handlers_exports, {
+  handleCompare: () => handleCompare,
+  handleCompat: () => handleCompat,
+  handleEvaluate: () => handleEvaluate,
+  handleRecommend: () => handleRecommend,
+  handleReportOutcome: () => handleReportOutcome,
+  handleVerify: () => handleVerify,
+  latestDataAsOf: () => latestDataAsOf,
+  rowToEvaluate: () => rowToEvaluate
+});
+import { createHash as createHash3 } from "crypto";
+import { sql as sql4 } from "drizzle-orm";
 function isStale(dataAsOf) {
   if (!dataAsOf) return true;
   return Date.now() - dataAsOf.getTime() > STALENESS_DAYS * DAY_MS2;
 }
+function refreshStale(out) {
+  out.stale = isStale(out.dataAsOf ? new Date(out.dataAsOf) : null) || void 0;
+  return out;
+}
 function withinDays(date, days) {
   return date ? Date.now() - date.getTime() <= days * DAY_MS2 : false;
 }
@@ -2438,7 +3402,6 @@ function rowToEvaluate(row) {
     lastReleaseAt: row.lastReleaseAt ? row.lastReleaseAt.toISOString() : null,
     weeklyDownloads: row.weeklyDownloads,
     downloadGrowth90d: row.downloadGrowth90d,
-    dependentsCount: row.dependentsCount,
     scorecard: row.scorecard,
     bundleMinGzipKb: row.bundleMinGzipKb,
     deprecated: row.deprecated,
@@ -2446,44 +3409,95 @@ function rowToEvaluate(row) {
     advisories: topAdvisories(row.advisories),
     summary: row.summary ? truncateSentences(row.summary, 3) : null,
     usageGuide: row.usageGuide ?? null,
-    repoUrl: row.repoUrl
+    repoUrl: row.repoUrl,
+    replacedBy: lookupSuccessor(row.name)
   };
 }
 async function latestDataAsOf(db) {
-  const [row] = await db.select({ m: sql5`max(${packages.dataAsOf})` }).from(packages);
+  const [row] = await db.select({ m: sql4`max(${packages.dataAsOf})` }).from(packages);
   return new Date(row?.m ?? Date.now()).toISOString();
 }
+function cacheKey(parts) {
+  return createHash3("sha1").update(JSON.stringify(parts)).digest("hex").slice(0, 24);
+}
 async function handleRecommend(db, input) {
-  const candidates = await recommend(db, {
-    need: input.need,
-    category: input.category,
-    constraints: input.constraints,
-    limit: 5
-  });
-  return { dataAsOf: await latestDataAsOf(db), candidates };
+  return cached2(
+    "rec",
+    cacheKey([input.need, input.category ?? null, input.constraints ?? null]),
+    async () => {
+      const candidates = await recommend(db, {
+        need: input.need,
+        category: input.category,
+        constraints: input.constraints,
+        limit: 5
+      });
+      return { dataAsOf: await latestDataAsOf(db), candidates };
+    },
+    // Don't cache empty results — the index may still be populating.
+    { skipCache: (r) => r.candidates.length === 0 }
+  );
 }
 async function handleEvaluate(db, input) {
-  const { row, existsOnNpm } = await getOrFetchPackage(db, input.package);
-  if (!row) {
-    return {
-      tracked: false,
-      suggestion: existsOnNpm ? `"${input.package}" exists on npm but could not be scored right now; try again.` : `"${input.package}" was not found on the npm registry. Check the package name.`
-    };
-  }
-  return rowToEvaluate(row);
+  const out = await cached2(
+    "eval",
+    cacheKey([input.package]),
+    async () => {
+      const { row, existsOnNpm } = await getOrFetchPackage(db, input.package);
+      if (!row) {
+        return {
+          tracked: false,
+          suggestion: existsOnNpm ? `\u{1F389} Congrats \u2014 you're the first to add "${input.package}" to lurq's registry! It's being fetched and scored now; retry in a few seconds for the full evidence read.` : `"${input.package}" was not found on the npm registry. Check the package name.`
+        };
+      }
+      const evaluated = rowToEvaluate(row);
+      const verification = await getLatestVerificationByName(db, row.name);
+      return verification ? { ...evaluated, buildVerified: toBuildVerified(verification) } : evaluated;
+    },
+    // Don't cache "not found / not scored yet" — it may resolve on a later fetch.
+    { skipCache: (r) => "tracked" in r }
+  );
+  return "tracked" in out ? out : refreshStale(out);
 }
 async function handleCompare(db, input) {
-  const results = await Promise.all(input.packages.map((name) => getOrFetchPackage(db, name)));
-  const rows = results.map((r) => r.row).filter((row) => row !== null).map(rowToEvaluate).sort((a, b) => b.healthScore - a.healthScore);
-  const missing = input.packages.filter(
-    (name) => !rows.some((r) => r.name === name)
+  const out = await cached2(
+    "cmp",
+    cacheKey(input.packages),
+    async () => {
+      const results = await Promise.all(input.packages.map((name) => getOrFetchPackage(db, name)));
+      const rows = results.map((r) => r.row).filter((row) => row !== null).map(rowToEvaluate).sort((a, b) => b.healthScore - a.healthScore);
+      const missing = input.packages.filter((name) => !rows.some((r) => r.name === name));
+      return {
+        dataAsOf: await latestDataAsOf(db),
+        rows,
+        ...missing.length ? {
+          missing,
+          note: "\u{1F389} You're the first to add these to lurq's registry! They're being scored now; retry shortly for the full comparison."
+        } : {}
+      };
+    },
+    // Don't cache a transient miss (a package that momentarily failed to fetch).
+    { skipCache: (r) => Boolean(r.missing?.length) }
   );
-  return { dataAsOf: await latestDataAsOf(db), rows, ...missing.length ? { missing } : {} };
+  out.rows = out.rows.map(refreshStale);
+  return out;
+}
+function toBuildVerified(v) {
+  return {
+    version: v.version,
+    installed: v.installed,
+    loaded: v.imported,
+    driver: v.driver,
+    ranAt: v.ranAt ? v.ranAt.toISOString() : ""
+  };
+}
+async function handleCompat(db, input) {
+  return checkCompat(db, input.packages);
 }
 async function handleVerify(db, input) {
   const name = input.package;
   const exists = await npmPackageExists(name);
   if (!exists) {
+    const typo2 = detectTyposquat(name, typosquatCorpus(await getTopPackageNames(db).catch(() => [])));
     return {
       exists: false,
       tracked: false,
@@ -2491,25 +3505,46 @@ async function handleVerify(db, input) {
       archived: false,
       latestVersion: null,
       weeklyDownloads: null,
-      riskFlags: ["not-found-on-registry"],
+      riskFlags: typo2 ? ["not-found-on-registry", `possible-typosquat-of:${typo2.target}`] : ["not-found-on-registry"],
+      risk: "high",
+      typosquatOf: typo2?.target ?? null,
       confidence: null,
       advisoryCount: 0
     };
   }
-  const registry = await fetchNpmRegistry(name).catch(() => null);
-  const { row, wasTracked } = await getOrFetchPackage(db, name);
-  const weeklyDownloads = row?.weeklyDownloads ?? null;
-  const advisoryCount = row?.advisories?.length ?? 0;
+  const [registry, { row, wasTracked }, popular] = await Promise.all([
+    fetchNpmRegistry(name).catch(() => null),
+    getOrFetchPackage(db, name),
+    getTopPackageNames(db).catch(() => [])
+  ]);
+  const weeklyDownloads = row?.weeklyDownloads ?? await fetchWeeklyDownloads(name).catch(() => null);
+  const advisories = row?.advisories ?? [];
+  const advisoryCount = advisories.length;
   const deprecated = Boolean(row?.deprecated || registry?.deprecated);
   const archived = Boolean(row?.archived);
+  const brandNew = withinDays(registry?.firstPublishedAt ?? null, 7);
+  const lowTrust = weeklyDownloads === null || weeklyDownloads < 1e3;
+  const installScripts = registry?.hasInstallScripts ?? false;
+  const typo = detectTyposquat(name, typosquatCorpus(popular));
   const riskFlags = [];
+  if (typo) riskFlags.push(`possible-typosquat-of:${typo.target}`);
   if (weeklyDownloads === null || weeklyDownloads === 0) riskFlags.push("zero-downloads");
   else if (weeklyDownloads < 1e3) riskFlags.push("low-downloads");
-  if (withinDays(registry?.firstPublishedAt ?? null, 7)) riskFlags.push("published-within-7-days");
+  if (brandNew) riskFlags.push("published-within-7-days");
   if (registry?.maintainersCount === 1) riskFlags.push("single-maintainer");
+  if (installScripts) riskFlags.push("runs-install-scripts");
   if (advisoryCount > 0) riskFlags.push("has-known-advisory");
   if (deprecated) riskFlags.push("deprecated");
   if (archived) riskFlags.push("archived");
+  const risk = assessRisk({
+    flags: riskFlags,
+    hasCriticalOrHighAdvisory: hasCriticalOrHighAdvisory(advisories),
+    typosquat: Boolean(typo),
+    installScripts,
+    brandNew,
+    lowTrust,
+    deprecatedOrArchived: deprecated || archived
+  });
   return {
     exists: true,
     tracked: wasTracked,
@@ -2518,21 +3553,42 @@ async function handleVerify(db, input) {
     latestVersion: registry?.latestVersion ?? row?.latestVersion ?? null,
     weeklyDownloads,
     riskFlags,
+    risk,
+    typosquatOf: typo?.target ?? null,
     confidence: row?.confidence ?? null,
     advisoryCount
   };
 }
+async function handleReportOutcome(db, input, ownerId = null) {
+  await recordOutcome(db, {
+    ownerId,
+    packageName: input.package,
+    accepted: input.accepted,
+    buildSignal: input.buildSignal ?? null,
+    need: input.need ?? null
+  });
+  return { recorded: true };
+}
 var SEVERITY_RANK, DAY_MS2;
 var init_handlers = __esm({
   "src/mcp/handlers.ts"() {
     "use strict";
     init_esm_shims();
+    init_cache();
     init_constants();
+    init_check();
+    init_packages();
+    init_verification();
+    init_outcomes();
+    init_successors2();
     init_schema();
     init_sources();
     init_summarize();
     init_single();
+    init_score();
     init_recommend();
+    init_risk();
+    init_typosquat();
     SEVERITY_RANK = {
       critical: 4,
       high: 3,
@@ -2545,7 +3601,7 @@ var init_handlers = __esm({
 });
 
 // src/mcp/diagram.ts
-import { inArray } from "drizzle-orm";
+import { inArray as inArray2 } from "drizzle-orm";
 function layerFor(item) {
   if (!item.category) return UNCLASSIFIED;
   if (item.category === "framework" && BACKEND_FRAMEWORKS.has(item.label)) return "Backend";
@@ -2598,7 +3654,7 @@ async function handleDiagram(db, input) {
       note: "Provide a `stack` of package names to diagram. lurq labels a stack you choose; it does not infer an architecture from a description."
     };
   }
-  const rows = await db.select({ name: packages.name, category: packages.category }).from(packages).where(inArray(packages.name, input.stack));
+  const rows = await db.select({ name: packages.name, category: packages.category }).from(packages).where(inArray2(packages.name, input.stack));
   const known = new Map(rows.map((r) => [r.name, r.category]));
   const items = input.stack.map((name) => ({
     label: name,
@@ -2652,19 +3708,502 @@ var init_diagram = __esm({
   }
 });
 
+// src/compat/optimize.ts
+function conflictsFor(members, sandboxConflicts) {
+  const out = resolveArchitectureCompat(members);
+  for (let i = 0; i < members.length; i++) {
+    for (let j = i + 1; j < members.length; j++) {
+      const a = members[i].name;
+      const b = members[j].name;
+      const key = a <= b ? `${a}|${b}` : `${b}|${a}`;
+      if (sandboxConflicts.has(key)) {
+        out.push({
+          source: "sandbox",
+          packages: [a, b],
+          detail: `${a} and ${b} are recorded as incompatible (sandbox)`
+        });
+      }
+    }
+  }
+  return out;
+}
+function optimizeStack(slots, sandboxConflicts = /* @__PURE__ */ new Set()) {
+  if (slots.some((s) => s.length === 0)) {
+    throw new Error("optimizeStack: every slot must have at least one candidate");
+  }
+  const n = slots.length;
+  const budget = 5e4;
+  let nodes = 0;
+  let exhausted = false;
+  let bestSelection = new Array(n).fill(0);
+  let bestRegret = conflictsFor(
+    slots.map((c) => c[0]).filter((m) => Boolean(m)),
+    sandboxConflicts
+  ).length === 0 ? 0 : Infinity;
+  const chosen = new Array(n).fill(0);
+  const dfs = (slot, regret) => {
+    if (nodes++ > budget) {
+      exhausted = true;
+      return;
+    }
+    if (regret >= bestRegret) return;
+    if (slot === n) {
+      bestSelection = chosen.slice();
+      bestRegret = regret;
+      return;
+    }
+    const candidates = slots[slot];
+    for (let i = 0; i < candidates.length; i++) {
+      chosen[slot] = i;
+      const assigned = chosen.slice(0, slot + 1).map((idx, s) => slots[s][idx]);
+      if (conflictsFor(assigned, sandboxConflicts).length === 0) {
+        dfs(slot + 1, regret + i);
+      }
+      if (nodes > budget) {
+        exhausted = true;
+        return;
+      }
+    }
+  };
+  dfs(0, 0);
+  const members = bestSelection.map((idx, s) => slots[s][idx]);
+  return {
+    selection: bestSelection,
+    conflicts: conflictsFor(members, sandboxConflicts),
+    regret: bestRegret === Infinity ? bestSelection.reduce((a, b) => a + b, 0) : bestRegret,
+    bounded: exhausted
+  };
+}
+var init_optimize = __esm({
+  "src/compat/optimize.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_peerCompat();
+  }
+});
+
+// src/mcp/plan.ts
+var plan_exports = {};
+__export(plan_exports, {
+  decomposeHeuristic: () => decomposeHeuristic,
+  familyOf: () => familyOf,
+  flagSlotConflicts: () => flagSlotConflicts,
+  handlePlan: () => handlePlan,
+  orderCandidates: () => orderCandidates,
+  resolvePins: () => resolvePins
+});
+import { createHash as createHash4 } from "crypto";
+import { inArray as inArray3 } from "drizzle-orm";
+function packageToCandidate(row) {
+  return {
+    name: row.name,
+    category: row.category,
+    healthScore: row.healthScore ?? 0,
+    qualityScore: row.qualityScore,
+    confidence: row.confidence ?? "unproven",
+    why: "pinned by you",
+    latestVersion: row.latestVersion,
+    weeklyDownloads: row.weeklyDownloads,
+    lastReleaseAt: row.lastReleaseAt ? row.lastReleaseAt.toISOString() : null,
+    repoUrl: row.repoUrl
+  };
+}
+async function resolvePins(db, using, recommendedNames) {
+  const slots = [];
+  const unresolved = [];
+  for (const name of new Set(using ?? [])) {
+    if (recommendedNames.has(name)) continue;
+    const { row } = await getOrFetchPackage(db, name);
+    if (!row) {
+      unresolved.push(name);
+      continue;
+    }
+    slots.push({
+      need: `using ${name}`,
+      category: row.category,
+      layer: layerFor({ label: name, category: row.category }),
+      recommended: packageToCandidate(row),
+      alternatives: [],
+      // fixed: the user chose this, so it never gets swapped
+      note: "pinned by you"
+    });
+  }
+  return { slots, unresolved };
+}
+async function handlePlan(db, input) {
+  const optimize = input.optimize ?? "balanced";
+  const decomposed = input.needs?.length ? { needs: dedupeNeeds(input.needs), source: "needs" } : input.document?.trim() ? await decompose(input.document) : null;
+  const hasPins = Boolean(input.using?.length);
+  if ((!decomposed || decomposed.needs.length === 0) && !hasPins) {
+    return {
+      note: "Provide a `document` (a detailed description of your program), a `needs` array, or a `using` list of packages you have already chosen. lurq recommends evidence-scored packages per component \u2014 it does not invent an architecture from a bare prompt."
+    };
+  }
+  const needs = (decomposed?.needs ?? []).slice(0, MAX_SLOTS);
+  const source = decomposed?.source ?? "needs";
+  const safeRecommend = (need, category) => recommend(db, { need, category, limit: PER_SLOT }).catch((err) => {
+    logger.warn(`plan: recommend failed for "${need}": ${err.message}`);
+    return [];
+  });
+  const effCat = (n) => n.category ?? inferCategory(n.need) ?? void 0;
+  const anchorFamily = familyOf(`${input.document ?? ""} ${needs.map((n) => n.need).join(" ")}`);
+  const metaIdx = needs.findIndex((n) => effCat(n) === "meta-framework");
+  const anchorIdx = metaIdx >= 0 ? metaIdx : needs.findIndex((n) => effCat(n) === "framework");
+  const recs = new Array(needs.length);
+  let framework = anchorFamily;
+  if (anchorIdx >= 0) {
+    recs[anchorIdx] = await safeRecommend(needs[anchorIdx].need, effCat(needs[anchorIdx]));
+    framework = recs[anchorIdx][0]?.name ?? anchorFamily;
+  }
+  const [, dataAsOf] = await Promise.all([
+    Promise.all(
+      needs.map(async (n, i) => {
+        if (i === anchorIdx) return;
+        const need = framework ? `${n.need} (for a ${framework} app)` : n.need;
+        recs[i] = await safeRecommend(need, effCat(n));
+      })
+    ),
+    latestDataAsOf(db)
+  ]);
+  const bundleByName = optimize === "speed" ? await bundleSizes(db, recs.flat()) : /* @__PURE__ */ new Map();
+  const recSlots = needs.map((n, i) => {
+    const candidates = orderCandidates(recs[i], anchorFamily, optimize, bundleByName);
+    const recommended = candidates[0] ?? null;
+    const category = n.category ?? recommended?.category ?? inferCategory(n.need);
+    return {
+      need: n.need,
+      category,
+      layer: layerFor({ label: recommended?.name ?? n.need, category }),
+      recommended,
+      alternatives: candidates.slice(1),
+      note: recommended ? void 0 : "no tracked package matched this need yet"
+    };
+  });
+  const recommendedNames = new Set(
+    recSlots.map((s) => s.recommended?.name).filter((n) => Boolean(n))
+  );
+  const { slots: pinnedSlots, unresolved: unresolvedPins } = await resolvePins(
+    db,
+    input.using,
+    recommendedNames
+  );
+  const slots = [...pinnedSlots, ...recSlots];
+  const compatibility = await resolveCompat(db, slots);
+  const unmatched = [
+    ...slots.filter((s) => !s.recommended).map((s) => s.need),
+    ...unresolvedPins.map((n) => `${n} (pinned, but not found on npm)`)
+  ];
+  const mermaid = buildMermaid(
+    slots.filter((s) => s.recommended).map((s) => ({ label: s.recommended.name, category: s.category }))
+  );
+  return {
+    dataAsOf,
+    optimize,
+    source,
+    framework,
+    slots,
+    unmatched,
+    mermaid,
+    note: planNote(source, unmatched.length, optimize, framework),
+    compatibility
+  };
+}
+function flagSlotConflicts(picks, conflicts) {
+  const out = /* @__PURE__ */ new Map();
+  for (const c of conflicts) {
+    for (const p of picks) {
+      if (p.name && c.packages.includes(p.name)) {
+        const others = c.packages.filter((n) => n !== p.name);
+        out.set(p.need, [.../* @__PURE__ */ new Set([...out.get(p.need) ?? [], ...others])]);
+      }
+    }
+  }
+  return out;
+}
+async function resolveCompat(db, slots) {
+  const eligible = slots.filter((s) => s.recommended);
+  if (eligible.length < 2) return null;
+  try {
+    const allNames = [
+      ...new Set(eligible.flatMap((s) => [s.recommended, ...s.alternatives].map((c) => c.name)))
+    ];
+    const [{ members }, edges] = await Promise.all([
+      assembleMembers(db, allNames),
+      getCompatEdges(db, allNames)
+    ]);
+    const metaByName = new Map(members.map((m) => [m.name, m]));
+    const sandboxConflicts = new Set(
+      edges.filter((e) => e.status === "conflict").map((e) => `${e.packageA}|${e.packageB}`)
+    );
+    const slotCandidates = eligible.map(
+      (s) => [s.recommended, ...s.alternatives].map((c) => metaByName.get(c.name) ?? NO_META(c))
+    );
+    const { selection } = optimizeStack(slotCandidates, sandboxConflicts);
+    eligible.forEach((s, i) => {
+      const idx = selection[i] ?? 0;
+      if (idx <= 0) return;
+      const all = [s.recommended, ...s.alternatives];
+      const chosen = all[idx];
+      if (!chosen) return;
+      s.recommended = chosen;
+      s.alternatives = all.filter((c) => c.name !== chosen.name);
+      s.swappedFrom = all[0].name;
+    });
+  } catch (err) {
+    logger.warn(`plan: compat optimization failed: ${String(err)}`);
+  }
+  const compat = await checkCompat(
+    db,
+    eligible.map((s) => s.recommended.name)
+  ).catch(() => null);
+  if (compat) {
+    const flags = flagSlotConflicts(
+      slots.map((s) => ({ need: s.need, name: s.recommended?.name ?? null })),
+      compat.conflicts
+    );
+    for (const s of slots) {
+      const cw = flags.get(s.need);
+      s.conflictsWith = cw?.length ? cw : void 0;
+    }
+  }
+  return compat;
+}
+function planNote(source, unmatched, optimize, framework) {
+  const base = source === "heuristic" ? "Components were extracted from your document with a keyword heuristic (no summary LLM configured) \u2014 coarse; pass a `needs` array or set SUMMARY_API_KEY for sharper decomposition." : source === "llm" ? "Components were extracted from your document by the summary model." : "Components taken from the supplied needs.";
+  const grounding = " Each package is recommended from lurq\u2019s scored index \u2014 a labeled, evidence-backed starting point, not a validated architecture.";
+  const ctx = framework ? ` Anchored to the ${framework} ecosystem so sibling libraries stay coherent across the stack.` : "";
+  const tail = unmatched ? ` ${unmatched} need(s) had no tracked match (listed in \`unmatched\`).` : "";
+  const opt = optimize === "speed" ? " Ranking favored the lightest-bundle option per slot." : "";
+  return base + grounding + ctx + opt + tail;
+}
+function dedupeNeeds(needs) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const n of needs) {
+    const key = n.need.trim().toLowerCase();
+    if (!key) continue;
+    if (!seen.has(key)) seen.set(key, { need: n.need.trim(), category: n.category });
+  }
+  return [...seen.values()];
+}
+function familyOf(name) {
+  const n = name.toLowerCase();
+  for (const f of FAMILY_TOKENS) if (f.re.test(n)) return f.family;
+  return null;
+}
+function orderCandidates(cands, anchorFamily, optimize, bundleByName) {
+  const coherence = (c) => {
+    const fam = familyOf(c.name);
+    if (!fam) return 0;
+    return fam === anchorFamily ? 1 : -1;
+  };
+  return [...cands].sort((a, b) => {
+    if (anchorFamily) {
+      const d = coherence(b) - coherence(a);
+      if (d) return d;
+    }
+    if (optimize === "speed") {
+      return (bundleByName.get(a.name) ?? Infinity) - (bundleByName.get(b.name) ?? Infinity);
+    }
+    return 0;
+  });
+}
+async function bundleSizes(db, candidates) {
+  const names = [...new Set(candidates.map((c) => c.name))];
+  if (names.length === 0) return /* @__PURE__ */ new Map();
+  const rows = await db.select({ name: packages.name, bundle: packages.bundleMinGzipKb }).from(packages).where(inArray3(packages.name, names));
+  return new Map(rows.filter((r) => r.bundle != null).map((r) => [r.name, r.bundle]));
+}
+async function decompose(document) {
+  const config = getConfig();
+  if (config.SUMMARY_PROVIDER === "openai" && config.SUMMARY_API_KEY) {
+    const llm = await decomposeWithLlm(
+      document,
+      config.SUMMARY_API_KEY,
+      config.SUMMARY_MODEL,
+      config.SUMMARY_BASE_URL
+    ).catch((err) => {
+      logger.warn(`plan: LLM decomposition failed, using heuristic: ${err.message}`);
+      return null;
+    });
+    if (llm?.length) return { needs: dedupeNeeds(llm), source: "llm" };
+  }
+  return { needs: decomposeHeuristic(document), source: "heuristic" };
+}
+async function decomposeWithLlm(document, apiKey, model, baseUrl) {
+  const prompt = [
+    "Project description:",
+    document.slice(0, 8e3),
+    "",
+    'Return JSON: { "needs": [ { "need": "<one phrase describing a component that needs a library>", "category": "<optional taxonomy hint or empty>" } ] }.',
+    "One entry per distinct component (e.g. routing, validation, ORM, HTTP client). Omit anything not implied by the description."
+  ].join("\n");
+  const { data } = await httpRequest(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
+    host: new URL(baseUrl).host,
+    method: "POST",
+    ttlMs: 24 * 60 * 60 * 1e3,
+    // Hash the FULL document — length + a 64-char prefix collide for same-length
+    // edits or shared templated headers, which would serve a stale decomposition.
+    cacheKey: `openai-plan ${model} ${createHash4("sha1").update(document).digest("hex")}`,
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: "system", content: DECOMPOSE_SYSTEM },
+        { role: "user", content: prompt }
+      ],
+      response_format: { type: "json_object" },
+      temperature: 0.2
+    })
+  });
+  const content = data?.choices?.[0]?.message?.content;
+  const parsed = content ? JSON.parse(content) : {};
+  const raw = Array.isArray(parsed?.needs) ? parsed.needs : [];
+  return raw.map((n) => {
+    const need = typeof n?.need === "string" ? n.need.trim() : "";
+    if (!need) return null;
+    const cat = typeof n?.category === "string" && isCategory(n.category) ? n.category : void 0;
+    return { need, category: cat };
+  }).filter(Boolean);
+}
+function decomposeHeuristic(document) {
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const rawLine of document.split("\n")) {
+    const line = rawLine.replace(/^[#>*\-\s]+/, "").replace(/^\d+\.\s+/, "").trim();
+    if (line.length < 3) continue;
+    const category = inferCategory(line);
+    if (category && !byCategory.has(category)) {
+      byCategory.set(category, line.slice(0, 120));
+    }
+  }
+  return [...byCategory.entries()].map(([category, need]) => ({ need, category }));
+}
+var PER_SLOT, MAX_SLOTS, NO_META, FAMILY_TOKENS, DECOMPOSE_SYSTEM;
+var init_plan = __esm({
+  "src/mcp/plan.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_config();
+    init_http();
+    init_check();
+    init_members();
+    init_optimize();
+    init_compat();
+    init_logger();
+    init_types();
+    init_schema();
+    init_categoryInference();
+    init_recommend();
+    init_single();
+    init_diagram();
+    init_handlers();
+    PER_SLOT = 3;
+    MAX_SLOTS = 24;
+    NO_META = (c) => ({
+      name: c.name,
+      version: c.latestVersion,
+      peerDependencies: null,
+      peerDependenciesMeta: null,
+      engines: null
+    });
+    FAMILY_TOKENS = [
+      { family: "react", re: /\breact\b|preact/ },
+      { family: "vue", re: /\bvue\b|nuxt/ },
+      { family: "angular", re: /angular/ },
+      { family: "svelte", re: /svelte/ },
+      { family: "solid", re: /\bsolid(-?js)?\b/ }
+    ];
+    DECOMPOSE_SYSTEM = "You break a software project description into the distinct technical components that each need a library. Return ONLY components the project actually requires, grounded in the description. Respond with a JSON object.";
+  }
+});
+
+// src/mcp/metrics.ts
+function recordToolCall(tool, ok, ms) {
+  const s = stats.get(tool) ?? { calls: 0, errors: 0, totalMs: 0 };
+  s.calls += 1;
+  if (!ok) s.errors += 1;
+  s.totalMs += ms;
+  stats.set(tool, s);
+}
+async function timed(tool, fn) {
+  const start = Date.now();
+  let ok = false;
+  try {
+    const result = await fn();
+    ok = true;
+    return result;
+  } finally {
+    recordToolCall(tool, ok, Date.now() - start);
+  }
+}
+function renderPrometheus() {
+  const lines = [
+    "# HELP lurq_tool_calls_total Total MCP tool invocations.",
+    "# TYPE lurq_tool_calls_total counter",
+    "# HELP lurq_tool_errors_total MCP tool invocations that threw.",
+    "# TYPE lurq_tool_errors_total counter",
+    "# HELP lurq_tool_duration_ms_total Cumulative tool handler time in ms.",
+    "# TYPE lurq_tool_duration_ms_total counter"
+  ];
+  for (const [tool, s] of stats) {
+    const label = `{tool="${tool}"}`;
+    lines.push(`lurq_tool_calls_total${label} ${s.calls}`);
+    lines.push(`lurq_tool_errors_total${label} ${s.errors}`);
+    lines.push(`lurq_tool_duration_ms_total${label} ${s.totalMs}`);
+  }
+  return lines.join("\n") + "\n";
+}
+var stats;
+var init_metrics = __esm({
+  "src/mcp/metrics.ts"() {
+    "use strict";
+    init_esm_shims();
+    stats = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/mcp/compact.ts
+function isEmptyObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+function compact(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => compact(v)).filter((v) => v !== null && v !== void 0);
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+      if (raw === null || raw === void 0) continue;
+      const cleaned = compact(raw);
+      if (cleaned === null || cleaned === void 0) continue;
+      if (Array.isArray(cleaned) && cleaned.length === 0) continue;
+      if (isEmptyObject(cleaned)) continue;
+      out[key] = cleaned;
+    }
+    return out;
+  }
+  return value;
+}
+var init_compact = __esm({
+  "src/mcp/compact.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/mcp/server.ts
 var server_exports = {};
 __export(server_exports, {
   buildMcpServer: () => buildMcpServer,
+  npmName: () => npmName,
   startMcpServer: () => startMcpServer
 });
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z2 } from "zod";
 function json(obj) {
-  return { content: [{ type: "text", text: JSON.stringify(obj) }] };
+  return { content: [{ type: "text", text: JSON.stringify(compact(obj)) }] };
 }
-function buildMcpServer(db) {
+function buildMcpServer(db, ctx = {}) {
   const server = new McpServer({ name: SERVER_NAME, version: VERSION });
   server.registerTool(
     "recommend",
@@ -2677,7 +4216,7 @@ function buildMcpServer(db) {
         constraints: constraintsSchema
       }
     },
-    async (args) => json(await handleRecommend(db, args))
+    async (args) => json(await timed("recommend", () => handleRecommend(db, args)))
   );
   server.registerTool(
     "evaluate",
@@ -2685,10 +4224,10 @@ function buildMcpServer(db) {
       title: "Evaluate a package",
       description: "Full evidence read for one npm package: scores, signals, advisories, summary, and a usage guide. Fetches & scores on demand if not yet tracked.",
       inputSchema: {
-        package: z2.string().min(1).describe("npm package name")
+        package: npmName.describe("npm package name")
       }
     },
-    async (args) => json(await handleEvaluate(db, args))
+    async (args) => json(await timed("evaluate", () => handleEvaluate(db, args)))
   );
   server.registerTool(
     "compare",
@@ -2696,10 +4235,21 @@ function buildMcpServer(db) {
       title: "Compare packages",
       description: "Side-by-side comparison of 2\u20135 npm packages, ranked by health score.",
       inputSchema: {
-        packages: z2.array(z2.string().min(1)).min(2).max(5).describe("2\u20135 npm package names")
+        packages: z2.array(npmName).min(2).max(5).describe("2\u20135 npm package names")
+      }
+    },
+    async (args) => json(await timed("compare", () => handleCompare(db, args)))
+  );
+  server.registerTool(
+    "compat",
+    {
+      title: "Check package compatibility",
+      description: "Check whether a set of packages forms a coherent stack: peer-dependency and engine-range compatibility across the whole set (instant, from declared metadata), plus any recorded sandbox-verified conflicts. Returns the exact clashing constraints. Read-only \u2014 does not run installs. Call before committing to a multi-package stack.",
+      inputSchema: {
+        packages: z2.array(npmName).min(2).max(8).describe("2\u20138 npm package names to check together")
       }
     },
-    async (args) => json(await handleCompare(db, args))
+    async (args) => json(await timed("compat", () => handleCompat(db, args)))
   );
   server.registerTool(
     "verify",
@@ -2707,10 +4257,10 @@ function buildMcpServer(db) {
       title: "Verify a package",
       description: "Confirm an npm package is real, healthy, and not risky before installing \u2014 guards against hallucinated or typosquatted dependency names. Checks the live registry.",
       inputSchema: {
-        package: z2.string().min(1).describe("npm package name to verify")
+        package: npmName.describe("npm package name to verify")
       }
     },
-    async (args) => json(await handleVerify(db, args))
+    async (args) => json(await timed("verify", () => handleVerify(db, args)))
   );
   server.registerTool(
     "diagram",
@@ -2718,10 +4268,47 @@ function buildMcpServer(db) {
       title: "Reference architecture diagram",
       description: "Emit a reference-architecture Mermaid diagram for a stack you have already chosen (package names). A labeled starting point keyed by layer \u2014 not a validated architecture, and not an architecture designer.",
       inputSchema: {
-        stack: z2.array(z2.string()).optional().describe("Package names that make up the stack; omit or empty to get usage guidance")
+        stack: z2.array(npmName).optional().describe("Package names that make up the stack; omit or empty to get usage guidance")
+      }
+    },
+    async (args) => json(await timed("diagram", () => handleDiagram(db, args)))
+  );
+  server.registerTool(
+    "plan",
+    {
+      title: "Plan a stack from a program description",
+      description: "Turn a detailed program description (spec/README) or a list of component needs into an evidence-scored build plan: a real, lurq-scored package recommended per component, plus a Mermaid roadmap other agents can parse. Recommends building blocks slot-by-slot from the index \u2014 it does not invent an architecture from a bare prompt.",
+      inputSchema: {
+        document: z2.string().optional().describe("Detailed description of the program (spec/README); lurq decomposes it into components"),
+        needs: z2.array(
+          z2.object({
+            need: z2.string().min(1).describe("A component that needs a library"),
+            category: categoryEnum.optional()
+          })
+        ).optional().describe("Pre-decomposed components (skip if you pass a document)"),
+        using: z2.array(npmName).max(12).optional().describe(
+          "Packages you have already decided on. lurq pins these as fixed slots, recommends only the remaining needs, and checks/optimizes the whole stack around your picks."
+        ),
+        optimize: z2.enum(["speed", "balanced"]).optional().describe("'speed' prefers the lightest-bundle option per slot; default 'balanced'")
+      }
+    },
+    async (args) => json(await timed("plan", () => handlePlan(db, args)))
+  );
+  server.registerTool(
+    "report_outcome",
+    {
+      title: "Report a recommendation outcome",
+      description: "Opt-in feedback after acting on a lurq recommendation: report whether you went with the package and whether it built. No source code \u2014 only the coarse decision + a build signal. Helps lurq learn which packages agents actually succeed with; safe to skip.",
+      inputSchema: {
+        package: npmName.describe("The package that was recommended"),
+        accepted: z2.boolean().describe("Did you go with this package?"),
+        buildSignal: z2.enum(["installed", "compiled", "tests_passed", "failed"]).optional().describe("Coarse post-install result, if known"),
+        need: z2.string().max(500).optional().describe("The original need this was recommended for (no source code)")
       }
     },
-    async (args) => json(await handleDiagram(db, args))
+    // ownerId comes from the authenticated key (ctx), NOT the tool arguments —
+    // a caller must never be able to attribute an outcome to another org.
+    async (args) => json(await timed("report_outcome", () => handleReportOutcome(db, args, ctx.ownerId ?? null)))
   );
   return server;
 }
@@ -2741,7 +4328,7 @@ async function startMcpServer() {
   await server.connect(transport);
   logger.info(`${SERVER_NAME} MCP server v${VERSION} running on stdio.`);
 }
-var categoryEnum, confidenceEnum, constraintsSchema;
+var categoryEnum, confidenceEnum, npmName, constraintsSchema;
 var init_server = __esm({
   "src/mcp/server.ts"() {
     "use strict";
@@ -2752,8 +4339,12 @@ var init_server = __esm({
     init_logger();
     init_handlers();
     init_diagram();
+    init_plan();
+    init_metrics();
+    init_compact();
     categoryEnum = z2.enum(CATEGORIES);
     confidenceEnum = z2.enum(["proven", "emerging", "promising", "unproven"]);
+    npmName = z2.string().trim().min(1).max(214).regex(/^(?:@[a-z0-9-][a-z0-9-._]*\/)?[a-z0-9-][a-z0-9-._]*$/i, "Invalid npm package name");
     constraintsSchema = z2.object({
       runtime: z2.enum(["browser", "node", "both"]).optional(),
       license: z2.string().optional(),
@@ -2764,10 +4355,10 @@ var init_server = __esm({
 });
 
 // src/auth/apiKeys.ts
-import { createHash as createHash3, randomBytes } from "crypto";
-import { and as and3, desc, eq as eq4, isNull } from "drizzle-orm";
+import { createHash as createHash5, randomBytes } from "crypto";
+import { and as and5, desc as desc3, eq as eq5, isNull } from "drizzle-orm";
 function hashKey(key) {
-  return createHash3("sha256").update(key).digest("hex");
+  return createHash5("sha256").update(key).digest("hex");
 }
 function generateApiKey() {
   const body = randomBytes(24).toString("base64url");
@@ -2785,48 +4376,106 @@ async function createKey(db, input = {}) {
   }).returning();
   return { key, row };
 }
+function stampLastUsed(db, entry, now) {
+  if (now - entry.lastStampAt < STAMP_INTERVAL_MS) return;
+  entry.lastStampAt = now;
+  db.update(apiKeys).set({ lastUsedAt: new Date(now) }).where(eq5(apiKeys.id, entry.row.id)).then(void 0, (err) => logger.debug(`lastUsedAt stamp failed: ${String(err)}`));
+}
 async function lookupActiveKey(db, key) {
   const hash = hashKey(key);
-  const [row] = await db.select().from(apiKeys).where(and3(eq4(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt))).limit(1);
-  if (!row) return null;
-  db.update(apiKeys).set({ lastUsedAt: /* @__PURE__ */ new Date() }).where(eq4(apiKeys.id, row.id)).then(void 0, () => {
-  });
+  const now = Date.now();
+  const cached3 = authCache.get(hash);
+  if (cached3 && now - cached3.cachedAt < AUTH_TTL_MS) {
+    stampLastUsed(db, cached3, now);
+    return cached3.row;
+  }
+  const [row] = await db.select().from(apiKeys).where(and5(eq5(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt))).limit(1);
+  if (!row) {
+    authCache.delete(hash);
+    return null;
+  }
+  const entry = { row, cachedAt: now, lastStampAt: 0 };
+  authCache.set(hash, entry);
+  stampLastUsed(db, entry, now);
   return row;
 }
 async function listKeys(db) {
-  return db.select().from(apiKeys).orderBy(desc(apiKeys.createdAt));
+  return db.select().from(apiKeys).orderBy(desc3(apiKeys.createdAt));
 }
-async function revokeKey(db, prefixOrId) {
+function matchByPrefixOrId(prefixOrId) {
   const asId = Number(prefixOrId);
-  const match = Number.isInteger(asId) && String(asId) === prefixOrId.trim() ? eq4(apiKeys.id, asId) : eq4(apiKeys.prefix, prefixOrId);
-  const rows = await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(and3(match, isNull(apiKeys.revokedAt))).returning({ id: apiKeys.id });
+  return Number.isInteger(asId) && String(asId) === prefixOrId.trim() ? eq5(apiKeys.id, asId) : eq5(apiKeys.prefix, prefixOrId);
+}
+async function revokeKey(db, prefixOrId) {
+  const rows = await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(and5(matchByPrefixOrId(prefixOrId), isNull(apiKeys.revokedAt))).returning({ id: apiKeys.id });
   return rows.length;
 }
-var DISPLAY_BODY;
+async function rotateKey(db, prefixOrId) {
+  const [previous] = await db.select().from(apiKeys).where(and5(matchByPrefixOrId(prefixOrId), isNull(apiKeys.revokedAt))).limit(1);
+  if (!previous) return null;
+  const { key, row } = await createKey(db, {
+    label: previous.label ?? void 0,
+    tier: previous.tier,
+    ownerId: previous.ownerId ?? void 0
+  });
+  await db.update(apiKeys).set({ revokedAt: /* @__PURE__ */ new Date() }).where(eq5(apiKeys.id, previous.id));
+  return { key, row, previous };
+}
+var DISPLAY_BODY, authCache, AUTH_TTL_MS, STAMP_INTERVAL_MS;
 var init_apiKeys = __esm({
   "src/auth/apiKeys.ts"() {
     "use strict";
     init_esm_shims();
     init_constants();
     init_schema();
+    init_logger();
     DISPLAY_BODY = 6;
+    authCache = /* @__PURE__ */ new Map();
+    AUTH_TTL_MS = 6e4;
+    STAMP_INTERVAL_MS = 6e4;
   }
 });
 
 // src/mcp/http.ts
 var http_exports = {};
 __export(http_exports, {
+  secretEquals: () => secretEquals,
   startHttpServer: () => startHttpServer
 });
+import { createHash as createHash6, timingSafeEqual } from "crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 function rpcError(code, message) {
   return { jsonrpc: "2.0", error: { code, message }, id: null };
 }
+function secretEquals(a, b) {
+  return timingSafeEqual(
+    createHash6("sha256").update(a).digest(),
+    createHash6("sha256").update(b).digest()
+  );
+}
 async function startHttpServer(opts = {}) {
   const config = getConfig();
   const port = opts.port ?? config.PORT;
   const [{ default: express }, { default: helmet }, { rateLimit, ipKeyGenerator }] = await Promise.all([import("express"), import("helmet"), import("express-rate-limit")]);
   const { db } = createDb({ max: 20 });
+  if (!process.env.REDIS_URL) {
+    logger.warn(
+      "REDIS_URL not set \u2014 response caching is OFF; every request recomputes on the database. Set REDIS_URL before serving real traffic (and it also backs the rate limiter across instances)."
+    );
+  }
+  let makeStore = null;
+  if (process.env.REDIS_URL) {
+    const [{ default: Redis }, { default: RedisStore }] = await Promise.all([
+      import("ioredis"),
+      import("rate-limit-redis")
+    ]);
+    const rlRedis = new Redis(process.env.REDIS_URL, { maxRetriesPerRequest: 1, family: 0 });
+    rlRedis.on("error", (err) => logger.warn(`rate-limit redis: ${err.message}`));
+    makeStore = (prefix) => new RedisStore({
+      prefix,
+      sendCommand: (...args) => rlRedis.call(args[0], ...args.slice(1))
+    });
+  }
   const app = express();
   app.set("trust proxy", 1);
   app.use(helmet());
@@ -2834,11 +4483,26 @@ async function startHttpServer(opts = {}) {
   app.get("/healthz", (_req, res) => {
     res.status(200).json({ status: "ok" });
   });
+  app.get("/metrics", (req, res) => {
+    const token = config.LURQ_METRICS_TOKEN;
+    if (!token) {
+      res.status(404).end();
+      return;
+    }
+    const header = req.headers.authorization;
+    const presented = header?.startsWith("Bearer ") ? header.slice(7).trim() : "";
+    if (presented !== token) {
+      res.status(401).end();
+      return;
+    }
+    res.type("text/plain").send(renderPrometheus());
+  });
   const ipLimiter = rateLimit({
     windowMs: config.LURQ_RATE_LIMIT_WINDOW_MS,
     limit: config.LURQ_IP_RATE_LIMIT_MAX,
     standardHeaders: "draft-7",
     legacyHeaders: false,
+    ...makeStore ? { store: makeStore("rl:ip:") } : {},
     message: rpcError(-32029, "Rate limit exceeded.")
   });
   const auth = async (req, res, next) => {
@@ -2866,14 +4530,47 @@ async function startHttpServer(opts = {}) {
     limit: config.LURQ_RATE_LIMIT_MAX,
     standardHeaders: "draft-7",
     legacyHeaders: false,
-    // Key on the resolved API key (always present — auth runs first). The IP
-    // fallback uses express-rate-limit's ipKeyGenerator so IPv6 addresses are
-    // normalized correctly (v8 throws ERR_ERL_KEY_GEN_IPV6 on a raw req.ip).
-    keyGenerator: (req) => req.lurqKey?.prefix ?? ipKeyGenerator(req.ip ?? "0.0.0.0"),
+    // Key on the resolved API key's unique row id (always present — auth runs
+    // first). The display `prefix` is only 6 chars of body, so distinct keys
+    // can collide on it and share a quota; the id cannot. The IP fallback uses
+    // express-rate-limit's ipKeyGenerator so IPv6 addresses are normalized
+    // correctly (v8 throws ERR_ERL_KEY_GEN_IPV6 on a raw req.ip).
+    keyGenerator: (req) => {
+      const id = req.lurqKey?.id;
+      return id != null ? `key:${id}` : ipKeyGenerator(req.ip ?? "0.0.0.0");
+    },
+    ...makeStore ? { store: makeStore("rl:key:") } : {},
     message: rpcError(-32029, "Rate limit exceeded.")
   });
+  app.post("/keys", async (req, res) => {
+    const secret = config.LURQ_ISSUER_SECRET;
+    if (!secret) {
+      res.status(404).end();
+      return;
+    }
+    const header = req.headers.authorization;
+    const token = header?.startsWith("Bearer ") ? header.slice(7).trim() : "";
+    if (!token || !secretEquals(token, secret)) {
+      res.status(401).json({ error: "Invalid issuer secret." });
+      return;
+    }
+    const body = req.body ?? {};
+    const ownerId = typeof body.ownerId === "string" ? body.ownerId.trim() : "";
+    if (!ownerId) {
+      res.status(400).json({ error: "ownerId is required." });
+      return;
+    }
+    const label = typeof body.label === "string" ? body.label.slice(0, 200) : void 0;
+    try {
+      const { key, row } = await createKey(db, { ownerId, label, tier: "free" });
+      res.status(201).json({ key, prefix: row.prefix });
+    } catch (err) {
+      logger.error("key issuance failed:", err instanceof Error ? err.message : String(err));
+      res.status(500).json({ error: "Could not issue key." });
+    }
+  });
   app.post("/mcp", ipLimiter, auth, keyLimiter, async (req, res) => {
-    const server = buildMcpServer(db);
+    const server = buildMcpServer(db, { ownerId: req.lurqKey?.ownerId ?? null });
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: void 0,
       enableJsonResponse: true
@@ -2906,27 +4603,29 @@ var init_http2 = __esm({
     init_apiKeys();
     init_client();
     init_server();
+    init_metrics();
   }
 });
 
 // src/pipeline/rescore.ts
-import { isNotNull as isNotNull3 } from "drizzle-orm";
-import { eq as eq5 } from "drizzle-orm";
+import { isNotNull as isNotNull4 } from "drizzle-orm";
+import { eq as eq6 } from "drizzle-orm";
 async function runRescore() {
   const weights = loadWeights();
   const handle = createDb({ max: 4 });
   try {
-    const rows = await handle.db.select({ id: packages.id, breakdown: packages.scoreBreakdown, healthScore: packages.healthScore }).from(packages).where(isNotNull3(packages.scoreBreakdown));
+    const rows = await handle.db.select({ id: packages.id, breakdown: packages.scoreBreakdown, healthScore: packages.healthScore }).from(packages).where(isNotNull4(packages.scoreBreakdown));
     let updated = 0;
     for (const row of rows) {
       if (!row.breakdown) continue;
       const health = computeHealthScore(row.breakdown, weights.health);
       if (health !== row.healthScore) {
-        await handle.db.update(packages).set({ healthScore: health, updatedAt: /* @__PURE__ */ new Date() }).where(eq5(packages.id, row.id));
+        await handle.db.update(packages).set({ healthScore: health, updatedAt: /* @__PURE__ */ new Date() }).where(eq6(packages.id, row.id));
         updated++;
       }
     }
     logger.info(`Rescored ${rows.length} package(s); ${updated} health score(s) changed.`);
+    if (updated > 0) await invalidateCache();
     return { seen: rows.length, updated };
   } finally {
     await handle.close();
@@ -2936,6 +4635,7 @@ var init_rescore = __esm({
   "src/pipeline/rescore.ts"() {
     "use strict";
     init_esm_shims();
+    init_cache();
     init_logger();
     init_client();
     init_schema();
@@ -2945,7 +4645,7 @@ var init_rescore = __esm({
 });
 
 // src/db/discovery.ts
-import { eq as eq6, inArray as inArray2, sql as sql6 } from "drizzle-orm";
+import { eq as eq7 } from "drizzle-orm";
 async function getKnownNames(db) {
   const [tracked, queued] = await Promise.all([
     db.select({ name: packages.name }).from(packages),
@@ -2960,10 +4660,10 @@ async function enqueueCandidates(db, candidates) {
   return inserted.length;
 }
 async function getPendingCandidates(db, limit) {
-  return db.select().from(discoveryQueue).where(eq6(discoveryQueue.status, "pending")).limit(limit);
+  return db.select().from(discoveryQueue).where(eq7(discoveryQueue.status, "pending")).limit(limit);
 }
 async function setDiscoveryStatus(db, name, data) {
-  await db.update(discoveryQueue).set({ status: data.status, ...data.preScore !== void 0 ? { preScore: data.preScore } : {} }).where(eq6(discoveryQueue.name, name));
+  await db.update(discoveryQueue).set({ status: data.status, ...data.preScore !== void 0 ? { preScore: data.preScore } : {} }).where(eq7(discoveryQueue.name, name));
 }
 var init_discovery = __esm({
   "src/db/discovery.ts"() {
@@ -2974,7 +4674,7 @@ var init_discovery = __esm({
 });
 
 // src/pipeline/discovery.ts
-import { isNotNull as isNotNull4 } from "drizzle-orm";
+import { isNotNull as isNotNull5 } from "drizzle-orm";
 function selectCandidates(raw, known) {
   const seen = new Set(known);
   const out = [];
@@ -3007,7 +4707,7 @@ async function preScorePackage(name, fetchImpl) {
   }
 }
 async function graphChannel(db) {
-  const tracked = await db.select({ name: packages.name, version: packages.latestVersion }).from(packages).where(isNotNull4(packages.latestVersion));
+  const tracked = await db.select({ name: packages.name, version: packages.latestVersion }).from(packages).where(isNotNull5(packages.latestVersion));
   const out = [];
   for (const t of tracked) {
     if (!t.version) continue;
@@ -3049,9 +4749,13 @@ async function runDiscovery(opts = {}) {
     logger.info(
       `Discovery: ${graph.length} graph + ${search.length} search candidates \u2192 ${enqueued} new queued.`
     );
-    const pending = await getPendingCandidates(handle.db, cap * 4);
+    const pending2 = await getPendingCandidates(handle.db, cap * 4);
     const scored = [];
-    for (const cand of pending) {
+    for (const cand of pending2) {
+      if (cand.preScore !== null) {
+        scored.push({ name: cand.name, preScore: cand.preScore });
+        continue;
+      }
       const preScore = await preScorePackage(cand.name);
       await setDiscoveryStatus(handle.db, cand.name, {
         status: passesGate(preScore) ? "pending" : "rejected",
@@ -3059,7 +4763,7 @@ async function runDiscovery(opts = {}) {
       });
       if (passesGate(preScore)) scored.push({ name: cand.name, preScore });
     }
-    logger.info(`Discovery: gated ${pending.length}; ${scored.length} cleared the quality bar.`);
+    logger.info(`Discovery: gated ${pending2.length}; ${scored.length} cleared the quality bar.`);
     scored.sort((a, b) => b.preScore - a.preScore);
     const toIngest = scored.slice(0, cap);
     const deferred = scored.slice(cap);
@@ -3083,7 +4787,7 @@ async function runDiscovery(opts = {}) {
     logger.info(`Discovery: ingested ${ingested}/${toIngest.length} candidate(s).`);
     return {
       enqueued,
-      gated: pending.length,
+      gated: pending2.length,
       passed: scored.length,
       ingested,
       droppedToNextRun: deferred.length
@@ -3177,14 +4881,580 @@ var init_format = __esm({
   }
 });
 
+// src/cli/planView.ts
+var planView_exports = {};
+__export(planView_exports, {
+  renderPlanHtml: () => renderPlanHtml
+});
+function esc(s) {
+  return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+}
+function slotRows(plan) {
+  return plan.slots.map((s) => {
+    const rec = s.recommended;
+    const name = rec ? rec.repoUrl ? `<a href="${esc(rec.repoUrl)}" target="_blank" rel="noreferrer">${esc(rec.name)}</a>` : esc(rec.name) : '<span class="muted">\u2014 no match \u2014</span>';
+    const alts = s.alternatives.map((a) => esc(a.name)).join(", ") || '<span class="muted">\u2014</span>';
+    return `<tr>
+        <td>${esc(s.need)}</td>
+        <td><span class="layer">${esc(s.layer)}</span></td>
+        <td class="pkg">${name}</td>
+        <td class="num">${rec ? rec.healthScore : "\u2014"}</td>
+        <td>${rec ? esc(rec.confidence) : "\u2014"}</td>
+        <td class="alts">${alts}</td>
+      </tr>`;
+  }).join("\n");
+}
+function renderPlanHtml(plan) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>lurq plan \u2014 roadmap</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, sans-serif;
+         background: #0b0b0f; color: #e7e7ea; padding: 2.5rem clamp(1rem, 5vw, 4rem); }
+  h1 { font-size: 1.5rem; margin: 0 0 .25rem; }
+  h2 { font-size: 1rem; text-transform: uppercase; letter-spacing: .08em; color: #9a9aa6; margin: 2.5rem 0 .75rem; }
+  .sub { color: #9a9aa6; margin: 0 0 1rem; max-width: 70ch; }
+  .diagram { background: #141419; border: 1px solid #26262e; border-radius: 14px; padding: 1.5rem; overflow: auto; }
+  table { width: 100%; border-collapse: collapse; margin-top: .5rem; }
+  th, td { text-align: left; padding: .55rem .75rem; border-bottom: 1px solid #1e1e25; vertical-align: top; }
+  th { font-size: .78rem; text-transform: uppercase; letter-spacing: .05em; color: #9a9aa6; }
+  .pkg a { color: #d98cff; text-decoration: none; } .pkg a:hover { text-decoration: underline; }
+  .num { text-align: right; font-variant-numeric: tabular-nums; }
+  .muted { color: #6a6a76; } .alts { color: #b8b8c2; font-size: .92rem; }
+  .layer { font-size: .8rem; color: #8ad; background: #15202b; border-radius: 6px; padding: .1rem .45rem; }
+  footer { margin-top: 2.5rem; color: #6a6a76; font-size: .85rem; }
+</style>
+</head>
+<body>
+  <h1>lurq plan <span class="muted">\xB7 ${esc(plan.optimize)} \xB7 ${esc(plan.source)}${plan.framework ? ` \xB7 ${esc(plan.framework)} ecosystem` : ""}</span></h1>
+  <p class="sub">${esc(plan.note)}</p>
+
+  <h2>Roadmap</h2>
+  <div class="diagram"><pre class="mermaid">${esc(plan.mermaid)}</pre></div>
+
+  <h2>Components</h2>
+  <table>
+    <thead><tr><th>Component</th><th>Layer</th><th>Recommended</th><th>Health</th><th>Confidence</th><th>Alternatives</th></tr></thead>
+    <tbody>
+${slotRows(plan)}
+    </tbody>
+  </table>
+
+  <footer>data as of ${esc(plan.dataAsOf)} \xB7 generated by lurq</footer>
+
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: true, theme: 'dark' });
+  </script>
+</body>
+</html>
+`;
+}
+var init_planView = __esm({
+  "src/cli/planView.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
+// src/db/watch.ts
+import { eq as eq8 } from "drizzle-orm";
+async function getWatchCursor(db, id) {
+  const rows = await db.select({ seq: watchState.seq }).from(watchState).where(eq8(watchState.id, id)).limit(1);
+  return rows[0]?.seq ?? null;
+}
+async function setWatchCursor(db, id, seq) {
+  await db.insert(watchState).values({ id, seq, updatedAt: /* @__PURE__ */ new Date() }).onConflictDoUpdate({ target: watchState.id, set: { seq, updatedAt: /* @__PURE__ */ new Date() } });
+}
+var init_watch = __esm({
+  "src/db/watch.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_schema();
+  }
+});
+
+// src/pipeline/watch.ts
+var watch_exports = {};
+__export(watch_exports, {
+  parseChangeLine: () => parseChangeLine,
+  watchNpmChanges: () => watchNpmChanges
+});
+function parseChangeLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    const obj = JSON.parse(trimmed);
+    if (typeof obj?.id !== "string" || obj.seq == null) return null;
+    return { seq: obj.seq, id: obj.id, deleted: Boolean(obj.deleted) };
+  } catch {
+    return null;
+  }
+}
+async function watchNpmChanges(db, opts = {}) {
+  const { signal } = opts;
+  let backoff2 = 1e3;
+  while (!signal?.aborted) {
+    let tracked = new Set(await getAllPackageNames(db));
+    let trackedAt = Date.now();
+    const since = await getWatchCursor(db, FEED_ID) ?? opts.since ?? "now";
+    const url = `${FEED_URL}?feed=continuous&since=${encodeURIComponent(since)}&heartbeat=${HEARTBEAT_MS}`;
+    logger.info(`watch: connecting from seq=${since} (${tracked.size} tracked packages)`);
+    try {
+      const res = await fetch(url, { signal });
+      if (!res.ok || !res.body) throw new Error(`feed responded ${res.status}`);
+      backoff2 = 1e3;
+      let sinceCheckpoint = 0;
+      for await (const line of ndjsonLines(res.body, signal)) {
+        const change = parseChangeLine(line);
+        if (!change) continue;
+        const seq = String(change.seq);
+        sinceCheckpoint++;
+        if (Date.now() - trackedAt > TRACKED_REFRESH_MS) {
+          tracked = new Set(await getAllPackageNames(db));
+          trackedAt = Date.now();
+        }
+        if (!change.deleted && tracked.has(change.id)) {
+          logger.info(`watch: re-syncing ${change.id} (seq=${seq})`);
+          await syncOnePackage(db, change.id).catch(
+            (err) => logger.warn(`watch: re-sync failed for ${change.id}: ${String(err)}`)
+          );
+          await setWatchCursor(db, FEED_ID, seq);
+          sinceCheckpoint = 0;
+        } else if (sinceCheckpoint >= CHECKPOINT_EVERY) {
+          await setWatchCursor(db, FEED_ID, seq);
+          sinceCheckpoint = 0;
+        }
+      }
+      logger.info("watch: feed stream ended; reconnecting");
+    } catch (err) {
+      if (signal?.aborted) break;
+      logger.warn(`watch: ${String(err)} \u2014 retrying in ${backoff2}ms`);
+      await sleep(backoff2, signal);
+      backoff2 = Math.min(backoff2 * 2, MAX_BACKOFF_MS);
+    }
+  }
+}
+async function* ndjsonLines(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal?.aborted) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let nl;
+      while ((nl = buffer.indexOf("\n")) >= 0) {
+        yield buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+var FEED_ID, FEED_URL, HEARTBEAT_MS, TRACKED_REFRESH_MS, CHECKPOINT_EVERY, MAX_BACKOFF_MS;
+var init_watch2 = __esm({
+  "src/pipeline/watch.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_logger();
+    init_packages();
+    init_watch();
+    init_single();
+    FEED_ID = "npm-changes";
+    FEED_URL = "https://replicate.npmjs.com/_changes";
+    HEARTBEAT_MS = 3e4;
+    TRACKED_REFRESH_MS = 5 * 6e4;
+    CHECKPOINT_EVERY = 200;
+    MAX_BACKOFF_MS = 3e4;
+  }
+});
+
+// src/sandbox/types.ts
+var DEFAULT_TARGET;
+var init_types2 = __esm({
+  "src/sandbox/types.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_TARGET = {
+      node: "20",
+      moduleSystem: "cjs"
+    };
+  }
+});
+
+// src/sandbox/local.ts
+import { execFile } from "child_process";
+import { mkdtemp, rm, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+import { promisify } from "util";
+function npmInstallArgs(specs, opts) {
+  const bad = specs.find((s) => s.startsWith("-"));
+  if (bad) throw new Error(`Invalid package spec: ${bad}`);
+  const args = ["install", ...specs, "--no-audit", "--no-fund", "--no-package-lock", "--no-save"];
+  if (!opts.allowScripts) args.push("--ignore-scripts");
+  return args;
+}
+function smokeScript(pkg, moduleSystem) {
+  return moduleSystem === "esm" ? ["--input-type=module", "-e", `await import(${JSON.stringify(pkg)})`] : ["-e", `require(${JSON.stringify(pkg)})`];
+}
+function condense(s) {
+  return s.replace(/\s+/g, " ").trim().slice(0, ERROR_MAX);
+}
+function stderrOf(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    if (typeof e.stderr === "string" && e.stderr.trim()) return e.stderr;
+    if (typeof e.message === "string") return e.message;
+  }
+  return String(err);
+}
+var execFileAsync, INSTALL_TIMEOUT_MS, SMOKE_TIMEOUT_MS, ERROR_MAX, toSpec, LocalSandbox;
+var init_local = __esm({
+  "src/sandbox/local.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_types2();
+    execFileAsync = promisify(execFile);
+    INSTALL_TIMEOUT_MS = 12e4;
+    SMOKE_TIMEOUT_MS = 3e4;
+    ERROR_MAX = 500;
+    toSpec = (p) => p.version ? `${p.name}@${p.version}` : p.name;
+    LocalSandbox = class {
+      name = "local";
+      async verify(pkg, version, opts = {}) {
+        const set = await this.verifySet([{ name: pkg, version }], opts);
+        return {
+          driver: this.name,
+          moduleSystem: set.moduleSystem,
+          installed: set.installed,
+          imported: set.loaded[0]?.loaded ?? null,
+          ranScripts: opts.allowScripts ?? false,
+          durationMs: set.durationMs,
+          error: set.error
+        };
+      }
+      async verifySet(packages2, opts = {}) {
+        const target = opts.target ?? DEFAULT_TARGET;
+        const allowScripts = opts.allowScripts ?? false;
+        const specs = packages2.map(toSpec);
+        const dir = await mkdtemp(join3(tmpdir(), "lurq-sandbox-"));
+        const started = Date.now();
+        const loaded = packages2.map((p) => ({ name: p.name, loaded: null }));
+        let installed = false;
+        let error = null;
+        try {
+          await writeFile2(
+            join3(dir, "package.json"),
+            JSON.stringify({ name: "lurq-sandbox", version: "0.0.0", private: true })
+          );
+          await execFileAsync("npm", npmInstallArgs(specs, { allowScripts }), {
+            cwd: dir,
+            timeout: opts.timeoutMs ?? INSTALL_TIMEOUT_MS,
+            signal: opts.signal
+          });
+          installed = true;
+          for (let i = 0; i < packages2.length; i++) {
+            try {
+              await execFileAsync("node", smokeScript(packages2[i].name, target.moduleSystem), {
+                cwd: dir,
+                timeout: SMOKE_TIMEOUT_MS,
+                signal: opts.signal
+              });
+              loaded[i].loaded = true;
+            } catch (err) {
+              loaded[i].loaded = false;
+              if (!error) error = condense(stderrOf(err));
+            }
+          }
+        } catch (err) {
+          error = condense(stderrOf(err));
+        } finally {
+          await rm(dir, { recursive: true, force: true }).catch(() => {
+          });
+        }
+        return {
+          driver: this.name,
+          moduleSystem: target.moduleSystem,
+          installed,
+          loaded,
+          durationMs: Date.now() - started,
+          error
+        };
+      }
+    };
+  }
+});
+
+// src/sandbox/e2b.ts
+var e2b_exports = {};
+__export(e2b_exports, {
+  E2BSandbox: () => E2BSandbox,
+  installCommand: () => installCommand,
+  shQuote: () => shQuote,
+  smokeCommand: () => smokeCommand
+});
+import Sandbox from "e2b";
+function shQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function installCommand(specs, allowScripts) {
+  const bad = specs.find((s) => s.startsWith("-"));
+  if (bad) throw new Error(`Invalid package spec: ${bad}`);
+  const flags = ["--no-audit", "--no-fund", "--no-package-lock", "--no-save"];
+  if (!allowScripts) flags.push("--ignore-scripts");
+  return `npm install ${specs.map(shQuote).join(" ")} ${flags.join(" ")}`;
+}
+function smokeCommand(pkg, moduleSystem) {
+  const js = moduleSystem === "esm" ? `await import(${JSON.stringify(pkg)})` : `require(${JSON.stringify(pkg)})`;
+  const flags = moduleSystem === "esm" ? "--input-type=module " : "";
+  return `node ${flags}-e ${shQuote(js)}`;
+}
+function condense2(s) {
+  return s.replace(/\s+/g, " ").trim().slice(0, ERROR_MAX2);
+}
+function errText(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    if (typeof e.stderr === "string" && e.stderr.trim()) return e.stderr;
+    if (typeof e.message === "string") return e.message;
+  }
+  return String(err);
+}
+var INSTALL_TIMEOUT_MS2, SMOKE_TIMEOUT_MS2, ERROR_MAX2, WORKDIR, toSpec2, E2BSandbox;
+var init_e2b = __esm({
+  "src/sandbox/e2b.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_config();
+    init_types2();
+    INSTALL_TIMEOUT_MS2 = 12e4;
+    SMOKE_TIMEOUT_MS2 = 3e4;
+    ERROR_MAX2 = 500;
+    WORKDIR = "/home/user";
+    toSpec2 = (p) => p.version ? `${p.name}@${p.version}` : p.name;
+    E2BSandbox = class {
+      name = "e2b";
+      async verify(pkg, version, opts = {}) {
+        const set = await this.verifySet([{ name: pkg, version }], opts);
+        return {
+          driver: this.name,
+          moduleSystem: set.moduleSystem,
+          installed: set.installed,
+          imported: set.loaded[0]?.loaded ?? null,
+          ranScripts: opts.allowScripts ?? false,
+          durationMs: set.durationMs,
+          error: set.error
+        };
+      }
+      async verifySet(packages2, opts = {}) {
+        const config = getConfig();
+        const target = opts.target ?? DEFAULT_TARGET;
+        const allowScripts = opts.allowScripts ?? false;
+        const specs = packages2.map(toSpec2);
+        const installTimeout = opts.timeoutMs ?? INSTALL_TIMEOUT_MS2;
+        const started = Date.now();
+        const loaded = packages2.map((p) => ({ name: p.name, loaded: null }));
+        let installed = false;
+        let error = null;
+        const install = installCommand(specs, allowScripts);
+        const createOpts = {
+          apiKey: config.E2B_API_KEY,
+          timeoutMs: installTimeout + SMOKE_TIMEOUT_MS2 * packages2.length + 3e4
+        };
+        const sandbox = config.E2B_TEMPLATE ? await Sandbox.create(config.E2B_TEMPLATE, createOpts) : await Sandbox.create(createOpts);
+        try {
+          await sandbox.files.write(
+            `${WORKDIR}/package.json`,
+            JSON.stringify({ name: "lurq-sandbox", version: "0.0.0", private: true })
+          );
+          await sandbox.commands.run(install, { cwd: WORKDIR, timeoutMs: installTimeout });
+          installed = true;
+          for (let i = 0; i < packages2.length; i++) {
+            try {
+              await sandbox.commands.run(smokeCommand(packages2[i].name, target.moduleSystem), {
+                cwd: WORKDIR,
+                timeoutMs: SMOKE_TIMEOUT_MS2
+              });
+              loaded[i].loaded = true;
+            } catch (err) {
+              loaded[i].loaded = false;
+              if (!error) error = condense2(errText(err));
+            }
+          }
+        } catch (err) {
+          error = condense2(errText(err));
+        } finally {
+          await sandbox.kill().catch(() => {
+          });
+        }
+        return {
+          driver: this.name,
+          moduleSystem: target.moduleSystem,
+          installed,
+          loaded,
+          durationMs: Date.now() - started,
+          error
+        };
+      }
+    };
+  }
+});
+
+// src/sandbox/index.ts
+async function getSandbox() {
+  if (getConfig().E2B_API_KEY) {
+    const { E2BSandbox: E2BSandbox2 } = await Promise.resolve().then(() => (init_e2b(), e2b_exports));
+    return new E2BSandbox2();
+  }
+  return new LocalSandbox();
+}
+var init_sandbox = __esm({
+  "src/sandbox/index.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_config();
+    init_local();
+    init_types2();
+    init_local();
+  }
+});
+
+// src/pipeline/sandbox.ts
+var sandbox_exports = {};
+__export(sandbox_exports, {
+  verifyPackageInSandbox: () => verifyPackageInSandbox
+});
+async function verifyPackageInSandbox(db, pkg, version, opts = {}) {
+  const result = await (await getSandbox()).verify(pkg, version, opts);
+  await storeVerificationRun(db, {
+    packageName: pkg,
+    version: version ?? "latest",
+    driver: result.driver,
+    moduleSystem: result.moduleSystem,
+    installed: result.installed,
+    imported: result.imported,
+    ranScripts: result.ranScripts,
+    durationMs: result.durationMs,
+    error: result.error,
+    ranAt: /* @__PURE__ */ new Date()
+  }).catch(() => {
+  });
+  return result;
+}
+var init_sandbox2 = __esm({
+  "src/pipeline/sandbox.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_verification();
+    init_sandbox();
+  }
+});
+
+// src/pipeline/compat.ts
+var compat_exports = {};
+__export(compat_exports, {
+  deriveCompatEdges: () => deriveCompatEdges,
+  verifyCompatibility: () => verifyCompatibility
+});
+function deriveCompatEdges(resolved, result) {
+  const allLoaded = result.loaded.every((l) => l.loaded === true);
+  const edges = [];
+  if (result.installed && allLoaded) {
+    for (let i = 0; i < resolved.length; i++) {
+      for (let j = i + 1; j < resolved.length; j++) {
+        edges.push({
+          a: resolved[i].name,
+          aVersion: resolved[i].version,
+          b: resolved[j].name,
+          bVersion: resolved[j].version,
+          status: "compatible"
+        });
+      }
+    }
+  } else if (resolved.length === 2) {
+    edges.push({
+      a: resolved[0].name,
+      aVersion: resolved[0].version,
+      b: resolved[1].name,
+      bVersion: resolved[1].version,
+      status: "conflict"
+    });
+  }
+  return edges;
+}
+async function verifyCompatibility(db, packages2, opts = {}) {
+  const resolved = await Promise.all(
+    packages2.map(async (name) => ({
+      name,
+      version: (await getPackageByName(db, name))?.latestVersion ?? "latest"
+    }))
+  );
+  const result = await (await getSandbox()).verifySet(
+    resolved.map((r) => ({ name: r.name, version: r.version === "latest" ? null : r.version })),
+    { allowScripts: opts.allowScripts }
+  );
+  const edges = deriveCompatEdges(resolved, result);
+  for (const e of edges) {
+    const pair = canonicalPair(
+      { name: e.a, version: e.aVersion },
+      { name: e.b, version: e.bVersion }
+    );
+    await upsertCompatEdge(db, {
+      ...pair,
+      status: e.status,
+      driver: result.driver,
+      ranAt: /* @__PURE__ */ new Date()
+    }).catch(() => {
+    });
+  }
+  const failed = !result.installed || !result.loaded.every((l) => l.loaded === true);
+  return { result, edges, unattributedConflict: failed && edges.length === 0 };
+}
+var init_compat2 = __esm({
+  "src/pipeline/compat.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_compat();
+    init_packages();
+    init_sandbox();
+  }
+});
+
 // src/cli/commands.ts
 var commands_exports = {};
 __export(commands_exports, {
   runCompare: () => runCompare,
+  runCompat: () => runCompat,
   runEditWeights: () => runEditWeights,
   runEvaluate: () => runEvaluate,
+  runPlan: () => runPlan,
   runRecommend: () => runRecommend,
+  runSandbox: () => runSandbox,
   runVerify: () => runVerify,
+  runVersions: () => runVersions,
+  runWatch: () => runWatch,
   runWeights: () => runWeights
 });
 async function withDb(fn) {
@@ -3257,6 +5527,12 @@ async function runEvaluate(pkg, opts) {
         ["repo", res.repoUrl ?? "\u2014"]
       ])
     );
+    if (res.buildVerified) {
+      const bv = res.buildVerified;
+      const state = !bv.installed ? red("install failed") : bv.loaded === false ? yellow("installs, load failed") : green("installs and loads");
+      console.log(`
+sandbox: ${state}  ${dim(`${bv.version} \xB7 ${bv.driver}`)}`);
+    }
     if (res.summary) console.log("\n" + res.summary);
     if (res.usageGuide) {
       const g = res.usageGuide;
@@ -3301,9 +5577,9 @@ not found: ${res.missing.join(", ")}`));
 }
 function runWeights(opts = {}) {
   const w = loadWeights();
-  const active = activeWeightsPath();
+  const active2 = activeWeightsPath();
   if (opts.json) {
-    console.log(JSON.stringify({ ...w, source: active?.source ?? "defaults" }, null, 2));
+    console.log(JSON.stringify({ ...w, source: active2?.source ?? "defaults" }, null, 2));
     return;
   }
   const pct = (n) => n.toFixed(2);
@@ -3330,13 +5606,15 @@ function runWeights(opts = {}) {
     ])
   );
   console.log(dim(`
-Source: ${active ? `${active.source} (${active.path})` : "defaults (no user overrides)"}`));
+Source: ${active2 ? `${active2.source} (${active2.path})` : "defaults (no user overrides)"}`));
 }
-function runEditWeights(opts) {
+async function runEditWeights(opts) {
+  const { invalidateCache: invalidateCache2 } = await Promise.resolve().then(() => (init_cache(), cache_exports));
   if (opts.reset) {
     const removed = resetWeights();
     console.log(removed.length ? `Removed overrides:
   ${removed.join("\n  ")}` : "No overrides to remove; already on defaults.");
+    if (removed.length) await invalidateCache2();
     return;
   }
   if (opts.explain) {
@@ -3352,6 +5630,7 @@ function runEditWeights(opts) {
     const next = applyOverrides(loadWeights(), opts.set);
     const { weights, normalized } = validateWeights(next);
     const path2 = saveWeights(weights, opts.project ? "project" : "user");
+    await invalidateCache2();
     console.log(`Saved overrides to ${path2}`);
     if (normalized) {
       console.log(
@@ -3365,11 +5644,83 @@ function runEditWeights(opts) {
 `));
   runWeights(opts);
 }
+async function openInBrowser(target) {
+  const { spawn } = await import("child_process");
+  const [cmd, args] = process.platform === "darwin" ? ["open", [target]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", target]] : ["xdg-open", [target]];
+  spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+}
+async function runPlan(file, opts) {
+  const { readFileSync: readFileSync4 } = await import("fs");
+  let document;
+  try {
+    document = readFileSync4(file, "utf8");
+  } catch {
+    throw new Error(`Could not read "${file}".`);
+  }
+  if (opts.optimize && opts.optimize !== "speed" && opts.optimize !== "balanced") {
+    throw new Error("--optimize must be 'speed' or 'balanced'.");
+  }
+  await withDb(async (db) => {
+    const { handlePlan: handlePlan2 } = await Promise.resolve().then(() => (init_plan(), plan_exports));
+    const res = await handlePlan2(db, {
+      document,
+      optimize: opts.optimize
+    });
+    if (opts.json) return console.log(JSON.stringify(res, null, 2));
+    if (!("slots" in res)) {
+      console.log(res.note);
+      return;
+    }
+    if (opts.html || opts.open) {
+      const { writeFileSync: writeFileSync3 } = await import("fs");
+      const { tmpdir: tmpdir2 } = await import("os");
+      const { join: join5 } = await import("path");
+      const { renderPlanHtml: renderPlanHtml2 } = await Promise.resolve().then(() => (init_planView(), planView_exports));
+      const out = opts.html ?? join5(tmpdir2(), `lurq-plan-${Date.now()}.html`);
+      writeFileSync3(out, renderPlanHtml2(res), "utf8");
+      console.log(`Roadmap written to ${out}`);
+      if (opts.open) await openInBrowser(out);
+    }
+    console.log(
+      table(
+        ["Component", "Layer", "Recommended", "Health", "Confidence", "Alternatives"],
+        res.slots.map((s) => [
+          s.need.length > 32 ? s.need.slice(0, 31) + "\u2026" : s.need,
+          s.layer,
+          s.recommended ? `${s.recommended.name}@${s.recommended.latestVersion ?? "?"}` : dim("\u2014"),
+          s.recommended ? String(s.recommended.healthScore) : "\u2014",
+          s.recommended ? confidenceLabel(s.recommended.confidence) : "\u2014",
+          s.alternatives.map((a) => a.name).join(", ") || "\u2014"
+        ])
+      )
+    );
+    if (res.unmatched.length) console.log(yellow(`
+No match for: ${res.unmatched.join(", ")}`));
+    if (res.compatibility) {
+      const c = res.compatibility;
+      const col = c.overall === "compatible" ? green : c.overall === "conflict" ? red : dim;
+      console.log("\n" + bold("Compatibility: ") + col(c.overall));
+      for (const s of res.slots) {
+        if (s.swappedFrom && s.recommended) {
+          console.log(green(`  \u2713 swapped ${s.swappedFrom} \u2192 ${s.recommended.name} for compatibility`));
+        }
+      }
+      for (const cf of c.conflicts) console.log(red(`  \u2717 ${cf.detail} (no compatible alternative)`));
+      if (c.unverified.length) console.log(dim(`  unverified: ${c.unverified.join(", ")}`));
+    }
+    console.log("\n" + bold("Roadmap (Mermaid):"));
+    console.log(res.mermaid);
+    console.log(dim(`
+${res.note}`));
+    console.log(dim(`data as of ${formatDate(res.dataAsOf)}`));
+  });
+}
 async function runVerify(pkg, opts) {
   await withDb(async (db) => {
     const res = await handleVerify(db, { package: pkg });
     if (opts.json) return console.log(JSON.stringify(res, null, 2));
-    const verdict = !res.exists ? red("\u2717 NOT FOUND on npm") : res.deprecated || res.archived || res.advisoryCount > 0 ? yellow("\u26A0 exists, but risky") : green("\u2713 looks safe");
+    const riskColor = res.risk === "high" ? red : res.risk === "medium" ? yellow : green;
+    const verdict = !res.exists ? red("\u2717 NOT FOUND on npm") : res.risk === "high" ? red("\u2717 high supply-chain risk") : res.risk === "medium" ? yellow("\u26A0 exists, but risky") : green("\u2713 looks safe");
     console.log(`${bold(pkg)}  ${verdict}`);
     console.log(
       detail([
@@ -3377,11 +5728,107 @@ async function runVerify(pkg, opts) {
         ["weekly dl", formatNumber(res.weeklyDownloads)],
         ["confidence", res.confidence ? confidenceLabel(res.confidence) : "\u2014"],
         ["advisories", String(res.advisoryCount)],
+        ["risk", riskColor(res.risk)],
         ["risk flags", res.riskFlags.length ? yellow(res.riskFlags.join(", ")) : "none"]
       ])
     );
   });
 }
+async function runVersions(pkg, opts) {
+  const limit = opts.limit ? Math.max(1, parseInt(opts.limit, 10) || 30) : 30;
+  await withDb(async (db) => {
+    const versions = await getPackageVersions(db, pkg, limit);
+    if (opts.json) return console.log(JSON.stringify(versions, null, 2));
+    if (versions.length === 0) {
+      console.log(`No stored versions for ${bold(pkg)}. Run \`lurq sync --package ${pkg}\` first.`);
+      return;
+    }
+    console.log(bold(pkg));
+    console.log(
+      table(
+        ["Version", "Published"],
+        versions.map((v) => [
+          v.version,
+          v.publishedAt ? v.publishedAt.toISOString().slice(0, 10) : "\u2014"
+        ])
+      )
+    );
+  });
+}
+async function runWatch() {
+  const { watchNpmChanges: watchNpmChanges2 } = await Promise.resolve().then(() => (init_watch2(), watch_exports));
+  await withDb(async (db) => {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    console.log(dim("watching npm for releases of tracked packages \u2014 Ctrl-C to stop"));
+    try {
+      await watchNpmChanges2(db, { signal: controller.signal });
+    } finally {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+    }
+  });
+}
+async function runSandbox(pkg, version, opts) {
+  if (opts.allowScripts) {
+    console.error(
+      yellow("warning: running install scripts and loading the package locally without isolation")
+    );
+  }
+  const { verifyPackageInSandbox: verifyPackageInSandbox2 } = await Promise.resolve().then(() => (init_sandbox2(), sandbox_exports));
+  await withDb(async (db) => {
+    const result = await verifyPackageInSandbox2(db, pkg, version ?? null, {
+      target: { node: "20", moduleSystem: opts.esm ? "esm" : "cjs" },
+      allowScripts: opts.allowScripts
+    });
+    if (opts.json) return console.log(JSON.stringify(result, null, 2));
+    const ok = result.installed && result.imported !== false;
+    const label = version ? `${pkg}@${version}` : pkg;
+    const verdict = ok ? green("\u2713 installs and loads") : red("\u2717 failed");
+    console.log(`${bold(label)}  ${verdict}  ${dim(`(${result.durationMs}ms \xB7 ${result.driver})`)}`);
+    console.log(
+      detail([
+        ["installed", result.installed ? "yes" : "no"],
+        ["loaded", result.imported === null ? "\u2014" : result.imported ? "yes" : "no"],
+        ["module", result.moduleSystem],
+        ["scripts", result.ranScripts ? "ran" : "skipped"],
+        ["error", result.error ?? "none"]
+      ])
+    );
+  });
+}
+async function runCompat(pkgs, opts) {
+  await withDb(async (db) => {
+    if (opts.run) {
+      console.error(
+        yellow("co-installing in the sandbox (loads package code locally without isolation)")
+      );
+      const { verifyCompatibility: verifyCompatibility2 } = await Promise.resolve().then(() => (init_compat2(), compat_exports));
+      await verifyCompatibility2(db, pkgs);
+    }
+    const { handleCompat: handleCompat2 } = await Promise.resolve().then(() => (init_handlers(), handlers_exports));
+    const res = await handleCompat2(db, { packages: pkgs });
+    if (opts.json) return console.log(JSON.stringify(res, null, 2));
+    const color = res.overall === "compatible" ? green : res.overall === "conflict" ? red : dim;
+    console.log(`${bold(res.packages.join(" + "))}  ${color(res.overall)}`);
+    if (res.conflicts.length) {
+      console.log(
+        table(
+          ["Source", "Detail"],
+          res.conflicts.map((c) => [c.source, c.detail])
+        )
+      );
+    } else if (res.overall === "compatible") {
+      console.log(dim("no peer-dependency or engine conflicts across the set"));
+    }
+    if (res.unverified.length) {
+      console.log(dim(`
+unverified (no metadata): ${res.unverified.join(", ")}`));
+    }
+  });
+}
 var init_commands = __esm({
   "src/cli/commands.ts"() {
     "use strict";
@@ -3389,6 +5836,7 @@ var init_commands = __esm({
     init_config();
     init_types();
     init_client();
+    init_packages();
     init_handlers();
     init_weights();
     init_weights();
@@ -3414,9 +5862,9 @@ __export(installSkill_exports, {
 import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import { copyFileSync } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname4, join as join3 } from "path";
+import { dirname as dirname4, join as join4 } from "path";
 function home(...p) {
-  return join3(homedir3(), ...p);
+  return join4(homedir3(), ...p);
 }
 function agentSpecs() {
   return [
@@ -3550,10 +5998,10 @@ function installAgent(spec, mode) {
   }
 }
 function installInstructionsFile() {
-  const src = join3(packageRoot(), "templates", "skill-instructions.md");
+  const src = join4(packageRoot(), "templates", "skill-instructions.md");
   if (!existsSync4(src)) return null;
   const destDir = home(".lurq");
-  const dest = join3(destDir, "skill-instructions.md");
+  const dest = join4(destDir, "skill-instructions.md");
   mkdirSync2(destDir, { recursive: true });
   copyFileSync(src, dest);
   return dest;
@@ -3654,9 +6102,11 @@ async function validateKey(url, apiKey) {
       },
       body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" })
     });
-    return res.ok;
+    if (res.ok) return "valid";
+    if (res.status === 401 || res.status === 403) return "invalid";
+    return "unreachable";
   } catch {
-    return false;
+    return "unreachable";
   }
 }
 async function runInstallWizard(opts) {
@@ -3664,7 +6114,7 @@ async function runInstallWizard(opts) {
   const url = opts.url ?? process.env.LURQ_ENDPOINT ?? DEFAULT_ENDPOINT;
   let apiKey = (opts.apiKey ?? process.env.LURQ_API_KEY)?.trim();
   if (interactive) {
-    const { input, checkbox, confirm } = await import("@inquirer/prompts");
+    const { input, checkbox, confirm, select } = await import("@inquirer/prompts");
     console.log("\n  lurq \u2014 connect your coding agent to the hosted package index.\n");
     if (!apiKey) {
       console.log(`  Need a key? Get one at ${GET_KEY_URL}
@@ -3675,11 +6125,13 @@ async function runInstallWizard(opts) {
       })).trim();
     }
     process.stdout.write("  Validating key\u2026 ");
-    const ok = await validateKey(url, apiKey);
-    console.log(ok ? "ok" : "could not reach endpoint");
-    if (!ok) {
+    const check = await validateKey(url, apiKey);
+    console.log(
+      check === "valid" ? "ok" : check === "invalid" ? "rejected" : "could not reach endpoint"
+    );
+    if (check !== "valid") {
       const proceed = await confirm({
-        message: `Couldn't validate the key against ${url}. Continue anyway?`,
+        message: check === "invalid" ? `That key was rejected (401) by ${url}. Continue anyway?` : `Couldn't reach ${url} to validate the key. Continue anyway?`,
         default: false
       });
       if (!proceed) {
@@ -3687,22 +6139,45 @@ async function runInstallWizard(opts) {
         return;
       }
     }
-    let selected2;
     if (opts.agent) {
-      selected2 = resolveAgents(opts.agent);
-    } else {
-      const specs = agentSpecs();
-      const ids = await checkbox({
-        message: "Which assistant(s) should I configure?",
-        choices: specs.map((s) => ({
-          name: `${s.label}${s.detected ? " (detected)" : ""}`,
-          value: s.id,
-          checked: s.detected
-        }))
+      await finish(resolveAgents(opts.agent), { url, apiKey });
+      return;
+    }
+    const specs = agentSpecs();
+    const detected = specs.filter((s) => s.detected);
+    const primary = detected.find((s) => s.id === "claude-code") ?? detected[0];
+    if (primary) {
+      const others = detected.length - 1;
+      const choice = await select({
+        message: others > 0 ? `Looks like you have ${detected.map((s) => s.label).join(", ")}. Connect lurq to them?` : `Looks like you have ${primary.label}. Connect lurq to it?`,
+        default: "yes",
+        choices: [
+          {
+            name: others > 0 ? `Yes \u2014 set up all ${detected.length} detected agents` : `Yes \u2014 set up ${primary.label} for me`,
+            value: "yes"
+          },
+          { name: "No \u2014 let me choose which agent(s)", value: "other" },
+          { name: "Cancel \u2014 change nothing", value: "cancel" }
+        ]
       });
-      selected2 = specs.filter((s) => ids.includes(s.id));
+      if (choice === "cancel") {
+        console.log("No problem \u2014 nothing was changed. Run `lurq install` again anytime.");
+        return;
+      }
+      if (choice === "yes") {
+        await finish(detected, { url, apiKey });
+        return;
+      }
     }
-    await finish(selected2, { url, apiKey });
+    const ids = await checkbox({
+      message: "Which assistant(s) should I configure?",
+      choices: specs.map((s) => ({
+        name: `${s.label}${s.detected ? " (detected)" : ""}`,
+        value: s.id,
+        checked: s.detected
+      }))
+    });
+    await finish(specs.filter((s) => ids.includes(s.id)), { url, apiKey });
     return;
   }
   if (!apiKey) {
@@ -3742,7 +6217,8 @@ var keys_exports = {};
 __export(keys_exports, {
   runKeysCreate: () => runKeysCreate,
   runKeysList: () => runKeysList,
-  runKeysRevoke: () => runKeysRevoke
+  runKeysRevoke: () => runKeysRevoke,
+  runKeysRotate: () => runKeysRotate
 });
 function waitForEnter(prompt) {
   return new Promise((resolve) => {
@@ -3754,28 +6230,55 @@ function waitForEnter(prompt) {
     });
   });
 }
+async function presentNewKey(key, row, opts) {
+  if (opts.json) {
+    console.log(
+      JSON.stringify({ key, prefix: row.prefix, tier: row.tier, label: row.label, ...opts.extraJson })
+    );
+    return;
+  }
+  const meta = `prefix=${row.prefix}  tier=${row.tier}${row.label ? `  label=${row.label}` : ""}`;
+  const block = [bold(opts.header ?? "API key created."), "", `  ${green(key)}`, "", dim(meta)];
+  console.log(block.join("\n"));
+  if (process.stdout.isTTY && process.stdin.isTTY) {
+    await waitForEnter(dim("Copy it now, then press Enter to erase it from the terminal\u2026 "));
+    process.stdout.write(`\x1B[${block.length + 1}F\x1B[0J\x1B[3J`);
+    console.log(
+      dim(`New key (prefix ${row.prefix}) erased from the terminal. It is stored only as a hash and cannot be recovered, so make sure you saved it.`)
+    );
+  } else {
+    console.log(dim("Store it now \u2014 shown only once, stored hashed, cannot be recovered."));
+  }
+}
 async function runKeysCreate(opts) {
   requireConfig(["DATABASE_URL"]);
   const { db, close } = createDb({ max: 1 });
   try {
-    const { key, row } = await createKey(db, { label: opts.label, tier: opts.tier });
-    if (opts.json) {
-      console.log(JSON.stringify({ key, prefix: row.prefix, tier: row.tier, label: row.label }));
+    const { key, row } = await createKey(db, {
+      label: opts.label,
+      tier: opts.tier,
+      ownerId: opts.owner
+    });
+    await presentNewKey(key, row, opts);
+  } finally {
+    await close();
+  }
+}
+async function runKeysRotate(prefixOrId, opts) {
+  requireConfig(["DATABASE_URL"]);
+  const { db, close } = createDb({ max: 1 });
+  try {
+    const result = await rotateKey(db, prefixOrId);
+    if (!result) {
+      logger.warn(`No active key matched "${prefixOrId}".`);
+      process.exitCode = 1;
       return;
     }
-    const meta = `prefix=${row.prefix}  tier=${row.tier}${row.label ? `  label=${row.label}` : ""}`;
-    const block = [bold("API key created."), "", `  ${green(key)}`, "", dim(meta)];
-    const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
-    console.log(block.join("\n"));
-    if (interactive) {
-      await waitForEnter(dim("Copy it now, then press Enter to erase it from the terminal\u2026 "));
-      process.stdout.write(`\x1B[${block.length + 1}F\x1B[0J\x1B[3J`);
-      console.log(
-        dim(`API key created (prefix ${row.prefix}) \u2014 value erased from the terminal. It is stored only as a hash and cannot be recovered, so make sure you saved it.`)
-      );
-    } else {
-      console.log(dim("Store it now \u2014 shown only once, stored hashed, cannot be recovered."));
-    }
+    await presentNewKey(result.key, result.row, {
+      json: opts.json,
+      header: `API key rotated \u2014 replaces ${result.previous.prefix} (now revoked).`,
+      extraJson: { replaced: result.previous.prefix }
+    });
   } finally {
     await close();
   }
@@ -3856,7 +6359,7 @@ var init_keys = __esm({
 
 // src/db/seed.ts
 import { readFileSync as readFileSync3 } from "fs";
-import { sql as sql7 } from "drizzle-orm";
+import { sql as sql5 } from "drizzle-orm";
 import { z as z3 } from "zod";
 function loadSeedFile(path2 = seedJsonPath()) {
   const raw = JSON.parse(readFileSync3(path2, "utf8"));
@@ -3873,7 +6376,7 @@ async function loadSeedPackages(db, path2) {
   await db.insert(seedPackages).values(entries.map((e) => ({ name: e.name, category: e.category ?? null }))).onConflictDoUpdate({
     target: seedPackages.name,
     // Refresh category to the incoming value on conflict (EXCLUDED.category).
-    set: { category: sql7`excluded.category` }
+    set: { category: sql5`excluded.category` }
   });
   logger.info(`Loaded ${entries.length} packages into seed_packages.`);
   return entries.length;
@@ -3994,13 +6497,21 @@ function buildProgram() {
     const { runVerify: runVerify2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     await runVerify2(pkg, opts);
   });
+  program.command("versions").argument("<package>", "npm package name").description("show the stored version timeline for a package").option("--json", "output JSON instead of a table").option("-n, --limit <n>", "how many versions to show (default 30)").action(async (pkg, opts) => {
+    const { runVersions: runVersions2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+    await runVersions2(pkg, opts);
+  });
+  program.command("plan").argument("<file>", "path to a markdown file describing your program").description("turn a program description into an evidence-scored package plan + roadmap").option("--optimize <mode>", "ranking bias: 'speed' (lightest bundle) or 'balanced'").option("--html <path>", "write the roadmap as a self-contained HTML visualization").option("--open", "render the roadmap to HTML and open it in your browser").option("--json", "output the full plan as JSON").action(async (file, opts) => {
+    const { runPlan: runPlan2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+    await runPlan2(file, opts);
+  });
   program.command("weights").description("show and explain the scoring weight model (health, quality, composite \u03BB)").option("--json", "output the weight model as JSON").action(async (opts) => {
     const { runWeights: runWeights2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
     runWeights2(opts);
   });
   program.command("edit-weights").description("override, reset, or explain the scoring weights (layered over defaults)").option("--set <pair>", "override key=value, e.g. composite.lambda=0.5 (repeatable)", (v, acc) => acc.concat(v), []).option("--reset", "remove all overrides and restore defaults").option("--explain <component>", "explain a component (e.g. adoption, quality, lambda)").option("--project", "write to project-local .lurq/weights.json instead of the user config").action(async (opts) => {
     const { runEditWeights: runEditWeights2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
-    runEditWeights2(opts);
+    await runEditWeights2(opts);
   });
   program.command("discover").description("operator-side: proactively crawl for new packages and queue/gate them (\xA72B)").option("--cap <n>", "max candidates to fully ingest this run", (v) => parseInt(v, 10)).option("--dry-run", "discover, queue, and gate, but do not ingest survivors").option("--json", "output the discovery summary as JSON").action(async (opts) => {
     const { requireConfig: requireConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
@@ -4016,6 +6527,24 @@ function buildProgram() {
     const summary = await runRescore2();
     if (opts.json) console.log(JSON.stringify(summary, null, 2));
   });
+  program.command("watch").description(
+    "operator-side: follow the npm changes feed, re-syncing tracked packages on new releases"
+  ).action(async () => {
+    const { runWatch: runWatch2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+    await runWatch2();
+  });
+  program.command("sandbox").argument("<package>", "npm package name").argument("[version]", "specific version (default: latest)").description(
+    "operator-side: install + smoke-load a package in a sandbox to verify it actually works"
+  ).option("--esm", "load via ESM import instead of CJS require").option("--allow-scripts", "run install scripts (UNSAFE without VM isolation)").option("--json", "output JSON").action(
+    async (pkg, version, opts) => {
+      const { runSandbox: runSandbox2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+      await runSandbox2(pkg, version, opts);
+    }
+  );
+  program.command("compat").argument("<packages...>", "npm package names to check together").description("check pairwise compatibility of packages from the sandbox matrix").option("--run", "operator-side: co-install them in the sandbox first (UNSAFE without VM isolation)").option("--json", "output JSON").action(async (pkgs, opts) => {
+    const { runCompat: runCompat2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+    await runCompat2(pkgs, opts);
+  });
   program.command("install").description("guided setup: connect lurq to your AI assistant(s)").option("--api-key <key>", "hosted API key (skips the prompt)").option("--url <url>", "hosted endpoint URL (defaults to the lurq service)").option("--agent <agent>", "claude-code | cursor | copilot | windsurf | codex | all").option("--yes", "non-interactive: use flags/env and detected agents without prompting").action(async (opts) => {
     const { runInstallWizard: runInstallWizard2 } = await Promise.resolve().then(() => (init_install(), install_exports));
     await runInstallWizard2(opts);
@@ -4029,7 +6558,7 @@ function buildProgram() {
     await runInstallSkill2(opts);
   });
   const keys = program.command("keys").description("manage API keys for the hosted service (operator; needs DATABASE_URL)");
-  keys.command("create").description("create a new API key (shown once; erased from the terminal after you copy it)").option("--label <label>", "human label (owner / org / purpose)").option("--tier <tier>", "tier name", "free").option("--json", "print the key as JSON and skip the interactive erase (for scripts)").action(async (opts) => {
+  keys.command("create").description("create a new API key (shown once; erased from the terminal after you copy it)").option("--label <label>", "human label (owner / org / purpose)").option("--tier <tier>", "tier name", "free").option("--owner <id>", "org/owner id to attribute this key to (e.g. a Clerk org id)").option("--json", "print the key as JSON and skip the interactive erase (for scripts)").action(async (opts) => {
     const { runKeysCreate: runKeysCreate2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
     await runKeysCreate2(opts);
   });
@@ -4037,6 +6566,10 @@ function buildProgram() {
     const { runKeysList: runKeysList2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
     await runKeysList2(opts);
   });
+  keys.command("rotate").argument("<prefixOrId>", "key prefix (e.g. lurq_live_ab12cd) or numeric id to replace").description("issue a replacement key (same label/tier) and revoke the old one").option("--json", "print the new key as JSON and skip the interactive erase (for scripts)").action(async (prefixOrId, opts) => {
+    const { runKeysRotate: runKeysRotate2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
+    await runKeysRotate2(prefixOrId, opts);
+  });
   keys.command("revoke").argument("<prefixOrId>", "key prefix (e.g. lurq_live_ab12cd) or numeric id").description("revoke an API key").action(async (prefixOrId) => {
     const { runKeysRevoke: runKeysRevoke2 } = await Promise.resolve().then(() => (init_keys(), keys_exports));
     await runKeysRevoke2(prefixOrId);