add Exa MCP guidance for OpenCode search

Wire in Exa by default and teach Sam how to explain search failures so users can recover with their own Exa account and API key.

Author: bensenescu

.opencode/agents/seo-guide.md

@@ -70,3 +70,11 @@ If the user wants DataForSEO but it is not available in the current session:
 - Record that answer in `MEMORY.md`.
 - Read `docs/dataforseo-mcp-setup.md` before explaining the setup steps, and reference `https://app.dataforseo.com/api-access` when telling the user where to find their API login and password.
 - Do not present DataForSEO as active until its MCP tools are actually available.
+
+### Harness Specific Notes
+
+- In OpenCode, do not imply that web search is built in. Search in this workspace depends on Exa MCP.
+- Other search providers can also work in this harness, including Firecrawl or DuckDuckGo-based tools, but Exa is the preferred default for Sam.
+- If Exa-backed search tools are missing, disabled, or returning auth or rate-limit errors, read `docs/exa-seup.md` before replying.
+- When Exa search fails in OpenCode, explain that the shared free Exa limit is the likely cause and point the user to `docs/exa-seup.md` for the account and API key setup flow.
+- Do not claim that Exa search is available when the Exa MCP tools are unavailable or erroring.

AGENTS.md

@@ -32,6 +32,7 @@ Substantial draft work means a new full draft, a full-article rewrite, or struct
 - `docs/article-writing.md`
 - `docs/article-review.md`
 - `docs/dataforseo-mcp-setup.md`
+- `docs/exa-seup.md`
 - `context/user-notes.md`
 - `context/site-profile.md`
 - `context/brand-voice.md`

docs/exa-seup.md

@@ -0,0 +1,101 @@
+# Exa Setup For OpenCode
+
+Use this guide when search is failing in OpenCode or the Exa tools are missing in this workspace.
+
+## What is happening
+
+- OpenCode does not ship with native web search.
+- In this workspace, Sam uses Exa through MCP for web search, code search, and page crawling.
+- The checked-in `opencode.jsonc` uses Exa's shared free remote MCP endpoint so search works out of the box for many users.
+- If searches start failing, the most likely cause is that the shared free limit has been exhausted or your current Exa access is rate limited.
+
+## Recommended fix
+
+1. Create an Exa account.
+2. Generate your own API key.
+3. Export `EXA_API_KEY` before launching OpenCode.
+4. Use your key in a personal OpenCode config override, or update the project config if that is what you want.
+5. Restart OpenCode and try the search again.
+
+## Expected usage
+
+- Exa provides some free usage without requiring an account.
+- After signup, Exa also gives new users about `$10` of free usage.
+- If you are mainly using Exa for Sam, you will probably never go through that free usage.
+
+## Current workspace config
+
+This repository enables Exa in `opencode.jsonc` with the shared endpoint:
+
+```jsonc
+{
+  "mcp": {
+    "exa": {
+      "type": "remote",
+      "url": "https://mcp.exa.ai/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Personal API key setup
+
+The safest upgrade path is to keep the shared repo config as-is and add your own authenticated Exa config in your personal OpenCode config.
+
+OpenCode config files are merged, so a personal override can replace the URL locally without changing the checked-in project file.
+
+Use this URL when you want OpenCode to send your own Exa API key:
+
+```jsonc
+{
+  "mcp": {
+    "exa": {
+      "type": "remote",
+      "url": "https://mcp.exa.ai/mcp?exaApiKey={env:EXA_API_KEY}",
+      "enabled": true
+    }
+  }
+}
+```
+
+You can place that in `~/.config/opencode/opencode.json` or another local OpenCode config override.
+
+## Export the API key
+
+macOS/Linux:
+
+```bash
+export EXA_API_KEY="your_exa_api_key"
+opencode
+```
+
+Windows PowerShell:
+
+```powershell
+$env:EXA_API_KEY = "your_exa_api_key"
+opencode
+```
+
+If OpenCode is already running, restart it after exporting the variable.
+
+## Where to get the key
+
+- Create or sign in to your Exa account.
+- Open the Exa dashboard.
+- Create or copy an API key for your account.
+
+Reference docs:
+
+- Exa MCP docs: <https://docs.exa.ai/docs/reference/exa-mcp>
+- Exa pricing: <https://exa.ai/pricing>
+- OpenCode MCP docs: <https://dev.opencode.ai/docs/mcp-servers>
+
+## What Sam should say when search fails
+
+If search tools are erroring in OpenCode, Sam should explain:
+
+- OpenCode does not have native search built in.
+- This workspace uses Exa for search.
+- The shared free Exa limit is the likely reason for the failure.
+- The user should follow this doc to add their own Exa account and API key.

opencode.jsonc

@@ -4,7 +4,14 @@
 	"instructions": [
 		"MEMORY.md",
 		"context/user-notes.md"
-	]
+	],
+	"mcp": {
+		"exa": {
+			"type": "remote",
+			"url": "https://mcp.exa.ai/mcp",
+			"enabled": true
+		}
+	}
 	// "agent": {
 	//   "build": {
 	//     "disable": true,

tests/agent-sync.test.mjs

@@ -50,10 +50,15 @@ function parseFrontmatter(content) {
   );
 }
 
+function stripHarnessSpecificNotes(content) {
+  return content.replace(/(?:^|\n)#{2,6} Harness Specific Notes\n[\s\S]*$/, '');
+}
+
 function normalizeBody(content) {
   const normalizedLineEndings = content.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
   const withoutFrontmatter = stripFrontmatter(normalizedLineEndings);
-  const withoutTrailingWhitespace = withoutFrontmatter
+  const withoutHarnessSpecificNotes = stripHarnessSpecificNotes(withoutFrontmatter);
+  const withoutTrailingWhitespace = withoutHarnessSpecificNotes
     .split('\n')
     .map((line) => line.replace(/[ \t]+$/g, ''))
     .join('\n');