@adityanair98/api-oracle 0.5.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ An MCP server that gives Claude Code the ability to find, evaluate, and recommen
 
 When a developer asks *"what should I use to send emails?"* — API Oracle returns a structured recommendation with working code, honest gotchas, pricing details, and everything needed to get started immediately.
 
-[![CI](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml/badge.svg)](https://github.com/adityanair/api-oracle/actions/workflows/ci.yml)
+[![CI](https://github.com/adityanair98/api-oracle/actions/workflows/ci.yml/badge.svg)](https://github.com/adityanair98/api-oracle/actions/workflows/ci.yml)
 
 ---
 
@@ -49,35 +49,57 @@ When a developer asks *"what should I use to send emails?"* — API Oracle retur
 
 ## Quick Start
 
-### Option A — npx (no install)
+API Oracle runs as a local MCP server over stdio. There's no setup step. The 68 bundled entries are loaded into an in-memory database when the server starts, and nothing is written to your working directory.
+
+### Claude Code
+
+```bash
+claude mcp add api-oracle -- npx -y @adityanair98/api-oracle serve
+```
+
+This adds the server to the current project (local scope). To make it available in every project, use `--scope user`:
 
 ```bash
-npx @adityanair98/api-oracle serve
+claude mcp add --scope user api-oracle -- npx -y @adityanair98/api-oracle serve
 ```
 
-### Option B — global install
+To check that it's registered, run `claude mcp list`, or `/mcp` inside Claude Code.
+
+On native Windows (not WSL), wrap `npx` with `cmd /c`:
 
 ```bash
-npm install -g @adityanair98/api-oracle
-api-oracle serve
+claude mcp add api-oracle -- cmd /c npx -y @adityanair98/api-oracle serve
 ```
 
-### Connect to Claude Code
+### Claude Desktop
 
-Add to `~/.claude/claude_desktop_config.json` under `mcpServers`:
+Claude Desktop reads its MCP servers from `claude_desktop_config.json`. (Claude Code doesn't use this file.)
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the server under `mcpServers`, then restart Claude Desktop:
 
 ```json
 {
   "mcpServers": {
     "api-oracle": {
       "command": "npx",
-      "args": ["@adityanair98/api-oracle", "serve"]
+      "args": ["-y", "@adityanair98/api-oracle", "serve"]
     }
   }
 }
 ```
 
-Restart Claude Code. The `api-oracle` server will appear in your MCP servers list.
+### Run it directly
+
+```bash
+npx -y @adityanair98/api-oracle serve       # MCP server on stdio (what the clients above launch)
+npx -y @adityanair98/api-oracle dashboard   # web dashboard at http://localhost:3737
+npx -y @adityanair98/api-oracle --help
+```
+
+Or install it globally with `npm install -g @adityanair98/api-oracle`, then run `api-oracle serve`.
 
 ---
 
@@ -105,18 +127,19 @@ Dashboard features:
 ### 1. Clone and install
 
 ```bash
-git clone https://github.com/adityanair/api-oracle.git
+git clone https://github.com/adityanair98/api-oracle.git
 cd api-oracle
 npm install
 ```
 
-### 2. Build and seed
+### 2. Build
 
 ```bash
 npm run build
-npm run seed
 ```
 
+No seeding step is needed: entries are loaded from `src/entries/` at startup.
+
 ### 3. Run
 
 ```bash
@@ -131,10 +154,11 @@ node dist/cli.js dashboard
 
 ```bash
 npm run dev            # Run MCP server with tsx (no build needed)
-npm test               # Run all tests (160 tests)
+npm test               # Run all tests (228 tests)
 npm run validate       # Validate all JSON entries + cross-references
 npm run lint-entries   # Content quality linter (0 errors, 15 warnings)
 npm run e2e            # End-to-end query scenarios (43 assertions)
+npm run eval           # Retrieval accuracy on the dev and held-out query sets
 npm run dashboard      # Start dashboard with tsx
 ```
 
@@ -144,8 +168,8 @@ npm run dashboard      # Start dashboard with tsx
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DB_PATH` | `./data/api-oracle.db` | SQLite database path |
-| `PORT` | `3737` | Dashboard server port |
+| `DB_PATH` | _(unset)_: in-memory | Optional SQLite file. If it's unset, the bundled entries are loaded into memory at startup. If it's set, they're upserted into that file and other rows are kept. |
+| `PORT` | `3737` | Dashboard server port (`0` picks any free port; the banner shows the one in use) |
 | `LOG_LEVEL` | `info` | Log level: debug \| info \| warn \| error |
 
 ---
@@ -155,7 +179,7 @@ npm run dashboard      # Start dashboard with tsx
 1. Create `src/entries/<category>/<slug>.json`
 2. Fill in all schema fields (see `docs/adding-apis.md`)
 3. `npm run validate` — verify schema and cross-references
-4. `npm run seed` — load into database
+4. Restart the server. Entries are loaded at startup.
 5. `npm test` — run tests
 
 See [docs/adding-apis.md](docs/adding-apis.md) for the full guide and JSON template.
@@ -177,10 +201,12 @@ src/
 ├── knowledge/            # Core logic
 │   ├── schema.ts         # Zod schema + TypeScript types
 │   ├── db.ts             # SQLite CRUD (better-sqlite3)
+│   ├── loader.ts         # Loads + validates bundled entries at startup
+│   ├── relevance.ts      # Query relevance: IDF-weighted coverage, phrases
 │   ├── search.ts         # Search pipeline orchestration
-│   ├── scorer.ts         # Weighted multi-factor ranking engine
+│   ├── scorer.ts         # Relevance-gated ranking (relevance × prior)
 │   ├── synonyms.ts       # Query expansion + category detection
-│   └── tfidf.ts          # TF-IDF in-memory search index
+│   └── tfidf.ts          # TF-IDF index (candidate pre-selection for large KBs)
 ├── updater/              # Freshness and quality system
 │   ├── staleness.ts      # Staleness level detection
 │   ├── report.ts         # Freshness report builder
@@ -199,16 +225,42 @@ src/
 
 ## How Search Works
 
-1. **Phrase detection** — extracts `preferFree`, `preferOpenSource`, etc. from natural language
-2. **Synonym expansion** — "crashes" → error tracking; "log in" → auth; "billing" → payments
-3. **Category detection** — maps query to a category with confidence score
-4. **TF-IDF candidate selection** — field-weighted index pre-ranks all 68 entries
-5. **Multi-factor scoring** — useCaseFit (40%) + quality (25%) + devExperience (20%) + pricingFit (15%)
-6. **Category boost** — entries in the detected category receive up to 12% score boost
-7. **Confidence** — top result gets a 0–1 confidence score
+Relevance gates the score. An API's quality, developer experience, pricing and freshness can adjust its rank among relevant APIs, but they can't make an unrelated API show up.
+
+1. **Relevance.** This is the IDF-weighted share of your request's words that an entry covers. It checks the entry's name, subcategory, `bestFor` and use cases, with the description counting less. Rare words like "transcription" count more than common ones like "users". Synonyms count partially, and word order counts too, so "speech to text" and "text to speech" give different results.
+2. **Category fit.** The request is mapped to a category (email, payments, …). APIs in unrelated categories are down-weighted.
+3. **Prior.** A weighted mean of quality score, developer experience, pricing fit and recency. It scales a score between 0.75× and 1.0× of its relevance: `score = relevance × (0.75 + 0.25 × prior)`. If you name an API ("firebase", "send emails with resend"), a small keyword term ranks that API above entries that merely mention it.
+4. **Gate.** Candidates below a minimum relevance, below 60% of the best candidate's relevance, or in a clearly unrelated category are dropped.
+5. **Response.** `find_best_api` returns the top result with quick-start code, up to 2 alternatives, and `candidates`: up to 5 relevant APIs with key facts and relevance scores, so the calling model can make the final choice. `totalEvaluated` is the number of entries scored.
 
 See [docs/scoring-logic.md](docs/scoring-logic.md) for full details.
 
+## Accuracy
+
+`npm run eval` measures retrieval on two query sets in `tests/eval/`. **dev** (26 queries) is the tuning set. **holdout** (42 queries) was written before the scorer was changed and is never tuned on.
+
+| Scorer | Set | Top-1 | Top-3 | Must-not violations |
+|--------|-----|-------|-------|---------------------|
+| v0.5.0 | dev | 80.8% | 96.2% | 38.1% |
+| v0.5.0 | holdout | **38.1%** | 71.4% | 31.0% |
+| v0.6.0 | dev | 96.2% | 100% | 0.0% |
+| v0.6.0 | holdout | **92.9%** | 95.2% | 2.4% |
+
+"Must-not violations" is the share of queries with a must-not list (21 of 26 dev queries, all 42 holdout queries) where a clearly wrong API appeared in the top 3. Earlier versions of this project reported 20/20 queries passing. That was measured on the same queries the weights were tuned on, and the held-out top-1 for that scorer was 38.1%.
+
+Caveats: the holdout labels were written from the entries' own descriptions and use cases, which is also what the scorer matches on. Real-world phrasing is likely to score lower. With 42 queries, each one is worth about 2.4 percentage points. Full per-query results are in [`tests/eval/results/`](tests/eval/results/).
+
+## Data freshness
+
+Every entry has a `lastVerified` date: the last time someone checked its pricing, limits and SDK details against the provider's own docs. Dates are only changed when an entry is actually re-verified. Nothing updates them automatically.
+
+- `find_best_api` returns `lastVerified` for every API it lists. For the recommendation it also returns `freshness` (`lastVerified`, `daysSinceVerified`, `level`), plus a `freshnessNote` when the entry isn't fresh.
+- Levels: **fresh** < 90 days, **aging** 90–180, **stale** 180–365, **critical** > 365.
+- Recency is a small part of the ranking prior (full credit within 30 days, falling to zero at 365 days).
+- `check_api_freshness` (MCP tool), `npm run refresh-report` and the dashboard list entries that need re-verification.
+
+As of v0.6.0, all 68 entries were last verified on 2026-02-25, so they report as **stale**. Check pricing and limits on the provider's site before relying on them.
+
 ---
 
 ## License

package/dist/cli.js

@@ -9,11 +9,12 @@
  *   api-oracle --version   — Print version
  */
 import { createRequire } from "module";
-import { initDb } from "./knowledge/db.js";
-import { config } from "./utils/config.js";
+import { bootstrapKnowledgeBase } from "./knowledge/loader.js";
 const require = createRequire(import.meta.url);
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-require-imports
 const pkg = require("../package.json");
+/** The one-line Claude Code setup command (package name from package.json) */
+const CLAUDE_CODE_CMD = `claude mcp add api-oracle -- npx -y ${pkg.name} serve`;
 const HELP = `
   API Oracle — MCP server for API discovery and recommendations
 
@@ -29,15 +30,27 @@ const HELP = `
     --version    Show version
 
   Environment variables:
-    DB_PATH      Path to SQLite database (default: ./data/api-oracle.db)
-    PORT         Dashboard port (default: 3737)
+    DB_PATH      Optional SQLite file to use. By default the bundled entries
+                 are loaded into an in-memory database at startup and no
+                 file is written. If set, bundled entries are upserted into it.
+    PORT         Dashboard port (default: 3737; 0 picks any free port)
     LOG_LEVEL    Log level: debug | info | warn | error (default: info)
 
-  Example Claude Code configuration (~/.claude/claude_desktop_config.json):
+  Add to Claude Code:
+    ${CLAUDE_CODE_CMD}
+    For every project, add --scope user right after "claude mcp add".
+    On native Windows (not WSL), put "cmd /c" before npx.
+    Check it with: claude mcp list
+
+  Add to Claude Desktop — edit claude_desktop_config.json
+  (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json,
+   Windows: %APPDATA%\\Claude\\claude_desktop_config.json):
     {
-      "api-oracle": {
-        "command": "npx",
-        "args": ["@adityanair98/api-oracle", "serve"]
+      "mcpServers": {
+        "api-oracle": {
+          "command": "npx",
+          "args": ["-y", "${pkg.name}", "serve"]
+        }
       }
     }
 `.trimStart();
@@ -53,14 +66,14 @@ async function main() {
         process.exit(0);
     }
     if (command === "dashboard") {
-        initDb(config.dbPath);
+        bootstrapKnowledgeBase();
         const { startDashboard } = await import("./dashboard/server.js");
         startDashboard();
         return;
     }
     if (command === "serve" || command === "") {
-        // Default: MCP server on stdio
-        initDb(config.dbPath);
+        // Default: MCP server on stdio. Load the bundled entries before serving.
+        bootstrapKnowledgeBase();
         const { startServer } = await import("./server.js");
         await startServer();
         return;

package/dist/dashboard/routes/api.js

@@ -216,7 +216,7 @@ apiRouter.post("/entries/:slug/verify", (req, res) => {
             slug,
             lastVerified: today,
             staleness,
-            note: `To persist: update lastVerified in src/entries/**/${slug}.json and run npm run seed`,
+            note: `To persist: update lastVerified in src/entries/**/${slug}.json and restart the server (entries are loaded at startup)`,
         });
     }
     catch (e) {

package/dist/dashboard/server.d.ts

@@ -6,4 +6,10 @@
  *
  * Exports: startDashboard
  */
-export declare function startDashboard(): void;
+import type { Server } from "http";
+/**
+ * Port from PORT (default 3737). 0 asks the OS for a free port; the banner
+ * prints the port actually bound. Returns null for an invalid value.
+ */
+export declare function resolveDashboardPort(raw?: string | undefined): number | null;
+export declare function startDashboard(): Server | null;

package/dist/dashboard/server.js

@@ -9,14 +9,33 @@
 import express from "express";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { initDb } from "../knowledge/db.js";
+import { getAllEntries } from "../knowledge/db.js";
+import { bootstrapKnowledgeBase } from "../knowledge/loader.js";
 import { config } from "../utils/config.js";
 import { createLogger } from "../utils/logger.js";
 import { apiRouter } from "./routes/api.js";
 const logger = createLogger("dashboard");
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3737;
+const DEFAULT_PORT = 3737;
+/**
+ * Port from PORT (default 3737). 0 asks the OS for a free port; the banner
+ * prints the port actually bound. Returns null for an invalid value.
+ */
+export function resolveDashboardPort(raw = process.env.PORT) {
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_PORT;
+    if (!/^\d+$/.test(raw.trim()))
+        return null;
+    const port = Number(raw.trim());
+    return port <= 65535 ? port : null;
+}
 export function startDashboard() {
+    const port = resolveDashboardPort();
+    if (port === null) {
+        logger.error(`Invalid PORT "${process.env.PORT ?? ""}": use a number from 0 to 65535.`);
+        process.exitCode = 1;
+        return null;
+    }
     const app = express();
     // Parse JSON bodies
     app.use(express.json());
@@ -25,21 +44,40 @@ export function startDashboard() {
     app.use(express.static(publicDir));
     // Mount REST API
     app.use("/api", apiRouter);
-    // Catch-all: serve index.html for client-side routing
-    app.get("*", (_req, res) => {
-        res.sendFile(join(publicDir, "index.html"));
+    // Catch-all: serve index.html for client-side routing.
+    // Express 5 (path-to-regexp v8) requires a named wildcard — a bare "*" throws at startup.
+    app.get("/{*splat}", (_req, res) => {
+        // Resolve relative to `root`: with an absolute path, send() refuses any
+        // dot-directory in it (npx installs under ~/.npm/_npx/…) and returns 404.
+        res.sendFile("index.html", { root: publicDir });
     });
-    app.listen(PORT, () => {
+    const entries = getAllEntries();
+    const categoryCount = new Set(entries.map((e) => e.category)).size;
+    // Express 5 passes listen errors (e.g. EADDRINUSE) to this callback instead
+    // of throwing. Ignoring them printed the "Local:" banner and then exited 0.
+    const server = app.listen(port, (err) => {
+        if (err) {
+            const code = err.code;
+            const hint = code === "EADDRINUSE"
+                ? ` Port ${port} is already in use. Stop the other process or set PORT, e.g. PORT=3738 api-oracle dashboard.`
+                : "";
+            logger.error(`Dashboard could not start: ${err.message}.${hint}`);
+            process.exitCode = 1;
+            return;
+        }
+        const address = server.address();
+        const boundPort = typeof address === "object" && address !== null ? address.port : port;
         process.stdout.write(`\n  API Oracle Dashboard\n`);
         process.stdout.write(`  ───────────────────────────────\n`);
-        process.stdout.write(`  Local:   http://localhost:${PORT}\n`);
-        process.stdout.write(`  Entries: 68 APIs across 23 categories\n\n`);
+        process.stdout.write(`  Local:   http://localhost:${boundPort}\n`);
+        process.stdout.write(`  Entries: ${entries.length} APIs across ${categoryCount} categories\n\n`);
     });
+    return server;
 }
 // When run directly (npm run dashboard)
 const isMain = process.argv[1] === fileURLToPath(import.meta.url);
 if (isMain) {
-    logger.info("Initializing database for dashboard", { dbPath: config.dbPath });
-    initDb(config.dbPath);
+    logger.info("Loading knowledge base for dashboard", { dbPath: config.dbPath });
+    bootstrapKnowledgeBase();
     startDashboard();
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Entry point — initializes the SQLite database and starts the MCP server.
+ * Entry point — loads the bundled knowledge base and starts the MCP server.
  * Run with: npm run dev (via tsx) or node dist/index.js (compiled).
  */
 export {};

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
- * Entry point — initializes the SQLite database and starts the MCP server.
+ * Entry point — loads the bundled knowledge base and starts the MCP server.
  * Run with: npm run dev (via tsx) or node dist/index.js (compiled).
  */
-import { initDb } from "./knowledge/db.js";
+import { bootstrapKnowledgeBase } from "./knowledge/loader.js";
 import { startServer } from "./server.js";
 import { config } from "./utils/config.js";
 import { logger } from "./utils/logger.js";
@@ -11,9 +11,8 @@ async function main() {
         dbPath: config.dbPath,
         nodeEnv: config.nodeEnv,
     });
-    // Initialize SQLite database (creates tables if they don't exist)
-    initDb(config.dbPath);
-    logger.info("Database initialized");
+    // Open the database and load the bundled entries (in-memory unless DB_PATH is set)
+    bootstrapKnowledgeBase();
     // Start the MCP server on stdio
     await startServer();
 }

package/dist/knowledge/db.d.ts

@@ -8,12 +8,22 @@
  */
 import Database from "better-sqlite3";
 import { type ApiEntry } from "./schema.js";
+/**
+ * Open the database. Defaults to an in-memory database — callers that want
+ * data must load it (see bootstrapKnowledgeBase in loader.ts).
+ */
 export declare function initDb(dbPath?: string): void;
 export declare function getDb(): Database.Database;
 export declare function closeDb(): void;
 /** Allows tests to inject their own in-memory database instance */
 export declare function _setDbForTesting(testDb: Database.Database): void;
 export declare function insertEntry(entry: ApiEntry): void;
+/**
+ * Insert or replace many entries in one transaction (quiet: one log line).
+ * Entries are re-validated; returns the number written.
+ */
+export declare function upsertEntries(entries: ApiEntry[]): number;
+export declare function countEntries(): number;
 export declare function getBySlug(slug: string): ApiEntry | null;
 export declare function getByCategory(category: string): ApiEntry[];
 export declare function searchByText(query: string): ApiEntry[];

package/dist/knowledge/db.js

@@ -83,14 +83,20 @@ function deserializeRow(row) {
     return result.data;
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
-export function initDb(dbPath = "./data/api-oracle.db") {
+/**
+ * Open the database. Defaults to an in-memory database — callers that want
+ * data must load it (see bootstrapKnowledgeBase in loader.ts).
+ */
+export function initDb(dbPath = ":memory:") {
     if (db)
         return; // already initialized
     if (dbPath !== ":memory:") {
         mkdirSync(dirname(dbPath), { recursive: true });
     }
     db = new Database(dbPath);
-    db.pragma("journal_mode = WAL");
+    if (dbPath !== ":memory:") {
+        db.pragma("journal_mode = WAL");
+    }
     db.pragma("foreign_keys = ON");
     db.exec(CREATE_TABLE_SQL);
     db.exec(CREATE_CATEGORY_INDEX_SQL);
@@ -129,6 +135,36 @@ export function insertEntry(entry) {
     stmt.run(row);
     logger.info("Inserted entry", { slug: entry.slug });
 }
+/**
+ * Insert or replace many entries in one transaction (quiet: one log line).
+ * Entries are re-validated; returns the number written.
+ */
+export function upsertEntries(entries) {
+    const database = getDb();
+    const rows = entries.map((entry) => {
+        const validation = validateEntry(entry);
+        if (!validation.success) {
+            throw new Error(`Invalid entry ${entry.slug}: ${validation.errors.join("; ")}`);
+        }
+        return serializeEntry(validation.data);
+    });
+    if (rows.length === 0)
+        return 0;
+    const columns = Object.keys(rows[0]);
+    const placeholders = columns.map((c) => `@${c}`).join(", ");
+    const stmt = database.prepare(`INSERT OR REPLACE INTO apis (${columns.join(", ")}) VALUES (${placeholders})`);
+    const writeAll = database.transaction((batch) => {
+        for (const row of batch)
+            stmt.run(row);
+    });
+    writeAll(rows);
+    logger.debug("Upserted entries", { count: rows.length });
+    return rows.length;
+}
+export function countEntries() {
+    const row = getDb().prepare("SELECT COUNT(*) AS n FROM apis").get();
+    return row.n;
+}
 export function getBySlug(slug) {
     const database = getDb();
     const row = database

package/dist/knowledge/loader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Knowledge-base loader — reads the bundled JSON entries that ship with the
+ * package (src/entries/<category>/<slug>.json), validates each one, and loads
+ * them into the SQLite database at startup.
+ *
+ * The entries directory is resolved relative to this compiled module
+ * (import.meta.url), never the process cwd, so running the package via npx
+ * works from any folder.
+ *
+ * Exports: resolveEntriesDir, loadEntriesFromDir, bootstrapKnowledgeBase,
+ *          LoadResult, SkippedEntry, BootstrapResult
+ */
+import { type ApiEntry } from "./schema.js";
+export interface SkippedEntry {
+    file: string;
+    reason: string;
+}
+export interface LoadResult {
+    dir: string;
+    entries: ApiEntry[];
+    skipped: SkippedEntry[];
+}
+export interface BootstrapResult {
+    dbPath: string;
+    entriesDir: string;
+    loaded: number;
+    skipped: SkippedEntry[];
+    totalInDb: number;
+}
+/**
+ * Absolute path of the bundled entries directory.
+ *
+ * This module lives two levels below the package root in both layouts:
+ *   <pkg>/dist/knowledge/loader.js   (compiled, what npm users run)
+ *   <pkg>/src/knowledge/loader.ts    (tsx, local development)
+ * and package.json "files" ships the entries at <pkg>/src/entries.
+ */
+export declare function resolveEntriesDir(): string;
+/**
+ * Read and validate every JSON entry under `dir`.
+ * Invalid JSON, schema failures and duplicate slugs are skipped (and reported),
+ * never thrown — one bad entry must not take the server down.
+ */
+export declare function loadEntriesFromDir(dir: string): LoadResult;
+/**
+ * Open the database and load the bundled entries into it.
+ *
+ * - Default (DB_PATH unset): an in-memory database, rebuilt on every start, so
+ *   no file is ever written to the user's working directory.
+ * - DB_PATH set explicitly: that file is opened and the bundled entries are
+ *   upserted into it (bundled data wins for matching slugs; other rows are kept).
+ */
+export declare function bootstrapKnowledgeBase(options?: {
+    dbPath?: string;
+    entriesDir?: string;
+}): BootstrapResult;

package/dist/knowledge/loader.js

@@ -0,0 +1,116 @@
+/**
+ * Knowledge-base loader — reads the bundled JSON entries that ship with the
+ * package (src/entries/<category>/<slug>.json), validates each one, and loads
+ * them into the SQLite database at startup.
+ *
+ * The entries directory is resolved relative to this compiled module
+ * (import.meta.url), never the process cwd, so running the package via npx
+ * works from any folder.
+ *
+ * Exports: resolveEntriesDir, loadEntriesFromDir, bootstrapKnowledgeBase,
+ *          LoadResult, SkippedEntry, BootstrapResult
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, relative } from "path";
+import { fileURLToPath } from "url";
+import { initDb, upsertEntries, countEntries } from "./db.js";
+import { validateEntry } from "./schema.js";
+import { resetTfIdfEngine } from "./tfidf.js";
+import { config } from "../utils/config.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("loader");
+/**
+ * Absolute path of the bundled entries directory.
+ *
+ * This module lives two levels below the package root in both layouts:
+ *   <pkg>/dist/knowledge/loader.js   (compiled, what npm users run)
+ *   <pkg>/src/knowledge/loader.ts    (tsx, local development)
+ * and package.json "files" ships the entries at <pkg>/src/entries.
+ */
+export function resolveEntriesDir() {
+    return fileURLToPath(new URL("../../src/entries/", import.meta.url));
+}
+function findJsonFiles(dir) {
+    const results = [];
+    for (const name of readdirSync(dir).sort()) {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) {
+            results.push(...findJsonFiles(full));
+        }
+        else if (name.endsWith(".json")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Read and validate every JSON entry under `dir`.
+ * Invalid JSON, schema failures and duplicate slugs are skipped (and reported),
+ * never thrown — one bad entry must not take the server down.
+ */
+export function loadEntriesFromDir(dir) {
+    if (!existsSync(dir)) {
+        throw new Error(`Entries directory not found: ${dir}`);
+    }
+    const entries = [];
+    const skipped = [];
+    const seen = new Map();
+    for (const file of findJsonFiles(dir)) {
+        const rel = relative(dir, file);
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(file, "utf-8"));
+        }
+        catch (e) {
+            skipped.push({ file: rel, reason: `invalid JSON: ${String(e)}` });
+            continue;
+        }
+        const validation = validateEntry(raw);
+        if (!validation.success) {
+            skipped.push({ file: rel, reason: `schema: ${validation.errors.slice(0, 3).join("; ")}` });
+            continue;
+        }
+        const entry = validation.data;
+        const firstFile = seen.get(entry.slug);
+        if (firstFile) {
+            skipped.push({ file: rel, reason: `duplicate slug "${entry.slug}" (already loaded from ${firstFile})` });
+            continue;
+        }
+        seen.set(entry.slug, rel);
+        entries.push(entry);
+    }
+    return { dir, entries, skipped };
+}
+/**
+ * Open the database and load the bundled entries into it.
+ *
+ * - Default (DB_PATH unset): an in-memory database, rebuilt on every start, so
+ *   no file is ever written to the user's working directory.
+ * - DB_PATH set explicitly: that file is opened and the bundled entries are
+ *   upserted into it (bundled data wins for matching slugs; other rows are kept).
+ */
+export function bootstrapKnowledgeBase(options = {}) {
+    const dbPath = options.dbPath ?? config.dbPath;
+    const entriesDir = options.entriesDir ?? resolveEntriesDir();
+    initDb(dbPath);
+    const { entries, skipped } = loadEntriesFromDir(entriesDir);
+    for (const s of skipped) {
+        logger.warn("Skipped invalid entry", s);
+    }
+    const loaded = upsertEntries(entries);
+    // The TF-IDF index is built lazily from the DB — force a rebuild.
+    resetTfIdfEngine();
+    const totalInDb = countEntries();
+    logger.info("Knowledge base loaded", {
+        loaded,
+        skipped: skipped.length,
+        totalInDb,
+        dbPath,
+    });
+    if (totalInDb === 0) {
+        logger.error("Knowledge base is empty — find_best_api will return no results", {
+            entriesDir,
+        });
+    }
+    return { dbPath, entriesDir, loaded, skipped, totalInDb };
+}