migrate to settings.json

README.md

@@ -79,21 +79,36 @@ Research Flow:
 
 ## Configuration
 
-Deep Research reads Firecrawl configuration from `~/.pi/agent/settings.json`:
+Deep Research reads Firecrawl configuration from pi's settings.json files, with the following resolution order (later wins):
+
+1. Environment variables (`FIRECRAWL_BASE_URL`, `FIRECRAWL_API_KEY`)
+2. Global settings (`$agentDir/settings.json`) → `firecrawl.*`
+3. Project settings (`.pi/settings.json`) → `firecrawl.*`
+4. Default `http://localhost:3002` (if nothing else sets baseUrl)
+
+The agent directory (`$agentDir`) defaults to `~/.pi/agent` and respects the `PI_CODING_AGENT_DIR` environment variable.
+
+**Global settings** (`~/.pi/agent/settings.json`):
 
 ```json
 {
   "firecrawl": {
     "baseUrl": "http://localhost:3002",
+  }
+}
+```
+
+**Project settings** (`.pi/settings.json` — overrides global):
+
+```json
+{
+  "firecrawl": {
+    "baseUrl": "https://firecrawl.team.internal"
     "apiKey": "your-api-key"
   }
 }
 ```
 
-Environment variables are also supported:
-- `FIRECRAWL_BASE_URL` — overrides the Firecrawl endpoint (default: `http://localhost:3002`)
-- `FIRECRAWL_API_KEY` — API key for authenticated Firecrawl instances
-
 ### Session startup check
 
 On `session_start`, the extension checks whether the Firecrawl endpoint is reachable. If not, it shows a warning notification so you know searches will fail before you try to use it.

index.ts

@@ -585,7 +585,7 @@ export default function (pi: ExtensionAPI) {
 		const reachable = await isFirecrawlReachable();
 		if (!reachable) {
 			ctx.ui.notify(
-				"Deep Research: Firecrawl endpoint unreachable — searches will fail. Check FIRECRAWL_BASE_URL in settings.json or env.",
+				"Deep Research: Firecrawl endpoint unreachable — searches will fail. Set firecrawl.baseUrl in settings.json (global or project) or the FIRECRAWL_BASE_URL env var.",
 				"warning",
 			);
 		}

src/firecrawl.ts

@@ -6,32 +6,53 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as os from "node:os";
 import type { SearchResult, EnrichedSearchResult, ContentType } from "./types";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 /* ── Config ──────────────────────────────────────────────────────── */
 
+/**
+ * Read and merge Firecrawl settings from pi's settings.json files.
+ *
+ * Resolution order (later wins):
+ *   1. env vars FIRECRAWL_BASE_URL / FIRECRAWL_API_KEY
+ *   2. global ~/.pi/agent/settings.json → firecrawl.*
+ *   3. project .pi/settings.json → firecrawl.*
+ *   4. default http://localhost:3002 (if no baseUrl configured)
+ */
 function loadFirecrawlConfig() {
-	const settingsPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+	// Start with env var defaults
-	try {
+	let baseUrl = process.env.FIRECRAWL_BASE_URL ?? "http://localhost:3002";
-		const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+	let apiKey = process.env.FIRECRAWL_API_KEY;
-		const fc = settings.firecrawl ?? {};
+
-		return {
+	const agentDir = getAgentDir();
-			baseUrl: (
+
-				fc.baseUrl ??
+	// Helper: read a settings.json and merge its firecrawl.* keys
-				process.env.FIRECRAWL_BASE_URL ??
+	const tryReadSettings = (settingsPath: string): void => {
-				"http://localhost:3002"
+		try {
-			).replace(/\/+$/, ""),
+			const raw = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-			apiKey: fc.apiKey ?? process.env.FIRECRAWL_API_KEY,
+			const fc: Record<string, string | undefined> = raw.firecrawl ?? {};
-		};
+			if (typeof fc.baseUrl === "string" && fc.baseUrl.length > 0) {
-	} catch {
+				baseUrl = fc.baseUrl;
-		return {
+			}
-			baseUrl: (
+			if (typeof fc.apiKey === "string" && fc.apiKey.length > 0) {
-				process.env.FIRECRAWL_BASE_URL ?? "http://localhost:3002"
+				apiKey = fc.apiKey;
-			).replace(/\/+$/, ""),
+			}
-			apiKey: process.env.FIRECRAWL_API_KEY,
+		} catch {
-		};
+			// File missing or unparseable — skip
-	}
+		}
+	};
+
+	// 1. Global settings
+	tryReadSettings(path.join(agentDir, "settings.json"));
+
+	// 2. Project settings (override global)
+	tryReadSettings(path.join(process.cwd(), ".pi", "settings.json"));
+
+	return {
+		baseUrl: baseUrl.replace(/\/+$/, ""),
+		apiKey,
+	};
 }
 
 const { baseUrl: BASE_URL, apiKey: API_KEY } = loadFirecrawlConfig();